# Groups and labels

```{=html}
<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script>
MathJax = {
  tex: {
    inlineMath: [['$', '$'], ['\\(', '\\)']]
  },
  svg: {
    fontCache: 'global'
  }
};
</script>
```

```{r}
library(tinytable)
options(tinytable_tt_digits = 3)
options(tinytable_theme_placement_latex_float = "H")
x <- mtcars[1:4, 1:5]
```

The `group_tt()` function can label groups of rows (`i`) or columns (`j`).

## Rows

The `i` argument accepts a named list of integers. The numbers identify the positions where row group labels are to be inserted. The names includes the text that should be inserted:

```{r}
dat <- mtcars[1:9, 1:8]

tt(dat) |>
  group_tt(i = list(
    "I like (fake) hamburgers" = 3,
    "She prefers halloumi" = 4,
    "They love tofu" = 7))
```

The numbers in the `i` list indicate that a label must be inserted at position # in the original table (without row groups). For example,

```{r}
tt(head(iris)) |>
  group_tt(i = list("After 1" = 2, "After 2" = 3, "After 3" = 4, "After 5" = 6))

tt(head(iris)) |>
  group_tt(i = list("After 1a" = 2, "After 1b" = 2, "After 5" = 6))

tt(head(iris)) |>
  group_tt(i = list("After 0" = 1))
```

We can style group rows in the same way as regular rows:

```{r}
tt(dat) |> 
  group_tt(
    i = list(
      "I like (fake) hamburgers" = 3,
      "She prefers halloumi" = 4,
      "They love tofu" = 7)) |>
  style_tt(
    i = c(3, 5, 9),
    align = "c",
    color = "white",
    background = "gray",
    bold = TRUE)
```

### Automatic row groups

We can use the `group_tt()` function to group rows and label them using spanners (almost) automatically. For example,

```{r}
# subset and sort data
df <- mtcars |> head(10) |> sort_by(~ am)

# identify row indices
indices <- tapply(1:nrow(df), df$am, \(x) x[1], simplify = FALSE)

# draw table
tt(df) |> group_tt(i = indices)
```


## Columns

The syntax for column groups is very similar, but we use the `j` argument instead. The named list specifies the labels to appear in column-spanning labels, and the values must be a vector of consecutive and non-overlapping integers that indicate which columns are associated to which labels:

```{r}
tt(dat) |> 
  group_tt(
    j = list(
      "Hamburgers" = 1:3,
      "Halloumi" = 4:5,
      "Tofu" = 7))
```

Here is a table with both row and column headers, as well as some styling:

```{r}
dat <- mtcars[1:9, 1:8]
tt(dat) |> 
  group_tt(
    i = list("I like (fake) hamburgers" = 3,
             "She prefers halloumi" = 4,
             "They love tofu" = 7),
    j = list("Hamburgers" = 1:3,
             "Halloumi" = 4:5,
             "Tofu" = 7)) |>
  style_tt(
    i = c(3, 5, 9),
    align = "c",
    background = "teal",
    color = "white") |>
  style_tt(i = -1, color = "teal")
```

We can also stack several extra headers on top of one another:

```{r}
tt(x) |>
  group_tt(j = list("Foo" = 2:3, "Bar" = 5)) |>
  group_tt(j = list("Hello" = 1:2, "World" = 4:5))
```

