14  fvlist from anylist

The examples in Chapter 14 require that the search path contains the following namespaces,

library(groupedHyperframe)

Package groupedHyperframe (v0.3.0.20251020) defines a derived S3 class 'fvlist' for a list of function-value-tables (fv.object, Chapter 13) that shares several common features (Section 14.1). The S3 class 'fvlist' inherits from the class 'anylist' (Chapter 11) with additional attributes (Listing 14.5),

Package groupedHyperframe implements the following S3 method dispatches to the class 'fvlist' (Listing 14.1, Table 14.1),

Listing 14.1: Table: S3 method dispatches groupedHyperframe::*.fvlist
Code
methods2kable(class = 'fvlist', package = 'groupedHyperframe', all.names = TRUE)
Table 14.1: S3 method dispatches groupedHyperframe::*.fvlist (v0.3.0.20251020)
visible from generic isS4
.disrecommend2theo.fvlist TRUE groupedHyperframe groupedHyperframe::.disrecommend2theo FALSE
.illegal2theo.fvlist TRUE groupedHyperframe groupedHyperframe::.illegal2theo FALSE
print.fvlist TRUE groupedHyperframe base::print FALSE
summary.fvlist TRUE groupedHyperframe base::summary FALSE
visualize_vtrapz.fvlist TRUE groupedHyperframe groupedHyperframe::visualize_vtrapz FALSE

Listing 14.2 creates a malformed function-value-table list sprucesE_ using the S3 method dispatch Emark_.ppplist() (Section 24.7) and the point-pattern object spruces (Section 8.17).

Listing 14.2: Data: a malformed fvlist sprucesE_
sprucesE_ = spatstat.geom::solist(
  spatstat.data::spruces,
  spatstat.data::spruces
) |> 
  Emark_(r = seq.int(from = 0, to = 100, by = 10))
# Legal rmax(m.E), smaller than user input of rmax = 100.0, are
# 2⨯ rmax=80 at location 1L, 2L
# 

14.1 Validity

Function is.fvlist() requires that all the members of a list of fv.objects (Chapter 13) share certain identical properties (Table 14.2). Some of these properties are also required by the low-level utility function spatstat.explore::bind.fv() (v3.5.3.3).

Table 14.2: Validity Requirements of S3 Class 'fvlist' vs. Function spatstat.explore::bind.fv()
Requirement Description S3 Class 'fvlist' spatstat.explore::bind.fv()
Function arguments Values of the \(r\)-vector Required Required
Name of function argument Listing 13.4 Required Not Required(?)
Name of recommended-function-value Listing 13.5 Required Not Required(?)
Function name (and additional information) attr(,'fname') Required Not Required(?)
Listing 14.3: Example: function is.fvlist()
Code
stopifnot(is.fvlist(sprucesE_$m.E))

14.2 Creation

Function as.fvlist() (Listing 14.4) converts a listof fv.objects, that passes the validity check (Section 14.1, Table 14.2), to an object of S3 class 'fvlist'.

Listing 14.4: Example: function as.fvlist() to create fvlist_mal
fvlist_mal = sprucesE_$m.E |>
  as.fvlist()
Listing 14.5: Advanced: base::attributes() of S3 class 'fvlist'
Code
fvlist_mal |> 
  attributes()
# $class
# [1] "fvlist"  "anylist" "listof"  "list"   
# 
# $r
#  [1]   0  10  20  30  40  50  60  70  80  90 100
# 
# $.x
# [1] "r"
# 
# $.y
# [1] "un"
# 
# $fname
# [1] "E"
# 
# $rmax
# [1] 80

The S3 method dispatch print.fvlist() (Listing 14.6) prints the vital information of an 'fvlist'.

Listing 14.6: Example: function print.fvlist()
fvlist_mal
# An 'fvlist' of 2 fv.objects E(r)
# Available rmax: 100
# Minimum Legal rmax: 80

14.3 Truncated Summary

The S3 method dispatch summary.fvlist() performs a truncated summary of an fvlist (Section 14.1), either

  • at an optional user-specified \(r_\text{max}\) in parameter rmax (user-rmax for short), or
  • at the minimum Legal \(r_\text{max}\) (Section 13.3) of all fv.objects (Chapter 13).

Specifically, the truncation is performed under the following rules,

  • if user-rmax is missing, then the fv.objects are truncated at the minimum Legal \(r_\text{max}\) attr(,'rmax').
  • if user-rmax is greater than the minimum Legal \(r_\text{max}\) attr(,'rmax'), then the fv.objects are truncated at the minimum Legal \(r_\text{max}\) attr(,'rmax') and the user rmax is ignored (Listing 14.7).
  • if user-rmax is less than or equal to the minimum Legal \(r_\text{max}\) attr(,'rmax'), then the fv.objects are truncated at the user rmax (Listing 14.8).

The S3 method dispatch summary.fvlist() returns a list with elements

  • $y, the (truncated) recommended-function-values (Section 13.1), per fv.object;
  • $cumtrapz, the (truncated) cumulative trapezoidal integration of the recommended-function-values, after removing the first 0-value (Chapter 9), per fv.object;
  • $cumvtrapz, the (truncated) cumulative average vertical height of the trapezoidal integration of the recommended-function-values, after removing the first NaN-value (Section 9.1), per fv.object.
Listing 14.7: Example: function summary.fvlist(), user \(r_\text{max}>\) minimum Legal \(r_\text{max}\)
Code
fvlist_mal |>
  summary(rmax = 85)
# summary.fvlist truncated at rmax(fvlist_mal) = 80.0 (user rmax = 85.0 ignored)
# $y
# $y[[1]]
#         0        10        20        30        40        50        60        70        80 
# 0.2456091 0.2486755 0.2499532 0.2523455 0.2505328 0.2527705 0.2406730 0.2766159 0.4502869 
# 
# $y[[2]]
#         0        10        20        30        40        50        60        70        80 
# 0.2456091 0.2486755 0.2499532 0.2523455 0.2505328 0.2527705 0.2406730 0.2766159 0.4502869 
# 
# 
# $cumtrapz
# $cumtrapz[[1]]
#        10        20        30        40        50        60        70        80 
#  2.471423  4.964566  7.476059  9.990451 12.506967 14.974185 17.560629 21.195143 
# 
# $cumtrapz[[2]]
#        10        20        30        40        50        60        70        80 
#  2.471423  4.964566  7.476059  9.990451 12.506967 14.974185 17.560629 21.195143 
# 
# 
# $cumvtrapz
# $cumvtrapz[[1]]
#        10        20        30        40        50        60        70        80 
# 0.2471423 0.2482283 0.2492020 0.2497613 0.2501393 0.2495697 0.2508661 0.2649393 
# 
# $cumvtrapz[[2]]
#        10        20        30        40        50        60        70        80 
# 0.2471423 0.2482283 0.2492020 0.2497613 0.2501393 0.2495697 0.2508661 0.2649393
Listing 14.8: Example: function summary.fvlist(), user \(r_\text{max}\leq\) minimum Legal \(r_\text{max}\)
Code
fvlist_mal |>
  summary(rmax = 70)
# summary.fvlist truncated at rmax = 70.0 for fvlist_mal
# $y
# $y[[1]]
#         0        10        20        30        40        50        60        70 
# 0.2456091 0.2486755 0.2499532 0.2523455 0.2505328 0.2527705 0.2406730 0.2766159 
# 
# $y[[2]]
#         0        10        20        30        40        50        60        70 
# 0.2456091 0.2486755 0.2499532 0.2523455 0.2505328 0.2527705 0.2406730 0.2766159 
# 
# 
# $cumtrapz
# $cumtrapz[[1]]
#        10        20        30        40        50        60        70 
#  2.471423  4.964566  7.476059  9.990451 12.506967 14.974185 17.560629 
# 
# $cumtrapz[[2]]
#        10        20        30        40        50        60        70 
#  2.471423  4.964566  7.476059  9.990451 12.506967 14.974185 17.560629 
# 
# 
# $cumvtrapz
# $cumvtrapz[[1]]
#        10        20        30        40        50        60        70 
# 0.2471423 0.2482283 0.2492020 0.2497613 0.2501393 0.2495697 0.2508661 
# 
# $cumvtrapz[[2]]
#        10        20        30        40        50        60        70 
# 0.2471423 0.2482283 0.2492020 0.2497613 0.2501393 0.2495697 0.2508661

The truncated summary is important, because the exceptional/illegal recommended-function-values (Section 13.3) cause problems in downstream analyses.

14.4 Handling Illegal Recommended-Function-Value

The S3 generic functions .illegal2theo() and .disrecommend2theo() have been introduced in Section 13.3.1.

The S3 method dispatches .illegal2theo.fvlist() (Listing 14.9) and .disrecommend2theo.fvlist() (Listing 14.10) are simply iterations of the S3 method dispatches .illegal2theo.fv() and .disrecommend2theo.fv() (Section 13.3.1).

Listing 14.9: Advanced: functions .illegal2theo.fvlist() and .disrecommend2theo.fvlist()
fvlist_mal |> 
  .illegal2theo()
# r≥90.0 replaced with theo
# r≥90.0 replaced with theo
# An 'fvlist' of 2 fv.objects E(r)
# Available rmax: 100
# Minimum Legal rmax: 100
Listing 14.10: Advanced: functions .illegal2theo.fvlist() and .disrecommend2theo.fvlist()
fvlist_mal |> 
  .disrecommend2theo()
# r≥10.0 replaced with theo
# r≥10.0 replaced with theo
# An 'fvlist' of 2 fv.objects E(r)
# Available rmax: 100
# Minimum Legal rmax: 100