Section 20.1 is intended as an educational handbook for beginners to package spatstat.geom (v3.6.1). This section does not discuss the functionality of package groupedHyperframe (v0.3.2).
The S3 method length.hyperframe() finds the number of columns and/or hypercolumns of a hyper data frame. Listing 20.3 reveals that the hyper data frame demohyper (Section 10.8) has 3 (hyper)columns.
Listing 20.3: Example: function length.hyperframe()
spatstat.data::demohyper |>length()# [1] 3
The S3 method length.hyperframe() reproduces the behavior of the .PrimitiveS3 generic function base::length() when dispatched to objects of class 'data.frame'. Listing 20.4 reveals that the data frame Formaldehyde from package datasets shipped with R version 4.5.2 (2025-10-31) has 2 columns.
Listing 20.4: Review: function base::length() on data.frame
datasets::Formaldehyde |>length()# [1] 2
The S3 method length.hyperframe() returns the user-perceived length, instead of internal structure length (Listing 20.5), of a hyper data frame. This behavior parallels that of the S3 method base::length.POSIXlt(), which returns the user-perceived length (Listing 20.7) of a POSIXlt object (Listing 20.6), rather than its internal structure length (Listing 20.8).
Listing 20.5: Review: length of hyper data frame, internal-structure
and appends the returned quantiles as numeric-hypercolumns to the input. Example has been discussed extensively in Section 3.3.3.
20.5 Aggregation
The S3 method aggregate.hyperframe()
splits (Section 13.3), according to the grouping level specified in the parameter by,
the hypercolumn(s) that are ppplist(s) (Chapter 28) into list(s) of ppplist;
the hypercolumn(s) that are imlist(s) (Chapter 23) into list(s) of imlist;
the hypercolumn(s) that are fvlist(s) (Chapter 16) into list(s) of fvlist;
the hypercolumn(s) that are solist(s) (Chapter 30) into list(s) of solist.
aggregates, according to the grouping level specified in the parameter by,
the regular column(s) by simply taking their unique-value, as the elements in each column must be all.equal within each grouping of by;
the hypercolumn(s) that are vectorlist(s) (Chapter 32) using the aggregation method provided in the parameter fun (Section 32.4).
returns a hyperframe.
When the primary input is a grouped hyper data frame (Chapter 19, e.g., in Section 3.4), the aggregation may be specified at either one of the nested grouping levels (Section 19.2) \(g_1,\cdots,g_{m-1}\). Aggregation at the lowest grouping level \(g_m\) is ignored, i.e., no aggregation to be performed.
20.6 Aggregate Marks-Statistics from ppp-hypercolumn
The S3 generic function aggregate_marks() has been introduced in Section 27.7 (Table 27.6). The S3 method aggregate_marks.hyperframe()
aggregates the marks of one-and-only-one (Section 20.14) ppp-hypercolumn in the input (Section 28.3);
appends the returned numeric-vectorlist to the input as a new hypercolumn named 'markstats'.
The author uses the hyper data frame flu (Section 10.10) to illustrate the aggregation of relative frequencies of the sole multi-type-mark in the ppp-hypercolumn $pattern.
Review: flu$pattern is a ppp-hypercolumn with one multi-type-mark
As explained in Section 28.3, the S3 method t.vectorlist() (Section 32.3) is the fastest way to extract a “slice” from the numeric-hypercolumn, e.g., flu_mfreq$markstats.
Unfortunately, package spatstat.data (v3.1.9) does not have a hyper data frame with (any) ppp-hypercolumn of
'dataframe'-markformat, to showcase the use of parameter by in the S3 method aggregate_marks.hyperframe().
'vector'-markformat and numeric-marks, to showcase the aggregation by sample mean and standard deviation.
20.7 Create groupedHyperframe
The S3 generic function as.groupedHyperframe() has been introduced in Section 14.1 (Table 14.2). The S3 method as.groupedHyperframe.hyperframe() converts a hyper data frame into a grouped hyper data frame by inspecting and adding a (nested) grouping structure to the input.
Listing 20.9 adds a nested grouping structure ~id/brick to the hyper data frame osteo (Section 10.16).
Listing 20.9: Example: function as.groupedHyperframe.hyperframe()
The author creates a hyper data frame fluM1 which consists of the same columns as fluM, but a ppp-hypercolumn pattern with M1 marks only. Similarly, the author creates another hyper data frame fluM2 which consists of the M2 marks only. Note that as of package spatstat.geom v3.6.1, the tedious code below is the only way to avoid using the row names of hyper data frame as the element-names of the hypercolumns. In other words, function unclass() avoids invoking the S3 method spatstat.geom::`$.hyperframe`(). The S3 method spatstat.geom::`$<-.hyperframe` is fine in this application.
The S3 method superimpose.hyperframe() recreates the hyper data frame fluM by combining the hyper data frames fluM2 and fluM1. Note that the order of fluM2-then-fluM1 matters, because the points are arranged in M2-then-M1 in the original hypercolumn fluM$pattern.
The S3 method spatstat.geom::superimpose.ppplist() (v3.6.1) superimposes all point-patterns from all input ppplists, instead of performing a by-element superimpose of all input ppplists as intended for the S3 method superimpose.hyperframe().
The S3 generic function .rmax() has been introduced in Section 27.10 (Table 27.9). The S3 method .rmax.hyperframe() obtains the default \(r_\text{max}\) of the one-or-more ppp-hypercolumn(s) (Section 28.4) before the (potentially) very slow batch processes.
Example: function .rmax.hyperframe() for Emark_(), Vmark_(), markcorr_(), markvario_() on numeric- and multi-type-mark
s |>.rmax(fun ='K')
Example: function .rmax.hyperframe() for Kcross_() on multi-type-mark
s |>.rmax(fun ='K', i ='CK+.CD8-', j ='CK-.CD8+')s |>.rmax(fun ='K', i ='CK-.CD8+', j ='CK+.CD8-')
Example: function .rmax.hyperframe() for Gcross_() on multi-type-mark
s |>.rmax(fun ='G', i ='CK+.CD8-', j ='CK-.CD8+')s |>.rmax(fun ='G', i ='CK-.CD8+', j ='CK+.CD8-')
Example: function .rmax.hyperframe() for Jcross_() on multi-type-mark
s |>.rmax(fun ='J', i ='CK+.CD8-', j ='CK-.CD8+')s |>.rmax(fun ='J', i ='CK-.CD8+', j ='CK+.CD8-')
20.10 Function Value from fv-Hypercolumns
The S3 generic function keyval() has been introduced in Section 15.1 (Table 15.3). The S3 method keyval.hyperframe()
applies the S3 method keyval.fvlist() (Section 16.3) across all fv-hypercolumns of the input (grouped) hyper data frame;
appends an additional numeric-hypercolumn <mark>.<fv>.<selected_value> to the input (grouped) hyper data frame.
apply the S3 method Gcross_.hyperframe() (Section 20.14) and create an fv-hypercolumn m.G in the returned hyper data frame fluG_v (Listing 20.14);
apply the S3 method keyval.hyperframe() and create a numeric-hypercolumn m.G.y of the recommended function values in the returned hyper data frame fluG_v (Listing 20.14).
apply the S3 method keyval.hyperframe(., key = 'theo') and create a numeric-hypercolumn m.G.theo of the theoretical function values in the returned hyper data frame fluG_v (Listing 20.14).
Listing 20.11: Example: function keyval.hyperframe()
fluG_v = spatstat.data::flu |> spatstat.geom::subset.hyperframe(subset = (stain =='M2-M1') & (virustype =='wt') ) |>Gcross_(i ='M1', j ='M2', r =seq.int(from =0, to =100, by =5)) |>keyval() |>keyval(key ='theo')#
20.11 Cumulative Average Vertical Height of Trapzoidal Integration of fv-Hypercolumn
The S3 generic function cumvtrapz() has been introduced in Section 11.1 (Table 11.1). The S3 method cumvtrapz.hyperframe()
runs the workhorse function cumvtrapz.fvlist() (Section 16.5) across all fv-hypercolumns of the input (grouped) hyper data frame;
appends additional numeric-hypercolumns <mark>.<fv>.cumvtrapz to the input.
The S3 method t.vectorlist() (Section 32.3) is the fastest way to extract a “slice” from a numeric-hypercolumn, e.g., out_fv$hladr.E.cumvtrapz from Chapter 3, Listing 3.1, Listing 3.4, Listing 3.8. The numeric-hypercolumns created by function summary_fv() are 'vectorlist's (although not supported as hypercolumns in hyperframe as of package spatstat.geom v3.6.1), as they contain tabulated values on common \(r\)-vector(s). A “slice” of the hypercolumn out_fv$hladr.E.cumvtrapz at the 5th index of the \(r\)-vector, i.e., \(r=50\), may be extracted by calling the S3 method spatstat.geom::with.hyperframe(), but the S3 method t.vectorlist() is much faster.
Example: function t.vectorlist(); a ‘slice’ from hypercolumn out_fv$hladr.E.cumvtrapz
The S3 generic functions .illegal2theo() and .disrecommend2theo() have been introduced in Section 15.4.1 (Table 15.4, Table 15.5). The S3 methods .illegal2theo.hyperframe() and .disrecommend2theo.hyperframe()
apply the S3 methods .illegal2theo.fvlist() and .disrecommend2theo.fvlist() (Section 16.4) to all fv-hypercolumns of the input (grouped) hyper data frame;
overwrite the fv-hypercolumns in the input (grouped) hyper data frame.
The author uses the hyper data frame flu (Section 10.10) to illustrate this usage.
Example: function kmeans.hyperframe()
set.seed(13); flu_k = spatstat.data::flu |> spatstat.geom::subset.hyperframe(subset = (stain =='M2-M1') & (virustype =='wt')) |>kmeans.hyperframe(formula =~ x + y, centers =3L)flu_k |>class()# [1] "hyperframekm" "hyperframe" "list"flu_k$pattern[1:3]# List of point patterns# # wt M2-M1 13:# Marked planar point pattern: 471 points# Multitype, with levels = M2, M1 # window: rectangle = [0, 3331] x [0, 3331] nm# with k-means clustering of 153, 147, 171 points# # wt M2-M1 22:# Marked planar point pattern: 217 points# Multitype, with levels = M2, M1 # window: rectangle = [0, 3331] x [0, 3331] nm# with k-means clustering of 85, 68, 64 points# # wt M2-M1 27:# Marked planar point pattern: 214 points# Multitype, with levels = M2, M1 # window: rectangle = [0, 3331] x [0, 3331] nm# with k-means clustering of 84, 71, 59 points
20.13.2 Split by \(k\)-Means Clustering
The S3 method split.hyperframekm() splits a hyperframekm by the \(k\)-means clustering indices of the one-and-only-one (Section 20.14) ppp-hypercolumn. The returned object is a grouped hyper data frame with grouping structure
~.id/.cluster, if the input is a hyper data frame
~ <existing/grouping/structure>/.cluster, if the input is a grouped hyper data frame. Note that the grouping level .id is believed to be equivalent to the lowest level of existing grouping structure.
The author uses the hyper data frame flu (Section 10.10) to illustrate this usage.
The S3 methods Emark_.hyperframe(), Vmark_.hyperframe(), etc., in Table 20.1 are user-friendly wrappers of the low-level utility function op_hyperframe(), for batch operation on hyper data frame (Section 3.2). Function op_hyperframe()
performs the batch operation on the one-and-only-oneppp-hypercolumn (Section 28.6) of the input hyper data frame. The batch operation is not designed to handle a hyper data frame containing multiple ppp-hypercolumns, e.g., cetaceans (Section 10.7). Supporting such functionality would require resolving potential name clashes in the marks across multiple ppp-hypercolumns.
column-binds the two-level hierarchical list returned from the previous step to the input hyper data frame.
Becker, Richard A., John M. Chambers, and Allan R. Wilks. 1988. The New S Language. 1st ed. Boca Raton, FL: Chapman; Hall/CRC. https://doi.org/10.1201/9781351074988.
