3 Grouping `ppp`-Hypercolumn

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

library(groupedHyperframe)
library(survival)

search path on author’s computer running RStudio (Posit Team 2025)

search()
#  [1] ".GlobalEnv"                "package:survival"          "package:groupedHyperframe" "package:stats"            
#  [5] "package:graphics"          "package:grDevices"         "package:utils"             "package:datasets"         
#  [9] "package:methods"           "Autoloads"                 "package:base"

In Chapter 3, the authors

create a grouped hyper data frame with one-and-only-one point-pattern (ppp) hypercolumn (Section 3.1);
discuss the batch processes of spatial point-pattern analyses applicable to the one-and-only-one point-pattern hypercolumn of a (grouped) hyper data frame (Section 3.2);
summarize the results of the batch-processes (Section 3.3)
(optional) aggregates the summary statistics over the nested grouping structure (Section 3.4).

3.1 Creation

Listing 3.1 creates a grouped hyper data frame s with one-and-only-one (Section 17.13) point-pattern (ppp, Chapter 23) hypercolumn from the data frame wrobel_lung. This process (Section 16.1)

creates a point-pattern hypercolumn ppp. from the $x$- and $y$-coordinates, the numeric mark hladr and the multi-type mark phenotype, per image_id nested within patient_id;
aggregates other variables of interest, e.g., OS, gender and age, at the level of image_id nested within patient_id. Those variables must be identical within the nested grouping structure ~patient_id/image_id.

Listing 3.1: Function grouped_ppp()

s = wrobel_lung |>
   grouped_ppp(formula = hladr + phenotype ~ OS + gender + age | patient_id/image_id, data = _, coords = ~ x + y)

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

Readers may visualize the one-and-only-one point-pattern hypercolumn s$ppp. using package spatstat.geom (v3.6.0.3); further details are provided in Section 17.1.

Review: plot point-pattern hypercolumn s$ppp.

s[1:4, ] |> # first 4 rows
  spatstat.geom::plot.hyperframe(
    e = quote(plot(ppp., main = paste(patient_id, image_id, sep = '\n'))), 
    main = "First 4 ppp's"
  )

Readers must note that Chapter 2 and Section 3.1 describe two independent approaches to

create a grouped hyper data frame, from a data frame (Chapter 2, Section 12.1);
create a grouped hyper data frame with one-and-only-one point-pattern hypercolumn, from a data frame (Section 3.1, Section 16.1).

These two approaches are independent and unrelated to each other (Section 31.1).

3.2 Batch Process on Eligible Marks

Listing 3.2 applies multiple batch processing functions (Section 23.15, Section 24.7, Section 17.13) to the eligible marks in the one-and-only-one (Section 17.13) point-pattern (ppp) hypercolumn in the (grouped) hyper data frame s (Listing 3.1) using a pipeline.

Listing 3.2: Batch Operations

r = seq.int(from = 0, to = 250, by = 10)
out = s |>
  Emark_(r = r, correction = 'none') |>
  Gcross_(i = 'CK+.CD8-', j = 'CK-.CD8+', r = r, correction = 'none') |>
  nncross_(i = 'CK+.CD8-', j = 'CK-.CD8+', correction = 'none')

The returned (grouped) hyper data frame out has

function-value-table (fv, Chapter 13) hypercolumn (Chapter 14) hladr.E, which is the conditional mean $E(r)$ (Table 23.9) of the numeric mark hladr in the one-and-only-one point-pattern (ppp) hypercolumn s$ppp.;
function-value-table hypercolumn phenotype.G, which is the multi-type nearest-neighbor distance $G_{\text{CK+.CD8- to CK-.CD8+}}(r)$ (Table 23.10) in the multi-type mark phenotype in the one-and-only-one point-pattern hypercolumn s$ppp.;
numeric-hypercolumn phenotype.nncross, which is the nearest neighbor distance from CK+.CD8- to CK-.CD8+ marks (Table 23.11) in the multi-type mark phenotype in the one-and-only-one point-pattern hypercolumn s$ppp..

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

3.3 Summarization

3.3.1 of `fv`-Hypercolumns

The function-value-table (fv, Chapter 13) hypercolumns (Chapter 14) from the batch processes (Section 3.2) are summarized (Section 14.3, Section 17.10) by

the recommended-function-values .y (Section 13.1),
the cumulative trapezoidal integration .cumtrapz (Chapter 9) of the recommended-function-values, and
the cumulative average vertical height of the trapezoidal integration .cumvtrapz (Section 9.1) of the recommended-function-values.

Listing 3.3 appends the summarized statistics as new numeric-hypercolumns to the input (grouped) hyper data frame out (Listing 3.2). The returned (grouped) hyper data frame out_fv has

numeric-hypercolumns hladr.E.y, hladr.E.cumtrapz and hladr.E.cumvtrapz from the function-value-table (fv) hypercolumn out$hladr.E.
numeric-hypercolumns phenotype.G.y, phenotype.G.cumtrapz and phenotype.G.cumvtrapz from the function-value-table hypercolumn out$phenotype.G.

Listing 3.3: Funcion summary_fv()

out_fv = out |>
  summary_fv()

A grouped hyper data frame out_fv: summarizing function-value-tables (fv) hypercolumns

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

3.3.2 of Quantiles

In a (grouped) hyper data frame, the quantiles of

the numeric marks in the one-and-only-one point-pattern (ppp) hypercolumn (Section 3.1, Section 24.3), or
the numeric hypercolumns from the batch processes (Section 3.2, Section 11.2),

are summarized (Section 17.4).

Listing 3.4 appends the summarized statistics as new numeric-hypercolumns to the input (grouped) hyper data frame out (Listing 3.2). The returned (grouped) hyper data frame out_q has

numeric-hypercolumn phenotype.nncross.quantile, the quantiles of the numeric-hypercolumn out$phenotype.nncross.
numeric-hypercolumn hladr.quantile, the quantiles of the numeric mark hladr in the point-pattern (ppp) hypercolumn out$ppp..

Listing 3.4: Funcion quantile.hyperframe()

out_q = out |>
  quantile(probs = seq.int(from = 0, to = 1, by = .1))

A grouped hyper data frame out_q: summarizing quantiles

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

3.3.3 of Kernel Densities

In a (grouped) hyper data frame, the kernel densities (Becker, Chambers, and Wilks 1988) estimates of

the numeric marks in the one-and-only-one point-pattern (ppp) hypercolumn (Section 3.1, Section 24.2), or
the numeric hypercolumns from the batch processes (Section 3.2, Section 11.1),

are summarized (Section 17.3).

Listing 3.5 appends the summarized statistics as new numeric-hypercolumns to the input (grouped) hyper data frame out (Listing 3.2). The returned (grouped) hyper data frame out_k has

numeric-hypercolumn phenotype.nncross.kerndens, the kernel densities of the numeric-hypercolumn out$phenotype.nncross.
numeric-hypercolumn hladr.kerndens, the kernel densities of the numeric mark hladr in the point-pattern (ppp) hypercolumn out$ppp..

Listing 3.5: Funcion kerndens.hyperframe()

mdist = out$phenotype.nncross |> unlist() |> max()
out_k = out |> 
  kerndens(from = 0, to = mdist)

A grouped hyper data frame out_k: summarizing kernel densities

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

3.4 Aggregation

In a grouped hyper data frame, the summary statistics (Section 3.3) are aggregated (Section 17.5) by the higher level(s) of the nested grouping structure.

Listing 3.6 aggregates the summarized information from function-value-table (fv) hypercolumns (Section 3.3.1) in the input grouped hyper data frame out_fv (Listing 3.3) by patient_id,

Listing 3.6: Example: aggregates the function-value-tables

out_fv |>
  aggregate(by = ~ patient_id, fun = pmean)
# Hyperframe:
#      OS gender age    patient_id hladr.E.y hladr.E.cumtrapz hladr.E.cumvtrapz phenotype.G.y phenotype.G.cumtrapz
# 1 3488+      F  85 #01 0-889-121 (numeric)        (numeric)         (numeric)     (numeric)            (numeric)
# 2  1605      M  66 #02 1-037-393 (numeric)        (numeric)         (numeric)     (numeric)            (numeric)
# 3   176      M  84 #03 2-080-378 (numeric)        (numeric)         (numeric)     (numeric)            (numeric)
#   phenotype.G.cumvtrapz      ppp.  hladr.E phenotype.G
# 1             (numeric) (ppplist) (fvlist)    (fvlist)
# 2             (numeric) (ppplist) (fvlist)    (fvlist)
# 3             (numeric) (ppplist) (fvlist)    (fvlist)

Listing 3.7 aggregates the quantiles from the numeric-hypercolumns or the numeric-marks of the one-and-only-one point-pattern (ppp) hypercolumn (Section 3.3.2) in the input grouped hyper data frame out_q (Listing 3.4) by patient_id,

Listing 3.7: Example: aggregates the quantiles

out_q |> 
  aggregate(by = ~ patient_id)
# Hyperframe:
#      OS gender age    patient_id phenotype.nncross.quantile hladr.quantile      ppp.  hladr.E phenotype.G
# 1 3488+      F  85 #01 0-889-121                  (numeric)      (numeric) (ppplist) (fvlist)    (fvlist)
# 2  1605      M  66 #02 1-037-393                  (numeric)      (numeric) (ppplist) (fvlist)    (fvlist)
# 3   176      M  84 #03 2-080-378                  (numeric)      (numeric) (ppplist) (fvlist)    (fvlist)

Listing 3.8 aggregates the kernel densities from the numeric-hypercolumns or the numeric-marks of the one-and-only-one point-pattern (ppp) hypercolumn (Section 3.3.3) in the input grouped hyper data frame out_k (Listing 3.5) by patient_id,

Listing 3.8: Example: aggregates the kernel densities

out_k |>
  aggregate(by = ~ patient_id)
# Hyperframe:
#      OS gender age    patient_id phenotype.nncross.kerndens hladr.kerndens      ppp.  hladr.E phenotype.G
# 1 3488+      F  85 #01 0-889-121                  (numeric)      (numeric) (ppplist) (fvlist)    (fvlist)
# 2  1605      M  66 #02 1-037-393                  (numeric)      (numeric) (ppplist) (fvlist)    (fvlist)
# 3   176      M  84 #03 2-080-378                  (numeric)      (numeric) (ppplist) (fvlist)    (fvlist)