24  groupedData

Function nlme::groupedData() (Pinheiro, Bates, and R Core Team 2025, v3.1.168) creates a grouped data frame, i.e., an R object of S3 class 'groupedData'. Listing 24.1 summarizes the S3 methods for the class 'groupedData' in packages nlme,

Listing 24.1: Existing (but not exported) S3 methods nlme::*.groupedData
Code 
suppressPackageStartupMessages(library(nlme))
.S3methods(class = 'groupedData', all.names = TRUE) |> 
  attr(which = 'info', exact = TRUE)
#                           visible                from       generic  isS4
# [.groupedData               FALSE registered S3method             [ FALSE
# as.data.frame.groupedData   FALSE registered S3method as.data.frame FALSE
# asTable.groupedData         FALSE registered S3method       asTable FALSE
# collapse.groupedData        FALSE registered S3method      collapse FALSE
# formula.groupedData         FALSE registered S3method       formula FALSE
# isBalanced.groupedData      FALSE registered S3method    isBalanced FALSE
# lme.groupedData             FALSE registered S3method           lme FALSE
# lmList.groupedData          FALSE registered S3method        lmList FALSE
# print.groupedData           FALSE registered S3method         print FALSE
# update.groupedData          FALSE registered S3method        update FALSE

The examples in Chapter 24 require

library(groupedHyperframe)
search path & loadedNamespaces on author’s computer 
search()
#  [1] ".GlobalEnv"                "package:groupedHyperframe" "package:stats"             "package:graphics"          "package:grDevices"         "package:utils"             "package:datasets"         
#  [8] "package:methods"           "Autoloads"                 "package:base"
loadedNamespaces() |> sort.int()
#  [1] "abind"             "base"              "cli"               "cluster"           "codetools"         "compiler"          "datasets"          "deldir"            "digest"           
# [10] "doParallel"        "dplyr"             "evaluate"          "farver"            "fastmap"           "fastmatrix"        "foreach"           "generics"          "geomtextpath"     
# [19] "GET"               "ggplot2"           "glue"              "goftest"           "graphics"          "grDevices"         "grid"              "gridExtra"         "groupedHyperframe"
# [28] "gtable"            "htmltools"         "htmlwidgets"       "iterators"         "jsonlite"          "knitr"             "lattice"           "lifecycle"         "magrittr"         
# [37] "Matrix"            "matrixStats"       "methods"           "nlme"              "otel"              "parallel"          "patchwork"         "pillar"            "pkgconfig"        
# [46] "polyclip"          "pracma"            "R6"                "RColorBrewer"      "rlang"             "rmarkdown"         "rstudioapi"        "S7"                "scales"           
# [55] "SpatialPack"       "spatstat.data"     "spatstat.explore"  "spatstat.geom"     "spatstat.random"   "spatstat.sparse"   "spatstat.univar"   "spatstat.utils"    "stats"            
# [64] "systemfonts"       "tensor"            "textshaping"       "tibble"            "tidyselect"        "tools"             "utils"             "vctrs"             "viridisLite"      
# [73] "xfun"              "yaml"

Table 24.1 summarizes the S3 methods for the class 'groupedData' in package groupedHyperframe (v0.3.2.20251225),

Table 24.1: S3 methods groupedHyperframe::*.groupedData (v0.3.2.20251225)
visible from generic isS4
as.groupedHyperframe.groupedData TRUE groupedHyperframe groupedHyperframe::as.groupedHyperframe FALSE

24.1 Create groupedHyperframe

The S3 method as.groupedHyperframe.groupedData() (Section 18.1, Table 18.2) converts a grouped data frame into a grouped hyper data frame (groupedHyperframe, Chapter 25) using its grouping structure.

Listing 24.3 converts the grouped data frame Remifentanil (Listing 24.2) from package nlme (Pinheiro, Bates, and R Core Team 2025, v3.1.168) into a grouped hyper data frame.

Listing 24.2: Data: Remifentanil 
nlme::Remifentanil
# Grouped Data: conc ~ Time | Subject
#      ID Subject   Time   conc   Rate       Amt   Age    Sex  Ht    Wt    BSA     LBM
# 1     1       1   0.00     NA  71.99  107.9850 30.58   Male 171  72.0 1.8393 56.5075
# 2     1       1   1.50   9.51  71.99   35.9950 30.58   Male 171  72.0 1.8393 56.5075
# 3     1       1   2.00  11.50  71.99   37.4348 30.58   Male 171  72.0 1.8393 56.5075
# ✂️ --- output truncated --- ✂️
Listing 24.3: Example: function as.groupedHyperframe.groupedData() on Remifentanil 
Remifentanil_g = nlme::Remifentanil |> 
  as.groupedHyperframe()
Remifentanil_g
# Grouped Hyperframe: ~Subject
# 
# 65 Subject
# 
#         Time      conc      Rate       Amt ID Subject   Age    Sex  Ht    Wt    BSA     LBM
# 1  (numeric) (numeric) (numeric) (numeric) 30      30 21.00 Female 165  55.9 1.6095 42.8260
# 2  (numeric) (numeric) (numeric) (numeric) 21      21 24.00 Female 161  58.6 1.6131 43.0953
# 3  (numeric) (numeric) (numeric) (numeric) 25      25 32.00 Female 157  45.9 1.4278 36.4631
# 4  (numeric) (numeric) (numeric) (numeric) 23      23 23.00 Female 163  50.0 1.5215 39.5740
# 5  (numeric) (numeric) (numeric) (numeric) 29      29 25.00 Female 163  54.5 1.5782 41.7695
# ✂️ --- output truncated --- ✂️

Listing 24.5 converts the grouped data frame bdf (Listing 24.4) from package nlme (Pinheiro, Bates, and R Core Team 2025, v3.1.168) into a grouped hyper data frame.

Listing 24.4: Data: bdf 
nlme::bdf
# Grouped Data: langPOST ~ IQ.verb | schoolNR
# <environment: 0x31a7d3c70>
#      schoolNR pupilNR IQ.verb  IQ.perf sex Minority repeatgr aritPRET classNR aritPOST langPRET langPOST ses denomina schoolSES satiprin natitest meetings currmeet mixedgra percmino aritdiff homework
# 1           1   17001    15.0 12.33333   0        N        0       14     180       24       36       46  23        1        11  3.42857        0  1.70000  1.83333        0       60       12  2.33333
# 2           1   17002    14.5 10.00000   0        Y        0       12     180       19       36       45  10        1        11  3.42857        0  1.70000  1.83333        0       60       12  2.33333
# 3           1   17003     9.5 11.00000   0        N        0       10     180       24       33       33  15        1        11  3.42857        0  1.70000  1.83333        0       60       12  2.33333
# ✂️ --- output truncated --- ✂️
Listing 24.5: Example: function as.groupedHyperframe.groupedData() on bdf 
bdf_g = nlme::bdf |> 
  as.groupedHyperframe()
bdf_g
# Grouped Hyperframe: ~schoolNR
# 
# 131 schoolNR
# 
#      pupilNR   IQ.verb   IQ.perf      sex Minority  repeatgr  aritPRET   classNR  aritPOST  langPRET  langPOST       ses mixedgra  percmino  homework  classsiz  groupsiz IQ.ver.cen grpSiz.cen
# 1   (factor) (numeric) (numeric) (factor) (factor) (ordered) (numeric) (numeric) (numeric) (numeric) (numeric) (numeric) (factor) (numeric) (numeric) (numeric) (numeric)  (numeric)  (numeric)
# 2   (factor) (numeric) (numeric) (factor) (factor) (ordered) (numeric) (numeric) (numeric) (numeric) (numeric) (numeric) (factor) (numeric) (numeric) (numeric) (numeric)  (numeric)  (numeric)
# 3   (factor) (numeric) (numeric) (factor) (factor) (ordered) (numeric) (numeric) (numeric) (numeric) (numeric) (numeric) (factor) (numeric) (numeric) (numeric) (numeric)  (numeric)  (numeric)
# 4   (factor) (numeric) (numeric) (factor) (factor) (ordered) (numeric) (numeric) (numeric) (numeric) (numeric) (numeric) (factor) (numeric) (numeric) (numeric) (numeric)  (numeric)  (numeric)
# 5   (factor) (numeric) (numeric) (factor) (factor) (ordered) (numeric) (numeric) (numeric) (numeric) (numeric) (numeric) (factor) (numeric) (numeric) (numeric) (numeric)  (numeric)  (numeric)
# ✂️ --- output truncated --- ✂️

Converting a (grouped) data frame with substantial amount of duplicated information into a grouped hyper data frame not necessarily(!!) reduces the memory allocation (Listing 24.8), because the hyperframe object (Chapter 26) carries additional auxiliary information. And even when it does reduce the memory allocation (Listing 24.6), a grouped hyper data frame would not reduce much the saved file.size compared to a data frame, if xz compression is used for both (Listing 24.7).

Listing 24.6: Advanced: Listing 24.3 reduces memory allocation 
unclass(object.size(Remifentanil_g) / object.size(nlme::Remifentanil))
# [1] 0.3083022
Listing 24.7: Advanced: Listing 24.3 does not reduce saved file size 
f = replicate(n = 2L, expr = tempfile(fileext = '.rds'))
Remifentanil_g |> saveRDS(file = f[1L], compress = 'xz')
nlme::Remifentanil |> saveRDS(file = f[2L], compress = 'xz')
file.size(f[1L]) / file.size(f[2L])
# [1] 0.9081325
Listing 24.8: Advanced: Listing 24.5 does not reduce memory allocation 
unclass(object.size(bdf_g) / object.size(nlme::bdf))
# [1] 25.78675