These packages (Note 1) are a one-person project undergoing rapid evolution. Backward compatibility (per Hadley Wickham) is provided as a courtesy rather than a guarantee.
Until further notice, these packages should
not be used as a basis for research grant applications,
not be cited as an actively maintained tool in a peer-reviewed manuscript,
not be used to support or fulfill requirements for pursuing an academic degree.
In addition, work primarily based on these packages (Note 1) should not be presented at academic conferences or similar scholarly venues.
Furthermore, a person’s ability to use these packages (Note 1) does not necessarily imply an understanding of their underlying mechanisms. Accordingly, demonstration of their use alone should not be considered sufficient evidence of expertise, nor should it be credited as a basis for academic promotion or advancement.
These statements do not apply to the contributors (Tip 1) to these packages (Note 1) with respect to their specific contributions.
These statements do not apply when the maintainer of these packages (Note 1), Tingting Zhan, is credited as the first author, the lead author, and/or the corresponding author in a peer-reviewed manuscript, or as the Principal Investigator or Co-Principal Investigator in a research grant application and/or a final research progress report.
These statements are advisory in nature and do not modify or restrict the rights granted under the GNU General Public License https://www.r-project.org/Licenses/.
The function fv() (v3.8.0, GPL (>= 2)) creates a function-value-table (fv.object), i.e., an R object of S3 class 'fv'.
The S3 generic function as.fv() (v3.8.0, GPL (>= 2)) 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(), for key value, finds various function values (default being the recommended) in a function-value-table, or an R object containing one or more function-value-tables. The term “key” comes from the invisible return of the S3 method plot.fv() (v3.8.0, GPL (>= 2)) (Listing 20.7). Package groupedHyperframe (v0.4.0, GPL-2) implements the following S3 methods (Table 20.3),
Table 20.3: S3 methods of groupedHyperframe::keyval (v0.4.0)
visible
generic
isS4
keyval.fv
FALSE
groupedHyperframe::keyval
FALSE
Listing 20.7: Review: the invisible return of function plot.fv()
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.8 finds the recommended function value in the function-value-table spruces_k (Listing 20.3).
Listing 20.8: Example: function keyval.fv() (Listing 20.3)
The S3 method with.fv() (v3.8.0, GPL (>= 2)) is capable of creating identical returns as the S3 method keyval.fv() (Listing 20.10, Listing 20.11). The internal utility function getValues() defined in the local environment of the S3 group-generic-method Summary.fv() (Listing 20.12) vectorizes all function values. Table 20.4 explains their differences and connections.
20.3 Cumulative Average Vertical Height of Trapzoidal Integration
The S3 method cumvtrapz.fv() (Section 11.2, Table 11.1) calculates the cumulative average vertical height of the trapezoidal integration (Section 11.2) under the recommended function values.
The S3 method visualize_vtrapz.fv() (Section 11.3, Table 11.2) visualizes the cumulative average vertical height of the trapezoidal integration (Section 11.2) under the recommended function values
Listing 20.14: Figure: function visualize_vtrapz.fv() (Listing 20.3)
spruces_k |>visualize_vtrapz(draw.rect =FALSE)
Figure 20.2: Cumulative Average Vertical Height of the Trapezoidal Integration (Section 11.2) of spruces_k (Listing 20.3)
20.4\(r_\text{max}\)
The S3 method .rmax.fv() (Section 36.9, Table 36.13), often used as an internal utility function, simply grabs the maximum value of the \(r\)-vector in a function-value-table.
The function markcorr() (v3.8.0, GPL (>= 2)) is the workhorse inside the functions Emark(), Vmark() and markvario() (v3.8.0, GPL (>= 2)). Function markcorr() provides a default argument of parameter \(r\)-vector (Section 36.9), 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 47, Listing 47.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.17)
The term Legal\(r_\text{max}\) indicates (the index) of the \(r\)-vector, where the last of the consecutive legal (Chapter 47, Listing 47.5) recommended function values appears. Listing 20.19 shows that the last consecutive legal recommended-function-value of the malformed function-value-table fv_mal (Listing 20.17) of \(k_f(r)=1.550\) appears at the 75-th index of the \(r\)-vector, i.e., \(r=74\).
Listing 20.19: Example: lastLegal() of keyval.fv() (Listing 20.17)
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.20). 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.20: 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() |>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.4.0, GPL-2) implements the following S3 methods (Table 20.5, Table 20.6),
Table 20.5: S3 methods of groupedHyperframe::.illegal2theo (v0.4.0)
visible
generic
isS4
.illegal2theo.fv
FALSE
groupedHyperframe::.illegal2theo
FALSE
Table 20.6: S3 methods of groupedHyperframe::.disrecommend2theo (v0.4.0)
visible
generic
isS4
.disrecommend2theo.fv
FALSE
groupedHyperframe::.disrecommend2theo
FALSE
The S3 method .illegal2theo.fv() (Listing 20.21) replaces the recommended function values after the first illegal \(r\) (Section 20.5) of the malformed function-value-table fv_mal (Listing 20.17) with its theoretical values (Figure 20.4).
Listing 20.21: Advanced: function .illegal2theo.fv() (Listing 20.17)
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.17)
Listing 20.23 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.21).
Listing 20.23: Data: coarse versus fine function-value-table
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) })
Listing 20.24: Figure: coarse versus fine function-value-table, trapezoidal integration (Listing 20.23)
Figure 20.6: coarse versus fine function-value-table, trapezoidal integration (Listing 20.23)
20.6.1 Interpolation
20.6.1.1 Linear Interpolation
The function approxfun.fv() creates a linear interpolation from a function-value-table and returns an R object of S3 class 'function'. This is a “pseudo” S3 method, as the workhorse function approxfun() is not an S3 generic function.
The function splinefun.fv() creates a spline interpolation from a function-value-table and returns an R object of S3 class 'function'. This is a “pseudo” S3 method, as the workhorse function splinefun() is not an S3 generic function.
The function interpSpline_.fv() creates a B-spline or a piecewise polynomial spline interpolation from a function-value-table and returns an R object of S3 class 'spline'. This is a “pseudo” S3 method, as the parameterization of the workhorse S3 generic function splines::interpSpline() is not ideal for this purpose.
The function loess.fv() creates a local polynomial regression fit from a function-value-table and returns an R object of S3 class 'loess'. This is a “pseudo” S3 method, as the workhorse function loess() is not an S3 generic function.
Listing 20.30 creates a local polynomial regression (Figure 20.11) of the coarse function-value-table sprucesK$coarse (Listing 20.23), which is mathematically equivalent to the return of the S3 method Smooth.fv() (v3.8.0, GPL (>= 2)) with 'loess' method (Listing 20.31).
Listing 20.30: Example: function loess.fv() (Listing 20.23)
The function ksmooth.fv() creates a kernel regression smoother from a function-value-table and returns an R object of S3 class 'ksmooth'. This is a “pseudo” S3 method, as the workhorse function ksmooth() is not an S3 generic function.
The function smooth.spline.fv() creates a smoothing spline from a function-value-table and returns an R object of S3 class 'smooth.spline'. This is a “pseudo” S3 method, as the workhorse function smooth.spline() is not an S3 generic function.
Listing 20.33 creates a smoothing spline (Figure 20.13) of the coarse function-value-table sprucesK$coarse (Listing 20.23), which is mathematically equivalent to the return of the S3 method Smooth.fv() (v3.8.0, GPL (>= 2)) with 'smooth.spline' method (Listing 20.34).
Listing 20.33: Example: function smooth.spline.fv() (Listing 20.23)
An experienced reader may wonder: is it truly advantageous to compute a coarse function-value-table sprucesK$coarse and then perform interpolation (Section 20.6.1) and/or smoothing (Section 20.6.2), rather than computing a fine function-value-table sprucesK$fine to start with? This is an excellent question! As of package spatstat.explore (v3.8.0, GPL (>= 2)), we observe only minor increase in the computation time of the creation of a function-value-table, even when the grid of the \(r\)-vector is 100 times finer (Listing 20.35, Figure 20.14) via package microbenchmark(Mersmann 2024, v1.5.0, BSD_2_clause + file LICENSE). This observation justifies the use of the plain-and-naïve trapezoidal integration (Chapter 11, Section 11.2) on a fine function-value-table (Figure 20.6, Right), rather than employing more sophisticated numerical integration methods, e.g.,
