The S3 generic function spatstat.explore::as.fv() converts R objects of various classes into a function-value-table. Listing 20.1 summarizes the S3 methods for the generic function as.fv() in the spatstat.* family of packages,
spruces_k |> spatstat.explore::print.fv()# Function value object (class 'fv')# for the function r -> k[mm](r)# ................................................................................# Math.label Description # r r distance argument r # theo {k[mm]^{iid}}(r) theoretical value (independent marks) for k[mm](r)# trans {hat(k)[mm]^{trans}}(r) translation-corrected estimate of k[mm](r) # iso {hat(k)[mm]^{iso}}(r) Ripley isotropic correction estimate of k[mm](r) # ................................................................................# Default plot formula: .~r# where "." stands for 'iso', 'trans', 'theo'# Recommended range of argument r: [0, 9.5]# Available range of argument r: [0, 9.5]# Unit of length: 1 metre
The S3 generic function keyval() finds various function values (default being the recommended) in a function-value-table, or an R object containing one or more function-value-tables. Package groupedHyperframe (v0.3.2.20251225) implements the following S3 methods (Table 20.3),
Table 20.3: S3 methods of groupedHyperframe::keyval (v0.3.2.20251225)
visible
isS4
keyval.fv
TRUE
FALSE
keyval.fvlist
TRUE
FALSE
keyval.hyperframe
TRUE
FALSE
The S3 method keyval.fv() finds various function values (default being the recommended) in a function-value-table, with the corresponding function argument as the vector names.
Listing 20.7 finds the recommended function value in the function-value-table spruces_k (Listing 20.3).
Listing 20.7: Example: function keyval.fv() (Listing 20.3)
20.3 Cumulative Average Vertical Height of Trapzoidal Integration
The S3 method cumvtrapz.fv() (Section 11.1, Table 11.1) calculates the cumulative average vertical height of the trapezoidal integration (Section 11.1) under the recommended function values.
The S3 method visualize_vtrapz.fv() (Section 11.2, Table 11.2) visualizes the cumulative average vertical height of the trapezoidal integration (Section 11.1) under the recommended function values
Figure 20.2: cumvtrapz of markcorr() (Listing 20.3)
20.4\(r_\text{max}\)
The S3 method .rmax.fv() (Section 36.10, Table 36.11), often used as an internal utility function, simply grabs the maximum value of the \(r\)-vector in a function-value-table.
Function spatstat.explore::markcorr() is the workhorse inside the functions Emark(), Vmark() and markvario() (v3.6.0.5). Function markcorr() provides a default argument of parameter \(r\)-vector (Section 36.10), at which the mark correlation function \(k_f(r)\) are evaluated. Function markcorr() relies on the un-exported workhorse function spatstat.explore:::sewsmod(), whose default method = "density" contains a ratio of two kernel density estimates. Exceptional/illegal values of 0, Inf and/or NaN (Chapter 44, Listing 44.1) may appear in the return of function markcorr(), if the \(r\)-vector goes well beyond the recommended range (Listing 20.4).
Figure 20.3: A malformed function-value-table fv_mal (Listing 20.14)
The term Legal\(r_\text{max}\) indicates (the index) of the \(r\)-vector, where the last of the consecutive legal (Chapter 44, Listing 44.5) recommended function values appears. Listing 20.16 shows that the last consecutive legal recommended-function-value of the malformed function-value-table fv_mal (Listing 20.14) of \(k_f(r)=1.550\) appears at the 75-th index of the \(r\)-vector, i.e., \(r=74\).
Listing 20.16: Example: lastLegal() of keyval.fv() (Listing 20.14)
Legality of the function markcorr() returns depends not only on the input point-pattern, but also on the values of the \(r\)-vector (Listing 20.17). In other words, the creation of a function-value-table is a numerical procedure. Therefore, the discussion of Legal \(r_\text{max}\) pertains to the function-value-table (fv.object, Chapter 20), instead of to the point-pattern (ppp.object, Chapter 36).
Listing 20.17: Example: Legality of markcorr() return depends on \(r\)-vector
spatstat.data::spruces |> spatstat.explore::markcorr(r =seq.int(from =0, to =100, by = .1)) |>keyval.fv() |>lastLegal()# [1] 742# attr(,"value")# 74.1 # 0.3191326
The S3 generic functions .illegal2theo() and .disrecommend2theo() are exploratory approaches to remove the illegal recommended function values (Section 20.5) from a function-value-table. These approaches replace the recommended function values with the theoretical values starting at different locations in the function argument (Table 20.2, Listing 20.6), and return an updated function-value-table. Package groupedHyperframe (v0.3.2.20251225) implements the following S3 methods (Table 20.5, Table 20.6),
Table 20.5: S3 methods of groupedHyperframe::.illegal2theo (v0.3.2.20251225)
visible
isS4
.illegal2theo.fv
TRUE
FALSE
.illegal2theo.fvlist
TRUE
FALSE
.illegal2theo.hyperframe
TRUE
FALSE
Table 20.6: S3 methods of groupedHyperframe::.disrecommend2theo (v0.3.2.20251225)
visible
isS4
.disrecommend2theo.fv
TRUE
FALSE
.disrecommend2theo.fvlist
TRUE
FALSE
.disrecommend2theo.hyperframe
TRUE
FALSE
The S3 method .illegal2theo.fv() (Listing 20.18) replaces the recommended function values after the first illegal \(r\) (Section 20.5) of the malformed function-value-table fv_mal (Listing 20.14) with its theoretical values (Figure 20.4).
Listing 20.18: Advanced: function .illegal2theo.fv() (Listing 20.14)
par(mar =c(4, 4, 1, 1))fv_mal |>.illegal2theo() |> spatstat.explore::plot.fv(xlim =c(0, 100), main =NULL)# r≥75.0 replaced with theo
Figure 20.4: Replaces with theoretical values after the first illegal \(r\) (Listing 20.14)
Listing 20.20 creates the toy examples of a coarse and a fine function-value-table at a coarse and a fine\(r\)-vector for the mark correlation of the point-pattern spruces (Section 10.19).
Listing 20.20: Data: coarse versus finefv.object
r =list(coarse =0:9,fine =seq.int(from =0, to =9, by = .01))sprucesK = r |>lapply(FUN = \(r) { spatstat.data::spruces |> spatstat.explore::markcorr(r = r) })
An experienced reader may wonder: is it truly advantageous to compute a coarse function-value-table and then perform interpolation and/or smoothing, rather than computing a fine function-value-table to start with? This is an excellent question! In fact, we observe no substantial difference in computation time via package microbenchmark(Mersmann 2024, v1.5.0) even when the grid of the \(r\)-vector is 100 times finer (Listing 20.24), as of package spatstat.explore (v3.6.0.5)! This observation justifies the use of the plain-and-naïve trapezoidal integration (Chapter 11, Section 11.1) on a finefv.object (Figure 20.9, Right), rather than employing more sophisticated numerical integration methods, e.g., the Simpson’s rulepracma::simpson(), the adaptive Simpson quadraturepracma::quad(), etc. on an interpolation and/or smoothing of a coarsefv.object (Figure 20.6, Figure 20.7, Figure 20.8).
Listing 20.24: Advanced: coarse versus fine function-value-table, benchmarks (Listing 20.20)
suppressPackageStartupMessages(library(spatstat))microbenchmark::microbenchmark(coarse =Emark(spruces, r = r$coarse),fine =Emark(spruces, r = r$fine)) |>suppressWarnings()# Unit: milliseconds# expr min lq mean median uq max neval cld# coarse 2.015478 2.049241 2.279279 2.080156 2.144177 7.284921 100 a # fine 2.365003 2.412953 2.599631 2.481689 2.524596 5.644839 100 b
Listing 20.25: Figure: coarse versus fine function-value-table, trapezoidal integration (Listing 20.20)
