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 26.1 summarizes the S3 methods for the generic function as.hyperframe() in the spatstat.* family of packages,
Section 26.2 is intended as an educational handbook for beginners to package spatstat.geom (v3.6.1.16). This section does not discuss the functionality of package groupedHyperframe (v0.3.2.20251225).
The S3 method length.hyperframe() finds the number of columns and/or hypercolumns of a hyper data frame. Table 26.2 explains its rational and similarity to other length methods in package base shipped with R version 4.5.2 (2025-10-31).
Table 26.2: Rational of S3 Method length.hyperframe()
Listing 26.5 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 26.5: Review: function base::length() on data.frame
datasets::Formaldehyde |>length()# [1] 2
Listing 26.6 reveals that the hyper data frame demohyper (Section 10.8) has 3 (hyper)columns. The internal structure length of a hyper data frame (Listing 26.7) is not relevant to end users and may change without notice in package spatstat.geom (v3.6.1.16).
Listing 26.6: Example: function length.hyperframe()
spatstat.data::demohyper |>length()# [1] 3
Listing 26.7: 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.
26.6 Aggregation
The S3 method aggregate.hyperframe()
splits (Section 15.5), according to the grouping level specified in the parameter by,
the hypercolumn(s) that are ppplist(s) (Chapter 37) into list(s) of ppplist;
the hypercolumn(s) that are imlist(s) (Chapter 29) into list(s) of imlist;
the hypercolumn(s) that are fvlist(s) (Chapter 21) into list(s) of fvlist;
the hypercolumn(s) that are solist(s) (Chapter 39) 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 41) using the aggregation method provided in the parameter fun (Section 41.4).
returns a hyperframe.
When the primary input is a grouped hyper data frame (Chapter 25, e.g., in Section 3.4), the aggregation may be specified at either one of the nested grouping levels (Chapter 46) \(g_1,\cdots,g_{m-1}\). Aggregation at the lowest grouping level \(g_m\) is ignored, i.e., no aggregation to be performed.
26.7 Aggregate Marks-Statistics from ppp-hypercolumn
aggregates the marks of one-and-only-one (Section 26.13) ppp-hypercolumn in the input hyper data frame, using the S3 method aggregate_marks.ppplist() (Section 37.4);
appends the returned numeric-vectorlist to the input as a new hypercolumn named 'markstats'.
Listing 26.10 shows the hyper data frame flu (Section 10.10) has a ppp-hypercolumn with one multi-type mark.
As explained in Section 37.4, the S3 method t.vectorlist() (Section 41.3) is the fastest way to extract a “slice” from the numeric-hypercolumn, e.g., flu_mfreq$markstats.
Listing 26.13: Advanced: function t.vectorlist() (Listing 26.11)
flu_mfreq$markstats[1:4] |>t.vectorlist()# A 'vectorlist' of 2 vectors # Name(s): M2, M1 # Storage Mode: numeric # Individual Vector Length: 4
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 in the S3 method aggregate_marks.hyperframe().
'vector' mark-format and numeric marks, to showcase the aggregation by sample mean and standard deviation.
26.8 Create groupedHyperframe
The S3 method as.groupedHyperframe.hyperframe() (Section 18.1, Table 18.2) converts a hyper data frame into a grouped hyper data frame by inspecting and adding a (nested) grouping structure to the input.
Listing 26.18 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. Note that as of package spatstat.geom v3.6.1.16, the tedious code in Listing 26.18 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.
Listing 26.18: Data: two hyper data frames fluM1 and fluM2
Listing 26.21 recreates the hyper data frame fluM (Listing 26.3) by superimposing the hyper data frames fluM2 and fluM1 (Listing 26.18). Note that the order of fluM2-then-fluM1 matters, because the points are arranged in M2-then-M1 in the original hypercolumn fluM$pattern.
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 26.23.
26.11 Default \(r_\text{max}\)
The S3 method .rmax.hyperframe() (Section 36.10, Table 36.11) obtains the default \(r_\text{max}\) of the one-or-more ppp-hypercolumn(s) (Section 37.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-')
26.12 Random Re-Labelling Envelope Residual & Test
applies the S3 method global_envelope_test_.anylist() (Section 15.3) to the 'curve_set' (Chapter 17) hypercolumn(s) of the input hyper data frame;
appends the 'global_envelope' (Chapter 23) hypercolumn(s) to the input hyper data frame, named in the fashion of $<curve_set>.GET.
Listing 26.23 performs the random re-labelling envelope residual and test on the ppp-hypercolumn fluM$pattern (Listing 26.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.
Listing 26.23: Example: functions rlabelRes.hyperframe(), global_envelope_test_.hyperframe() and attr_.hyperframe() (Section 26.10) on fluM (Listing 26.3)
The S3 methods Emark_.hyperframe(), Vmark_.hyperframe(), etc., in Table 26.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 37.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 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.
Listing 26.24 calls the S3 method Gcross_.hyperframe() to
create an fv-hypercolumn $m.G by applying the S3 method Gcross_.ppplist() (Section 37.9) to the ppp-hypercolumn fluM$pattern (Listing 26.3);
return a hyper data frame fluG.
Listing 26.24: Data: a hyper data frame fluG (Listing 26.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 26.25: Example: function keyval.hyperframe() (Listing 26.24)
runs the workhorse function cumvtrapz.fvlist() (Section 21.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 26.26 applies the S3 method cumvtrapz.hyperframe() to the hyper data frame fluG (Listing 26.24) and creates a numeric-hypercolumn $m.G.cumvtrapz from the fv-hypercolumn fluG$m.G in the returned hyper data frame fluG_vt.
Listing 26.26: Example: function cumvtrapz.hyperframe() (Listing 26.24)
The S3 method t.vectorlist() (Section 41.3) is the fastest way to extract a “slice” from a numeric-hypercolumn, e.g., fluG_vt$m.G.cumvtrapz (Listing 26.26), which is a 'vectorlist' (Chapter 41) although not supported as a hypercolumn in hyper data frame as of package spatstat.geom (v3.6.1.16). 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 26.28), but the S3 method t.vectorlist() (Listing 26.27) is much faster.
Listing 26.27: Advanced: function t.vectorlist() (Listing 26.26)
The S3 generic functions .illegal2theo() and .disrecommend2theo() have been introduced in Section 20.5.1 (Table 20.5, Table 20.6). The S3 methods .illegal2theo.hyperframe() and .disrecommend2theo.hyperframe()
apply the S3 methods .illegal2theo.fvlist() and .disrecommend2theo.fvlist() (Section 21.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 26.29 applies the S3 method .disrecommend2theo.hyperframe() on the hyper data frame fluG (Listing 26.24) and overwrites the fv-hypercolumn $m.G in the returned hyper data frame.
Listing 26.29: Example: function .disrecommend2theo.hyperframe() (Listing 26.24)
The S3 method split.hyperframekm() splits a hyperframekm by the \(k\)-means clustering indices of the one-and-only-one (Section 26.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 26.33 splits the hyper data frame fluM (Listing 26.3) by the \(k\)-means clustering of the ppp-hypercolumn fluM$pattern.
Listing 26.33: Example: function split.hyperframekm() (Listing 26.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.
