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"             "package:graphics"          "package:grDevices"         "package:utils"            
#  [8] "package:datasets"          "package:methods"           "Autoloads"                 "package:base"

In Chapter 3, the author

creates a grouped hyper data frame with one-and-only-one point-pattern (ppp) hypercolumn (Section 3.1);
discusses 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);
summarizes the results of the batch-processes (Section 3.3)
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 20.14) point-pattern (ppp, Chapter 27) hypercolumn from the data frame wrobel_lung. This process (Section 19.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: Create a grouped hyper data frame with one-and-only-one ppp-hypercolumn

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

Listing 3.2: A grouped hyper data frame s

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)

Figure 3.1 visualizes the one-and-only-one point-pattern hypercolumn s$ppp. using package spatstat.geom (v3.6.1); further details are provided in Section 20.1.

Listing 3.3: Review: plot point-pattern hypercolumn s$ppp.

Code

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"
  )

Figure 3.1: Point-pattern hypercolumn *`s$ppp.`*

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, Listing 2.2, Section 14.1);
create a grouped hyper data frame with one-and-only-one point-pattern hypercolumn, from a data frame (Section 3.1, Listing 3.1, Section 19.1).

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

3.2 Batch Process on Eligible Marks

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

Listing 3.4 calculates, from each point-pattern of the one-and-only-one point-pattern hypercolumn s$ppp.,

the conditional mean $E(r)$ of the numeric mark hladr using function Emark_() (Table 27.18). The results are stored in the function-value-table (fv, Chapter 15) hypercolumn (Chapter 16) $hladr.E of the output (Listing 3.5).
the multi-type nearest-neighbor distance $G_{\text{CK+.CD8- to CK-.CD8+}}(r)$ of the multi-type mark phenotype using function Gcross_() (Table 27.19). The results are stored in the function-value-table hypercolumn $phenotype.G of the output (Listing 3.5).
the nearest neighbor distance from CK+.CD8- to CK-.CD8+ marks in the multi-type mark phenotype using function nncross_() (Table 27.20). The results are stored in the numeric-hypercolumn $phenotype.nncross of the output (Listing 3.5).

Listing 3.4 lastly substitutes the recommended function values outside the recommended range with the corresponding theoretical values using function .disrecommend2theo() (Section 15.4.1). The function-value-table hypercolumns $hladr.E and $phenotype.G of the output are replaced with the substituted function-value-table hypercolumns.

Listing 3.4: 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') |>
  .disrecommend2theo()

Listing 3.5: A grouped hyper data frame out; batch processes on one-and-only-one ppp-hypercolumn

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 Statistics of Point-Pattern Marks

Listing 3.6 summarizes various customized statistics of the numeric- and/or multi-type-marks of the one-and-only-one point-pattern hypercolumn in the (grouped) hyper data frame s (Section 3.1, Listing 3.1) using function aggregate_marks() (Section 20.6). The results are stored in the numeric-hypercolumn $markstats of the output (Listing 3.7).

Listing 3.6 does not require the function-value-table hypercolumns created by the batch processes (Section 3.2).

Listing 3.6: Summarizing customized statistics of point-pattern marks

s_markstat = s |>
  aggregate_marks(by = hladr ~ phenotype, FUN = \(z) {
    c(mean = mean(z), sd = sd(z))
  })

Listing 3.7: Numeric-hypercolumn s_markstat$markstats: summarizing customized statistics of point-pattern marks

Code

s_markstat$markstats[1:3]
# 1:
# CK-.CD8-.hladr.mean   CK-.CD8-.hladr.sd CK+.CD8-.hladr.mean   CK+.CD8-.hladr.sd CK-.CD8+.hladr.mean   CK-.CD8+.hladr.sd 
#          0.19611248          0.09574274          0.13157655          0.02220862          0.37042708          0.15887763 
# 
# 2:
# CK-.CD8-.hladr.mean   CK-.CD8-.hladr.sd CK+.CD8-.hladr.mean   CK+.CD8-.hladr.sd CK-.CD8+.hladr.mean   CK-.CD8+.hladr.sd 
#          0.32685110          0.26761137          0.11682620          0.04559459          0.56401579          0.26288830 
# 
# 3:
# CK-.CD8-.hladr.mean   CK-.CD8-.hladr.sd CK+.CD8-.hladr.mean   CK+.CD8-.hladr.sd CK-.CD8+.hladr.mean   CK-.CD8+.hladr.sd 
#          0.46421412          0.22013973          0.14423884          0.04331782          0.75227297          0.24305858

3.3.2 of `fv`-Hypercolumns

Listing 3.8 summarizes the function-value-table (fv, Chapter 15) hypercolumns (Chapter 16) out$hladr.E and out$phenotype.G from the batch processes (Section 3.2, Listing 3.4),

by the recommended function values using function keyval() (Section 15.1). The results are stored in the numeric-hypercolumns $hladr.E.y and $phenotype.G.y of the output (Listing 3.9);
by the cumulative average vertical height of the trapezoidal integration of the recommended function values using function cumvtrapz() (Section 11.1). The results are stored in the numeric-hypercolumns $hladr.E.cumvtrapz and $phenotype.G.cumvtrapz of the output (Listing 3.9).

The functions keyval() and cumvtrapz() in Listing 3.8 are independent of one another. Readers may apply one or both, in whichever order suits their workflow.

Listing 3.8: Summarizing function-value-tables (fv) hypercolumns

out_fv = out |>
  keyval() |>
  cumvtrapz()

Listing 3.9: A grouped hyper data frame out_fv, summarizing 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 phenotype.G.y hladr.E.cumvtrapz phenotype.G.cumvtrapz
# 1  3488+      F  85 #01 0-889-121 [40864,18015].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 2  3488+      F  85 #01 0-889-121 [42689,19214].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 3  3488+      F  85 #01 0-889-121 [42806,16718].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 4  3488+      F  85 #01 0-889-121 [44311,17766].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 5  3488+      F  85 #01 0-889-121 [45366,16647].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 6   1605      M  66 #02 1-037-393 [56576,16907].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 7   1605      M  66 #02 1-037-393 [56583,15235].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 8   1605      M  66 #02 1-037-393 [57130,16082].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 9   1605      M  66 #02 1-037-393 [57396,17896].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)
# 10  1605      M  66 #02 1-037-393 [57403,16934].im3 (ppp)    (fv)        (fv)         (numeric) (numeric)     (numeric)         (numeric)             (numeric)

3.3.3 of Quantiles

Listing 3.10 inspects the hypercolumns of the input (grouped) hyper data frame out (Section 3.2, Listing 3.4) and finds the quantiles of,

the numeric-hypercolumn out$phenotype.nncross (Section 3.2, Listing 3.4). The results are stored in the numeric-hypercolumn $phenotype.nncross.quantile of the output (Listing 3.11);
the numeric mark hladr in the one-and-only-one point-pattern hypercolumn out$ppp. (Section 3.1, Listing 3.1). The results are stored in the numeric-hypercolumn $hladr.quantile of the output (Listing 3.11).

Listing 3.10: Summarizing quantiles

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

Listing 3.11: 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 phenotype.nncross.quantile hladr.quantile
# 1  3488+      F  85 #01 0-889-121 [40864,18015].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 2  3488+      F  85 #01 0-889-121 [42689,19214].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 3  3488+      F  85 #01 0-889-121 [42806,16718].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 4  3488+      F  85 #01 0-889-121 [44311,17766].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 5  3488+      F  85 #01 0-889-121 [45366,16647].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 6   1605      M  66 #02 1-037-393 [56576,16907].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 7   1605      M  66 #02 1-037-393 [56583,15235].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 8   1605      M  66 #02 1-037-393 [57130,16082].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 9   1605      M  66 #02 1-037-393 [57396,17896].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 10  1605      M  66 #02 1-037-393 [57403,16934].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)

3.3.4 of Kernel Density Estimates

Listing 3.12 inspects the hypercolumns of the input (grouped) hyper data frame out (Section 3.2, Listing 3.4) and finds the kernel density estimates of,

the numeric-hypercolumn out$phenotype.nncross (Section 3.2, Listing 3.4). The results are stored in the numeric-hypercolumn $phenotype.nncross.kerndens of the output (Listing 3.13);
the numeric mark hladr in the one-and-only-one point-pattern hypercolumn out$ppp. (Section 3.1, Listing 3.1). The results are stored in the numeric-hypercolumn $hladr.kerndens of the output (Listing 3.13).

Listing 3.12: Summarizing kernel density estimates

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

Listing 3.13: A grouped hyper data frame out_k: summarizing kernel density estimates

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 phenotype.nncross.kerndens hladr.kerndens
# 1  3488+      F  85 #01 0-889-121 [40864,18015].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 2  3488+      F  85 #01 0-889-121 [42689,19214].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 3  3488+      F  85 #01 0-889-121 [42806,16718].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 4  3488+      F  85 #01 0-889-121 [44311,17766].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 5  3488+      F  85 #01 0-889-121 [45366,16647].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 6   1605      M  66 #02 1-037-393 [56576,16907].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 7   1605      M  66 #02 1-037-393 [56583,15235].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 8   1605      M  66 #02 1-037-393 [57130,16082].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 9   1605      M  66 #02 1-037-393 [57396,17896].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)
# 10  1605      M  66 #02 1-037-393 [57403,16934].im3 (ppp)    (fv)        (fv)         (numeric)                  (numeric)      (numeric)

3.4 Aggregation

Listing 3.14 aggregates (Section 20.5) the customized statistics of the numeric- and/or multi-type-marks of the one-and-only-one point-pattern hypercolumn (Section 3.3.1, Listing 3.6) by patient_id using point-wise means pmeans() (Section 32.4), and returns a hyper data frame.

Listing 3.14: Aggregates the customized statistics of the numeric- and/or multi-type-marks

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

Listing 3.15 aggregates (Section 20.5) the summarized information from function-value-table (fv) hypercolumns (Section 3.3.2, Listing 3.8) by patient_id using point-wise means pmeans() (Section 32.4), and returns a hyper data frame.

Listing 3.15: Aggregates the function-value-tables

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

Listing 3.16 aggregates (Section 20.5) the quantiles from the numeric-hypercolumns or the numeric-marks of the one-and-only-one point-pattern hypercolumn (Section 3.3.3, Listing 3.10) by patient_id using point-wise means pmeans() (Section 32.4), and returns a hyper data frame.

Listing 3.16: 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.17 aggregates (Section 20.5) the kernel density estimates from the numeric-hypercolumns or the numeric-marks of the one-and-only-one point-pattern hypercolumn (Section 3.3.4, Listing 3.12) by patient_id using point-wise means pmeans() (Section 32.4), and returns a hyper data frame.

Listing 3.17: Aggregates the kernel density estimates

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)