Function spatstat.geom::hyperframe() creates a hyper data frame, i.e., an R object of S3 class 'hyperframe'.
The S3 generic function spatstat.geom::as.hyperframe() converts R objects of various classes into a hyper data frame. Listing 25.1 summarizes the S3 methods for the generic function as.hyperframe() in the spatstat.* family of packages,
Section 25.2 is intended as an educational handbook for beginners to package spatstat.geom (v3.7.0.6). This section does not discuss the functionality of package groupedHyperframe (v0.3.4).
The S3 method length.hyperframe() finds the number of columns and/or hypercolumns of a hyper data frame. Table 25.2 explains its rational and similarity to other length methods in package base shipped with R version 4.5.2 (2025-10-31).
Table 25.2: Rational of S3 Method length.hyperframe()
Listing 25.6 reveals that the data frame Formaldehyde from package datasets shipped with R version 4.5.2 (2025-10-31) has 2 columns, using the .PrimitiveS3 generic function base::length().
Listing 25.6: Review: function base::length() on data.frame
datasets::Formaldehyde |>length()# [1] 2
Listing 25.7 reveals that the hyper data frame demohyper (Section 9.9) has 3 (hyper)columns. The internal structure length of a hyper data frame (Listing 25.8) is not relevant to end users and may change without notice in package spatstat.geom (v3.7.0.6).
Listing 25.7: Example: function length.hyperframe()
spatstat.data::demohyper |>length()# [1] 3
Listing 25.8: Review: length of hyper data frame, internal-structure
of the numeric marks in the one-and-only-one point-pattern (ppp) hypercolumn (Section 36.3).
and appends the returned quantiles as numeric-hypercolumns to the input. Example has been discussed extensively in Section 2.3.3.
25.6 Aggregation
The S3 method aggregate.hyperframe()
splits (Section 14.5), according to the grouping level specified in the parameter by,
the hypercolumn(s) that are ppplist (Chapter 36) into list(s) of ppplist;
the hypercolumn(s) that are imlist (Chapter 28) into list(s) of imlist;
the hypercolumn(s) that are fvlist (Chapter 20) into list(s) of fvlist;
the hypercolumn(s) that are solist (Chapter 38) 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 vector-lists (vectorlist, Chapter 42) using the aggregation method provided in the parameter fun (Section 42.4).
returns a hyper data frame.
When the primary input is a grouped hyper data frame (Chapter 24, e.g., in Section 2.4), the aggregation may be specified at either one of the nested grouping levels (Chapter 48) \(g_1,\cdots,g_{m-1}\). Aggregation at the lowest grouping level \(g_m\) is ignored, i.e., no aggregation to be performed.
25.7 Aggregate Marks-Statistics from ppp-Hypercolumn
aggregates the marks of one-and-only-one (Section 25.13) ppp-hypercolumn in the input hyper data frame, using the S3 method aggregate_marks.ppplist() (Section 36.4);
appends the returned numeric vector-list (vectorlist, Chapter 42) to the input as a new hypercolumn named $markstats.
Listing 25.11 aggregates the relative frequencies of the 'M2' and 'M1' marks in each member of the ppp-hypercolumn fluM$pattern (Listing 25.3, Listing 25.4).
Listing 25.11: Example: function aggregate_marks.hyperframe(), for relative frequencies (Listing 25.3)
As explained in Section 36.4, the S3 method t.vectorlist() (Section 42.3) is the fastest way to extract a “slice” from the numeric-hypercolumn, e.g., fluM_relfreq$markstats.
Listing 25.13: Advanced: function t.vectorlist() (Listing 25.11)
fluM_relfreq$markstats |>t.vectorlist()# A 'vectorlist' of 2 vectors # Name(s): M2, M1 # Storage Mode: numeric # Individual Vector Length: 8
Unfortunately, package spatstat.data (v3.1.9) does not have a hyper data frame with (any) ppp-hypercolumn of
'dataframe' mark-format, to showcase the use of parameter by (Section 35.7.3.1).
'vector' mark-format and numeric marks, to showcase the aggregation by sample mean and standard deviation.
25.8 Create groupedHyperframe
The S3 method as.groupedHyperframe.hyperframe() (Section 17.1, Table 17.2) converts a hyper data frame into a grouped hyper data frame by inspecting and adding a (nested) grouping structure to the input.
Listing 25.14 adds a nested grouping structure ~id/brick to the hyper data frame osteo (Section 9.20).
Listing 25.14: Example: function as.groupedHyperframe.hyperframe()
names and class of the hyper columns, i.e., unclass(.)$hypercolumns
The hypercolumn fluM$pattern (Listing 25.3) contains 8 point-patterns, each of them has 200-500 points (Listing 25.4). Listing 25.16 creates a hyper data frame fluM1 which consists of the same columns as fluM, but a ppp-hypercolumn $pattern with M1 marks only; and another hyper data frame fluM2 which consists of the M2 marks only.
Listing 25.16: Data: two hyper data frames fluM1 and fluM2 (Listing 25.3)
Listing 25.17 recreates the hyper data frame fluM (Listing 25.3) by superimposing the hyper data frames fluM2 and fluM1 (Listing 25.16). Note that the order of fluM2-then-fluM1 matters, because the points are arranged in M2-then-M1 in the original hypercolumn fluM$pattern (Listing 25.3, Listing 25.4).
extracts the specified attribute per element, per hypercolumn of a hyper data frame;
appends these attributes, if exist, to the input hyper data frame as columns or hypercolumns, named in the fashion of $<hypercolumn>.<which>.
Examples of the S3 method attr_.hyperframe() are Listing 25.19.
25.11 Default \(r_\text{max}\)
The S3 method .rmax.hyperframe() (Section 35.10, Table 35.13) obtains the default \(r_\text{max}\) of the one-or-more ppp-hypercolumn(s) (Section 36.6) 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-')
25.12 Random Re-Labelling Envelope Residual & Test
applies the S3 method global_envelope_test_.anylist() (Section 14.3) to one or more 'curve_set' (Chapter 16) hypercolumn(s) of the input hyper data frame;
appends one or more 'global_envelope' (Chapter 22) hypercolumn(s) to the input hyper data frame, named in the fashion of $<curve_set>.GET.
Listing 25.19 performs the random re-labelling envelope residual and test on the ppp-hypercolumn fluM$pattern (Listing 25.3), and creates a hyper data frame with
a 'curve_set' hypercolumn $.rlabelRes;
a 'global_envelope' hypercolumn $.rlabelRes.GET;
a numeric column $.rlabelRes.GET.p, the \(p\)-values per element of the hypercolumn $.rlabelRes.GET.
The S3 methods Emark_.hyperframe(), Vmark_.hyperframe(), etc., in Table 25.1 are user-friendly wrappers of the low-level utility function op_hyperframe(), for batch operation on hyper data frame (Section 2.2). Function op_hyperframe()
performs the batch operation on the one-and-only-oneppp-hypercolumn (Section 36.9) 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 9.8). 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.
Listing 25.20 calls the S3 method Gcross_.hyperframe() to
apply the S3 method Gcross_.ppplist() (Section 36.9) to the ppp-hypercolumn fluM$pattern (Listing 25.3);
append an fv-hypercolumn $m.G to the input hyper data frame.
Listing 25.20: Data: a hyper data frame fluG (Listing 25.3)
create a numeric-hypercolumn $m.G.y of the recommended function values of the fv-hypercolumn fluG$m.G in the returned hyper data frame, using the S3 method keyval.hyperframe();
create a numeric-hypercolumn $m.G.theo of the theoretical function values of the fv-hypercolumn fluG$m.G in the returned hyper data frame, using the S3 method keyval.hyperframe(., key = 'theo').
Listing 25.21: Example: function keyval.hyperframe() (Listing 25.20)
runs the workhorse function cumvtrapz.fvlist() (Section 20.6) across all fv-hypercolumns of the input hyper data frame;
appends additional numeric-hypercolumns $<mark>.<fv>.cumvtrapz to the input hyper data frame;
returns a hyper data frame.
Listing 25.22 applies the S3 method cumvtrapz.hyperframe() to the hyper data frame fluG (Listing 25.20) and creates a numeric-hypercolumn $m.G.cumvtrapz from the fv-hypercolumn fluG$m.G in the returned hyper data frame fluG_vt.
Listing 25.22: Example: function cumvtrapz.hyperframe() (Listing 25.20)
The S3 method t.vectorlist() (Section 42.3) is the fastest way to extract a “slice” from a numeric-hypercolumn, e.g., fluG_vt$m.G.cumvtrapz (Listing 25.22), which is a 'vectorlist' (Chapter 42) although not supported as a hypercolumn in hyper data frame as of package spatstat.geom (v3.7.0.6). A “slice” of the hypercolumn fluG_vt$m.G.cumvtrapz at the 50th index of the \(r\)-vector, i.e., \(r=50\), may be extracted by calling the S3 method spatstat.geom::with.hyperframe() (Listing 25.24), but the S3 method t.vectorlist() (Listing 25.23) is much faster.
Listing 25.23: Advanced: function t.vectorlist() (Listing 25.22)
apply the S3 methods .illegal2theo.fvlist() and .disrecommend2theo.fvlist() (Section 20.5), respectively, to all fv-hypercolumns of the input hyper data frame;
overwrite the fv-hypercolumns in the input hyper data frame;
return a hyper data frame.
Listing 25.25 applies the S3 method .disrecommend2theo.hyperframe() on the hyper data frame fluG (Listing 25.20) and overwrites the fv-hypercolumn $m.G in the returned hyper data frame.
Listing 25.25: Example: function .disrecommend2theo.hyperframe() (Listing 25.20)
The S3 method split.hyperframekm() splits a hyperframekm by the \(k\)-means clustering indices of the one-and-only-one (Section 25.13) 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.
Listing 25.29 splits the hyper data frame fluM (Listing 25.3) by the \(k\)-means clustering of the ppp-hypercolumn fluM$pattern.
Listing 25.29: Example: function split.hyperframekm() (Listing 25.3)
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.
