49 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 a basis for research grant applications,
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 49 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.168, 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 49.1). In the meanwhile, user should be aware that the tilde operator ~ has lower priority than the forward pipe |> in R formula (Listing 49.2).

Listing 49.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 49.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 49.3).

Listing 49.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 49.4 and Listing 49.5 the exception handling of function get_nested() when no nested group exists.

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

(~a) |> get_nested()
# $a
# a

Listing 49.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 25)

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)