21 `fvlist` from `anylist`

The examples in Chapter 21 require

library(groupedHyperframe)

search path & loadedNamespaces on author’s computer

search()
#  [1] ".GlobalEnv"                "package:groupedHyperframe" "package:stats"             "package:graphics"          "package:grDevices"         "package:utils"             "package:datasets"         
#  [8] "package:methods"           "Autoloads"                 "package:base"
loadedNamespaces() |> sort.int()
#  [1] "abind"             "base"              "cli"               "cluster"           "codetools"         "compiler"          "datasets"          "deldir"            "digest"           
# [10] "doParallel"        "dplyr"             "evaluate"          "farver"            "fastmap"           "fastmatrix"        "foreach"           "generics"          "geomtextpath"     
# [19] "GET"               "ggplot2"           "glue"              "goftest"           "graphics"          "grDevices"         "grid"              "gridExtra"         "groupedHyperframe"
# [28] "gtable"            "htmltools"         "htmlwidgets"       "iterators"         "jsonlite"          "knitr"             "lattice"           "lifecycle"         "magrittr"         
# [37] "Matrix"            "matrixStats"       "methods"           "nlme"              "otel"              "parallel"          "patchwork"         "pillar"            "pkgconfig"        
# [46] "polyclip"          "pracma"            "R6"                "RColorBrewer"      "rlang"             "rmarkdown"         "rstudioapi"        "S7"                "scales"           
# [55] "SpatialPack"       "spatstat.data"     "spatstat.explore"  "spatstat.geom"     "spatstat.random"   "spatstat.sparse"   "spatstat.univar"   "spatstat.utils"    "stats"            
# [64] "systemfonts"       "tensor"            "textshaping"       "tibble"            "tidyselect"        "tools"             "utils"             "vctrs"             "viridisLite"      
# [73] "xfun"              "yaml"

Package groupedHyperframe (v0.3.2.20251225) defines a derived S3 class 'fvlist' for a list of function-value-tables (fv.object, Chapter 20) that shares several common features (Section 21.2). The S3 class 'fvlist' inherits from the class 'anylist' (Chapter 15) with additional attributes (Listing 21.7),

attr(,'r'), a numeric vector, the values of the \(r\)-vector;
attr(,'.x'), a character scalar, the name of the function argument;
attr(,'.y'), a character scalar, the name of the recommended-function-value;
attr(,'fname'), a character scalar or vector, the function name (and additional information);
attr(,'rmax'), a numeric scalar, the minimum Legal \(r_\text{max}\) (Section 20.5) of all fv.objects, which is obviously <= max(attr(,'r')).

Table 21.1 summarizes the S3 methods for the class 'fvlist' in package groupedHyperframe (v0.3.2.20251225),

Table 21.1: S3 methods groupedHyperframe::*.fvlist (v0.3.2.20251225)

	visible	generic	isS4
`.disrecommend2theo.fvlist`	TRUE	`groupedHyperframe::.disrecommend2theo`	FALSE
`.illegal2theo.fvlist`	TRUE	`groupedHyperframe::.illegal2theo`	FALSE
`cumvtrapz.fvlist`	TRUE	`groupedHyperframe::cumvtrapz`	FALSE
`keyval.fvlist`	TRUE	`groupedHyperframe::keyval`	FALSE
`Math.fvlist`	TRUE	`methods::Math`	FALSE
`print.fvlist`	TRUE	`base::print`	FALSE

21.1 Creation

21.1.1 A Good Example

Listing 21.1 and Listing 21.2 show that the point-patterns anemones (Section 10.1) and longleaf (Section 10.15) have similar default \(r_\text{max}\) (Section 36.10) for function spatstat.explore::markcorr() (Table 36.12),

Listing 21.1: Example: Default \(r_\text{max}\) of anemones for spatstat.explore::markcorr()

spatstat.data::anemones |>
  .rmax.ppp(fun = 'K')
# [1] 45

Listing 21.2: Example: Default \(r_\text{max}\) of longleaf for spatstat.explore::markcorr()

spatstat.data::longleaf |>
  .rmax.ppp(fun = 'K')
# [1] 50

Function as.fvlist() converts a listof fv.objects, that passes the validity check (Section 21.2, Table 21.2), to an object of S3 class 'fvlist'. Listing 21.3 creates a good function-value-table list fvL_good from the conditional mean \(E(r)\) (Section 37.9) of the point-patterns anemones (Section 10.1) and longleaf (Section 10.15). The S3 method print.fvlist() prints the vital information of fvL_good.

Listing 21.3: Example: a good function-value-table list fvL_good

fvL_good = spatstat.geom::solist(
  anemones = spatstat.data::anemones,
  longleaf = spatstat.data::longleaf
) |> 
  Emark_(r = seq.int(from = 0, to = 45, length.out = 513L)) |>
  getElement(name = 'm') |>
  as.fvlist()
fvL_good
# An 'fvlist' of 2 fv.objects E(r) 
# Name(s): anemones, longleaf 
# Available rmax: 45 
# Minimum Legal rmax: 45

21.1.2 A Malformed Example

Listing 21.4 and Listing 21.5 show the default \(r_\text{max}\) (Section 36.10) when applying the function spatstat.explore::markcorr() (Table 36.12) to the point-patterns bronzefilter (Section 10.5) and spruces (Section 10.19),

Listing 21.4: Example: Default \(r_\text{max}\) of bronzefilter for spatstat.explore::markcorr()

spatstat.data::bronzefilter |>
  .rmax.ppp(fun = 'K')
# [1] 1.75

Listing 21.5: Example: Default \(r_\text{max}\) of spruces for spatstat.explore::markcorr()

spatstat.data::spruces |>
  .rmax.ppp(fun = 'K')
# [1] 9.5

Listing 21.6 creates a malformed function-value-table list fvL_mal from the conditional mean \(E(r)\) (Section 37.9) of the point-patterns bronzefilter (Section 10.5) and spruces (Section 10.19). The S3 method print.fvlist() prints the vital information of fvL_mal.

Listing 21.6: Data: a malformed fvlist fvL_mal

fvL_mal = spatstat.geom::solist(
  bronzefilter = spatstat.data::bronzefilter,
  spruces = spatstat.data::spruces
) |> 
  Emark_(r = seq.int(from = 0, to = 100, length.out = 513L)) |>
  getElement(name = 'm') |>
  as.fvlist()
fvL_mal
# An 'fvlist' of 2 fv.objects E(r) 
# Name(s): bronzefilter, spruces 
# Available rmax: 100 
# Minimum Legal rmax: 22.46

Listing 21.7: Advanced: base::attributes() of S3 class 'fvlist'

Code

fvL_mal |> 
  attributes()
# $names
# [1] "bronzefilter" "spruces"     
# 
# $class
# [1] "fvlist"  "anylist" "listof"  "list"   
# 
# $r
#   [1]   0.0000000   0.1953125   0.3906250   0.5859375   0.7812500   0.9765625   1.1718750   1.3671875   1.5625000   1.7578125   1.9531250   2.1484375   2.3437500   2.5390625   2.7343750   2.9296875
#  [17]   3.1250000   3.3203125   3.5156250   3.7109375   3.9062500   4.1015625   4.2968750   4.4921875   4.6875000   4.8828125   5.0781250   5.2734375   5.4687500   5.6640625   5.8593750   6.0546875
#  [33]   6.2500000   6.4453125   6.6406250   6.8359375   7.0312500   7.2265625   7.4218750   7.6171875   7.8125000   8.0078125   8.2031250   8.3984375   8.5937500   8.7890625   8.9843750   9.1796875
#  [49]   9.3750000   9.5703125   9.7656250   9.9609375  10.1562500  10.3515625  10.5468750  10.7421875  10.9375000  11.1328125  11.3281250  11.5234375  11.7187500  11.9140625  12.1093750  12.3046875
#  [65]  12.5000000  12.6953125  12.8906250  13.0859375  13.2812500  13.4765625  13.6718750  13.8671875  14.0625000  14.2578125  14.4531250  14.6484375  14.8437500  15.0390625  15.2343750  15.4296875
#  [81]  15.6250000  15.8203125  16.0156250  16.2109375  16.4062500  16.6015625  16.7968750  16.9921875  17.1875000  17.3828125  17.5781250  17.7734375  17.9687500  18.1640625  18.3593750  18.5546875
#  [97]  18.7500000  18.9453125  19.1406250  19.3359375  19.5312500  19.7265625  19.9218750  20.1171875  20.3125000  20.5078125  20.7031250  20.8984375  21.0937500  21.2890625  21.4843750  21.6796875
# [113]  21.8750000  22.0703125  22.2656250  22.4609375  22.6562500  22.8515625  23.0468750  23.2421875  23.4375000  23.6328125  23.8281250  24.0234375  24.2187500  24.4140625  24.6093750  24.8046875
# [129]  25.0000000  25.1953125  25.3906250  25.5859375  25.7812500  25.9765625  26.1718750  26.3671875  26.5625000  26.7578125  26.9531250  27.1484375  27.3437500  27.5390625  27.7343750  27.9296875
# [145]  28.1250000  28.3203125  28.5156250  28.7109375  28.9062500  29.1015625  29.2968750  29.4921875  29.6875000  29.8828125  30.0781250  30.2734375  30.4687500  30.6640625  30.8593750  31.0546875
# [161]  31.2500000  31.4453125  31.6406250  31.8359375  32.0312500  32.2265625  32.4218750  32.6171875  32.8125000  33.0078125  33.2031250  33.3984375  33.5937500  33.7890625  33.9843750  34.1796875
# [177]  34.3750000  34.5703125  34.7656250  34.9609375  35.1562500  35.3515625  35.5468750  35.7421875  35.9375000  36.1328125  36.3281250  36.5234375  36.7187500  36.9140625  37.1093750  37.3046875
# [193]  37.5000000  37.6953125  37.8906250  38.0859375  38.2812500  38.4765625  38.6718750  38.8671875  39.0625000  39.2578125  39.4531250  39.6484375  39.8437500  40.0390625  40.2343750  40.4296875
# [209]  40.6250000  40.8203125  41.0156250  41.2109375  41.4062500  41.6015625  41.7968750  41.9921875  42.1875000  42.3828125  42.5781250  42.7734375  42.9687500  43.1640625  43.3593750  43.5546875
# [225]  43.7500000  43.9453125  44.1406250  44.3359375  44.5312500  44.7265625  44.9218750  45.1171875  45.3125000  45.5078125  45.7031250  45.8984375  46.0937500  46.2890625  46.4843750  46.6796875
# [241]  46.8750000  47.0703125  47.2656250  47.4609375  47.6562500  47.8515625  48.0468750  48.2421875  48.4375000  48.6328125  48.8281250  49.0234375  49.2187500  49.4140625  49.6093750  49.8046875
# [257]  50.0000000  50.1953125  50.3906250  50.5859375  50.7812500  50.9765625  51.1718750  51.3671875  51.5625000  51.7578125  51.9531250  52.1484375  52.3437500  52.5390625  52.7343750  52.9296875
# [273]  53.1250000  53.3203125  53.5156250  53.7109375  53.9062500  54.1015625  54.2968750  54.4921875  54.6875000  54.8828125  55.0781250  55.2734375  55.4687500  55.6640625  55.8593750  56.0546875
# [289]  56.2500000  56.4453125  56.6406250  56.8359375  57.0312500  57.2265625  57.4218750  57.6171875  57.8125000  58.0078125  58.2031250  58.3984375  58.5937500  58.7890625  58.9843750  59.1796875
# [305]  59.3750000  59.5703125  59.7656250  59.9609375  60.1562500  60.3515625  60.5468750  60.7421875  60.9375000  61.1328125  61.3281250  61.5234375  61.7187500  61.9140625  62.1093750  62.3046875
# [321]  62.5000000  62.6953125  62.8906250  63.0859375  63.2812500  63.4765625  63.6718750  63.8671875  64.0625000  64.2578125  64.4531250  64.6484375  64.8437500  65.0390625  65.2343750  65.4296875
# [337]  65.6250000  65.8203125  66.0156250  66.2109375  66.4062500  66.6015625  66.7968750  66.9921875  67.1875000  67.3828125  67.5781250  67.7734375  67.9687500  68.1640625  68.3593750  68.5546875
# [353]  68.7500000  68.9453125  69.1406250  69.3359375  69.5312500  69.7265625  69.9218750  70.1171875  70.3125000  70.5078125  70.7031250  70.8984375  71.0937500  71.2890625  71.4843750  71.6796875
# [369]  71.8750000  72.0703125  72.2656250  72.4609375  72.6562500  72.8515625  73.0468750  73.2421875  73.4375000  73.6328125  73.8281250  74.0234375  74.2187500  74.4140625  74.6093750  74.8046875
# [385]  75.0000000  75.1953125  75.3906250  75.5859375  75.7812500  75.9765625  76.1718750  76.3671875  76.5625000  76.7578125  76.9531250  77.1484375  77.3437500  77.5390625  77.7343750  77.9296875
# [401]  78.1250000  78.3203125  78.5156250  78.7109375  78.9062500  79.1015625  79.2968750  79.4921875  79.6875000  79.8828125  80.0781250  80.2734375  80.4687500  80.6640625  80.8593750  81.0546875
# [417]  81.2500000  81.4453125  81.6406250  81.8359375  82.0312500  82.2265625  82.4218750  82.6171875  82.8125000  83.0078125  83.2031250  83.3984375  83.5937500  83.7890625  83.9843750  84.1796875
# [433]  84.3750000  84.5703125  84.7656250  84.9609375  85.1562500  85.3515625  85.5468750  85.7421875  85.9375000  86.1328125  86.3281250  86.5234375  86.7187500  86.9140625  87.1093750  87.3046875
# [449]  87.5000000  87.6953125  87.8906250  88.0859375  88.2812500  88.4765625  88.6718750  88.8671875  89.0625000  89.2578125  89.4531250  89.6484375  89.8437500  90.0390625  90.2343750  90.4296875
# [465]  90.6250000  90.8203125  91.0156250  91.2109375  91.4062500  91.6015625  91.7968750  91.9921875  92.1875000  92.3828125  92.5781250  92.7734375  92.9687500  93.1640625  93.3593750  93.5546875
# [481]  93.7500000  93.9453125  94.1406250  94.3359375  94.5312500  94.7265625  94.9218750  95.1171875  95.3125000  95.5078125  95.7031250  95.8984375  96.0937500  96.2890625  96.4843750  96.6796875
# [497]  96.8750000  97.0703125  97.2656250  97.4609375  97.6562500  97.8515625  98.0468750  98.2421875  98.4375000  98.6328125  98.8281250  99.0234375  99.2187500  99.4140625  99.6093750  99.8046875
# [513] 100.0000000
# 
# $.x
# [1] "r"
# 
# $.y
# [1] "un"
# 
# $fname
# [1] "E"
# 
# $rmax
# [1] 22.46094

21.2 Validity

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

Table 21.2: Validity Requirements of S3 Class 'fvlist' versus function bind.fv()

Need to be `identical`?	`S3` Class `'fvlist'`	`bind.fv()`
Function Arguments, the \(r\)-vector values	Yes	Yes
Name of Function Argument, Table 20.2, Listing 20.6	Yes	No(?)
Name of Recommended-Function-Value, Table 20.2, Listing 20.6	Yes	No(?)
Function Name (& Add’l Info), `attr(,'fname')`	Yes	No(?)

Listing 21.8 validates that the function-value-table lists fvL_good (Listing 21.3) and fvL_mal (Listing 21.6) are both fvlists.

Listing 21.8: Example: function is.fvlist() (Listing 21.3, Listing 21.6)

stopifnot(is.fvlist(fvL_good))
stopifnot(is.fvlist(fvL_mal))

21.3 Inheritance

The S3 class 'fvlist' inherits from the class 'anylist' (Chapter 15) (Listing 21.9), which is inspired by the batch mechanism in package spatstat.explore (v3.6.0.5) (Table 36.21, Listing 21.10).

Listing 21.9: Review: Inheritance of S3 class 'fvlist'

fvL_good |>
  class()
# [1] "fvlist"  "anylist" "listof"  "list"

Listing 21.10: Review: Returned object class of the batch mechanism in package spatstat.explore

spatstat.data::finpines |>
  spatstat.explore::markcorr() |>
  class()
# [1] "anylist" "listof"  "list"

21.4 Function Value

The S3 method keyval.fvlist() (Section 20.2, Table 20.3)

applies the S3 method keyval.fv() (Section 20.2) to all function-value-tables of the input function-value-table list;
returns a numeric vectorlist (Chapter 41) containing the function values per function-value-table of the input function-value-table list.

Listing 21.11 finds the recommended function values in each function-value-table of fvL_mal (Listing 21.6).

Listing 21.11: Example: function keyval.fvlist() (Listing 21.6)

fvL_mal |>
  keyval() |>
  lapply(FUN = head)
# $bronzefilter
#         0 0.1953125  0.390625 0.5859375   0.78125 0.9765625 
# 0.1318823 0.1385519 0.1437837 0.1471030 0.1484506 0.1487112 
# 
# $spruces
#         0 0.1953125  0.390625 0.5859375   0.78125 0.9765625 
# 0.2455994 0.2456803 0.2457647 0.2458507 0.2459386 0.2460286

Listing 21.12 finds the theoretical function values in each function-value-table of fvL_mal (Listing 21.6).

Listing 21.12: Example: function keyval.fvlist(key = 'theo') (Listing 21.6)

fvL_mal |>
  keyval(key = 'theo') |>
  lapply(FUN = head)
# $bronzefilter
#         0 0.1953125  0.390625 0.5859375   0.78125 0.9765625 
# 0.1670236 0.1670236 0.1670236 0.1670236 0.1670236 0.1670236 
# 
# $spruces
#         0 0.1953125  0.390625 0.5859375   0.78125 0.9765625 
# 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731

21.5 Handling Illegal Recommended-Function-Value

The S3 generic functions .illegal2theo() and .disrecommend2theo() have been introduced in Section 20.5.1 (Table 20.5, Table 20.6). When a user-specified \(r\)-vector is provided to a batch process (Section 3.2) on all point-patterns in a ppplist, inevitably some of the fv-returns may contain exceptional/illegal recommended function values (Section 20.5).

The S3 method .illegal2theo.fvlist() (Listing 21.13) repeats the S3 method .illegal2theo.fv() (Section 20.5.1, Listing 20.18) on each function-value-table.

Listing 21.13: Advanced: function .illegal2theo.fvlist() (Listing 21.6)

fvL_mal |> 
  .illegal2theo()
# r≥22.7 replaced with theo
# r≥74.0 replaced with theo
# An 'fvlist' of 2 fv.objects E(r) 
# Name(s): bronzefilter, spruces 
# Available rmax: 100 
# Minimum Legal rmax: 100

The S3 method .disrecommend2theo.fvlist() (Listing 21.14) repeats the S3 method .disrecommend2theo.fv() (Section 20.5.1, Listing 20.19) on each function-value-table.

Listing 21.14: Advanced: function .disrecommend2theo.fvlist() (Listing 21.6)

fvL_mal |> 
  .disrecommend2theo()
# r≥1.8 replaced with theo
# r≥9.6 replaced with theo
# An 'fvlist' of 2 fv.objects E(r) 
# Name(s): bronzefilter, spruces 
# Available rmax: 100 
# Minimum Legal rmax: 100

21.6 Cumulative Average Vertical Height of Trapzoidal Integration

The S3 method cumvtrapz.fvlist() (Section 11.1, Table 11.1),

applies the S3 method cumvtrapz.fv() (Section 20.3) to all function-value-tables of the input function-value-table list;
removes the first NaN-value (Listing 11.7);
returns a numeric vectorlist (Chapter 41) containing the cumulative average vertical height of the trapezoidal integration of the recommended function values, per function-value-table of the input function-value-table list.

Listing 21.15

Listing 21.15: Example: function cumvtrapz.fvlist() (Listing 21.3)

fvL_good |>
  cumvtrapz()
# A 'vectorlist' of 2 vectors 
# Name(s): anemones, longleaf 
# Storage Mode: numeric 
# Individual Vector Length: 512 
# Suffix: cumvtrapz

The S3 method visualize_vtrapz.listof() (Section 11.2, Table 11.2)

Section 30.1

Listing 21.16 visualizes the good function-value-table list fvL_good (Listing 21.3) in Figure 21.1,

Listing 21.16: Figure: Visualize fvL_good (Listing 21.3)

fvL_good |>
  visualize_vtrapz(draw.rect = FALSE) *
  ggplot2::theme_minimal()

Figure 21.1: *`fvL_good`* (Listing 21.3)

21.7 `Math` Group-Generic

The S3 method Math.fvlist()

applies the S3 method spatstat.explore::Math.fv() (v3.6.0.5) to all function-value-tables of the input function-value-table list;
returns a function-value-table list.

The S3 method Math.fvlist() serves a similar purpose (Table 37.2) to the S3 method spatstat.geom::Math.imlist() (v3.6.1.16).

Listing 21.17 takes the square root of the function values in the good function-value-table list fvL_good (Listing 21.3) and visualize (Section 21.6) them in Figure 21.2.

Listing 21.17: Figure: Visualize square root of fvL_good (Listing 21.3)

fvL_good |>
  sqrt() |>
  visualize_vtrapz(draw.rect = FALSE) *
  ggplot2::theme_minimal()

Figure 21.2: Square root of *`fvL_good`* (Listing 21.3)