16 `groupedHyperframe`

The examples in Chapter 16 require that the search path contains the following namespaces,

library(groupedHyperframe)

Package groupedHyperframe (v0.3.0.20251020) introduces a new S3 class 'groupedHyperframe', for grouped hyper data frame, which inherits from the class 'hyperframe' (Chapter 17). The derived class 'groupedHyperframe' has additional attributes

attr(,'group'), a one-sided formula of the (nested) grouping structure (Section 16.2).

Package groupedHyperframe implements the following S3 method dispatches to the class 'groupedHyperframe' (Listing 16.1, Table 16.1),

Listing 16.1: Table: S3 method dispatches groupedHyperframe::*.groupedHyperframe

Code

suppressPackageStartupMessages(library(spatstat.geom))
methods2kable(class = 'groupedHyperframe', package = 'groupedHyperframe', all.names = TRUE)

Table 16.1: S3 method dispatches groupedHyperframe::*.groupedHyperframe (v0.3.0.20251020)

	visible	from	generic	isS4
`[.groupedHyperframe`	TRUE	groupedHyperframe	`base::[`	FALSE
`$<-.groupedHyperframe`	TRUE	groupedHyperframe	base::`$<-`	FALSE
`cbind.groupedHyperframe`	TRUE	groupedHyperframe	`base::cbind`	FALSE
`print.groupedHyperframe`	TRUE	groupedHyperframe	`base::print`	FALSE
`superimpose.groupedHyperframe`	TRUE	groupedHyperframe	`spatstat.geom::superimpose`	FALSE

Most of the S3 method dispatches in Table 16.1 are straightforward extensions of their counterparts for the class 'hyperframe' (Chapter 17).

Table 16.2: Inheritance of S3 Class 'groupedHyperframe'

S3 Method Dispatch	… is a trivial wrapper of
`print.groupedHyperframe()`	`spatstat.geom::print.hyperframe()`
`[.groupedHyperframe()`	spatstat.geom::`[.hyperframe`()
`$<-.groupedHyperframe()`	spatstat.geom::`$<-.hyperframe`()
`cbind.groupedHyperframe()`	`spatstat.geom::cbind.hyperframe()`
`superimpose.groupedHyperframe()`	`superimpose.hyperframe()` (Section 17.8)

Section 16.1 and Section 16.2 of Chapter 16 are not S3 method dispatches to the class 'groupedHyperframe'. Instead, they provide supplemental information about the class that experienced R users may find useful.

16.1 `grouped_ppp()`

Function grouped_ppp() creates a grouped hyper data frame with one-and-only-one (Section 17.13) ppp-hypercolumn, from a data frame. In Section 3.1, Listing 3.1, the argument formula takes form of <marks> ~ <variable.of.interest> | <group>, specifically,

the point-pattern marks, e.g., a numeric mark hladr and a multitype mark phenotype, on the left-hand-side
the additional predictors and/or endpoints for downstream analysis, e.g., OS, gender and age, before the | separator on the right-hand-side.
the (nested) grouping structure, e.g., image_id nested in patient_id, after the | separator on the right-hand-side.

Alternatively, readers may use the dot symbol . to denote the remaining variables except for those mentioned in the marks and the nested grouping structure.

Advanced: function grouped_ppp(formula = <marks> ~ . | <group>)

wrobel_lung |>
   grouped_ppp(formula = hladr + phenotype ~ . | patient_id/image_id)
# Grouped Hyperframe: ~patient_id/image_id
# 
# 15 image_id nested in
# 3 patient_id
# 
# Preview of first 10 (or less) rows:
# 
#       patient_id          image_id gender       OS age  ppp.
# 1  #01 0-889-121 [40864,18015].im3      F (matrix)  85 (ppp)
# 2  #01 0-889-121 [42689,19214].im3      F (matrix)  85 (ppp)
# 3  #01 0-889-121 [42806,16718].im3      F (matrix)  85 (ppp)
# 4  #01 0-889-121 [44311,17766].im3      F (matrix)  85 (ppp)
# 5  #01 0-889-121 [45366,16647].im3      F (matrix)  85 (ppp)
# 6  #02 1-037-393 [56576,16907].im3      M (matrix)  66 (ppp)
# 7  #02 1-037-393 [56583,15235].im3      M (matrix)  66 (ppp)
# 8  #02 1-037-393 [57130,16082].im3      M (matrix)  66 (ppp)
# 9  #02 1-037-393 [57396,17896].im3      M (matrix)  66 (ppp)
# 10 #02 1-037-393 [57403,16934].im3      M (matrix)  66 (ppp)

16.2 Nested Groups

The nested grouping structure $g_1/.../g_m$ (~g1/.../gm)

is explained in section Details of stats::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, Bates, and R Core Team 2025, v3.1.168), which inherits from the class 'data.frame'.

Package groupedHyperframe 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 16.2). In the meanwhile, user should be aware that the tilde operator ~ has lower priority than the forward pipe |> in R formula (Listing 16.3).

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

Code

quote(g1/g2a:g2b/g3a:g3b:g3c) |>
  as.list()
# [[1]]
# `/`
# 
# [[2]]
# g1/g2a:g2b
# 
# [[3]]
# g3a:g3b:g3c

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

Code

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 /.

Example: function get_nested()

quote(g1/g2/g3) |>
  get_nested()
# $g1
# g1
# 
# $g2
# g2
# 
# $g3
# g3
(~g1/g2/g3) |>
  get_nested()
# $g1
# g1
# 
# $g2
# g2
# 
# $g3
# g3

Example: function get_nested() with interaction terms

quote(g1/g2a:g2b/g3a:g3b:g3c) |>
  get_nested()
# $g1
# g1
# 
# $`g2a:g2b`
# g2a:g2b
# 
# $`g3a:g3b:g3c`
# g3a:g3b:g3c
(~g1/g2a:g2b/g3a:g3b:g3c) |>
  get_nested()
# $g1
# g1
# 
# $`g2a:g2b`
# g2a:g2b
# 
# $`g3a:g3b:g3c`
# g3a:g3b:g3c

Exception: function get_nested()

(~a) |> get_nested()
# $a
# a
(~b:c) |> get_nested()
# $`b:c`
# b:c

The (nested) grouping structure attr(,'group') of a groupedHyperframe

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)

16.1 grouped_ppp()

16.2 Nested Groups

16.1 `grouped_ppp()`