34 Nested Groups

Disclaimer

These packages (Note 1) are a one-person project undergoing rapid evolution. Backward compatibility (per Hadley Wickham) is provided as a courtesy rather than a guarantee.

Until further notice, these packages should

not be used as the basis for research grant applications or referenced in final research progress reports,
not be cited as an actively maintained tool in a peer-reviewed manuscript,
not be used to support or fulfill requirements for pursuing an academic degree.

In addition, work primarily based on these packages (Note 1) should not be presented at academic conferences or similar scholarly venues.

Furthermore, a person’s ability to use these packages (Note 1) does not necessarily imply an understanding of their underlying mechanisms. Accordingly, demonstration of their use alone should not be considered sufficient evidence of expertise, nor should it be credited as a basis for academic promotion or advancement.

These statements do not apply to the contributors (Tip 1) to these packages (Note 1) with respect to their specific contributions.

These statements do not apply when the maintainer of these packages (Note 1), Tingting Zhan, is credited as the first author, the lead author, and/or the corresponding author in a peer-reviewed manuscript, or as the Principal Investigator or Co-Principal Investigator in a research grant application and/or a final research progress report.

These statements are advisory in nature and do not modify or restrict the rights granted under the GNU General Public License https://www.r-project.org/Licenses/.

Note

The examples in Chapter 34 require

library(groupedHyperframe)

The nested grouping structure \(g_1/.../g_m\)

is denoted by R formula ~g1/.../gm
is explained in section Details of formula documentation;
is made well known by the parameter random of functions nlme::lme() and nlme::nlme().

In fact, the ‘grouped’ extension of the S3 class 'hyperframe' is inspired by the S3 class 'groupedData' defined in package nlme (Pinheiro et al. 2025, v3.1.169, GPL (>= 2)), which inherits from the class 'data.frame'.

Package groupedHyperframe (v0.4.0, GPL-2) allows interaction terms using colon operator : in the (nested) grouping structure, e.g., ~g1/g2a:g2b/g3a:g3b:g3c. This feature is made possible because the colon operator : has higher priority than the forward slash / in R formula (Listing 34.1). In the meanwhile, user should be aware that the tilde operator ~ has lower priority than the forward pipe |> in R formula (Listing 34.2).

Listing 34.1: Advanced: colon operator : has higher priority than forward slash /

quote(g1/g2a:g2b/g3a:g3b:g3c) |>
  as.list()

[[1]]
`/`

[[2]]
g1/g2a:g2b

[[3]]
g3a:g3b:g3c

Listing 34.2: Advanced: tilde operator ~ has lower priority than forward pipe |>

list(
  ~ x |> foobar(), # wrong!
  quote((~ x) |> foobar()) # correct
)

[[1]]
~foobar(x)

[[2]]
foobar((~x))

The low-level utility function get_nested() breaks down a nested grouping structure by the forward slash / (Listing 34.3).

Listing 34.3: Example: function get_nested() on formula, with interaction terms

(~g1/g2a:g2b/g3a:g3b:g3c) |>
  get_nested()

$g1
g1

$`g2a:g2b`
g2a:g2b

$`g3a:g3b:g3c`
g3a:g3b:g3c

Listing 34.4 and Listing 34.5 the exception handling of function get_nested() when no nested group exists.

Listing 34.4: Exception: function get_nested() on formula, no nested group

(~a) |> get_nested()

$a
a

Listing 34.5: Exception: function get_nested() on formula with interaction term, but no nested group

(~b:c) |> get_nested()

$`b:c`
b:c

The (nested) grouping structure attr(,'group') of a grouped hyper data frame (Chapter 15)

must denote the highest level using a symbol (e.g., g1)
may denote the lower levels using a symbol (e.g., g2) or an interaction-term (e.g., g2a:g2b)