20 `fvlist` from `anylist`

The examples in Chapter 20 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"    "splines"          
# [64] "stats"             "survival"          "systemfonts"       "tensor"            "textshaping"       "tibble"            "tidyselect"        "tools"             "utils"            
# [73] "vctrs"             "viridisLite"       "xfun"              "yaml"

Package groupedHyperframe (v0.3.4) defines a derived S3 class 'fvlist' for a list of function-value-tables (fv.object, Chapter 19) that shares several common features (Section 20.2). The S3 class 'fvlist' inherits from the class 'anylist' (Chapter 14), 'listof' and 'list' and is assigned with additional attributes (Listing 20.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 19.5) of all fv.objects, which is obviously <= max(attr(,'r')).

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

Table 20.1: S3 methods groupedHyperframe::*.fvlist (v0.3.4)

	visible	generic	isS4
`.disrecommend2theo.fvlist`	TRUE	`groupedHyperframe::.disrecommend2theo`	FALSE
`.illegal2theo.fvlist`	TRUE	`groupedHyperframe::.illegal2theo`	FALSE
`as.list.fvlist`	TRUE	`base::as.list`	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
`Summary.fvlist`	TRUE	`methods::Summary`	FALSE

20.1 Creation

20.1.1 A Good Example

Listing 20.1 and Listing 20.2 show that the point-patterns anemones (Section 9.1) and longleaf (Section 9.17) have similar default \(r_\text{max}\) (Section 35.10) for function spatstat.explore::markcorr() (Table 35.14),

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

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

Listing 20.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 20.2, Table 20.2), to an object of S3 class 'fvlist'. Listing 20.3 creates a good function-value-table list fvL_good from the conditional mean \(E(r)\) (Section 36.9) of the point-patterns anemones (Section 9.1) and longleaf (Section 9.17). The S3 method print.fvlist() prints the vital information of fvL_good.

Listing 20.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

20.1.2 A Malformed Example

Listing 20.4 and Listing 20.5 show the default \(r_\text{max}\) (Section 35.10) when applying the function spatstat.explore::markcorr() (Table 35.14) to the point-patterns bronzefilter (Section 9.5) and spruces (Section 9.21),

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

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

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

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

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

Listing 20.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 20.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

20.2 Validity

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

Table 20.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 19.2, Listing 19.6	Yes	No(?)
Name of Recommended-Function-Value, Table 19.2, Listing 19.6	Yes	No(?)
Function Name (& Add’l Info), `attr(,'fname')`	Yes	No(?)

Listing 20.8 validates that the function-value-table lists fvL_good (Listing 20.3) and fvL_mal (Listing 20.6) are both fvlists.

Listing 20.8: Example: function is.fvlist() (Listing 20.3, Listing 20.6)

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

20.3 Inheritance

The S3 class 'fvlist' inherits from the class 'anylist' (Chapter 14) (Listing 20.9), which is inspired by the batch mechanism in package spatstat.explore (v3.7.0.4) (Table 35.23, Listing 20.10).

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

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

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

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

20.4 Function Value

The S3 method keyval.fvlist() (Section 19.2, Table 19.3)

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

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

Listing 20.11: Example: function keyval.fvlist() (Listing 20.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 20.12 finds the theoretical function values in each function-value-table of fvL_mal (Listing 20.6).

Listing 20.12: Example: function keyval.fvlist(key = 'theo') (Listing 20.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

20.5 Handling Illegal Recommended-Function-Value

When a user-specified \(r\)-vector is provided to a batch process (Section 2.2) on all point-patterns in a ppplist (Section 35.14), inevitably some of the fv-returns may contain exceptional/illegal recommended function values (Section 19.5).

The S3 method .illegal2theo.fvlist() (Section 19.5.1, Table 19.5)

applies the S3 method .illegal2theo.fv() (Section 19.5.1) on each function-value-table in the input function-value-table list;
returns a function-value-table list.

Listing 20.13 replaces the recommended function values, of each function-value-table in the malformed function-value-table list fvL_mal (Listing 20.6), after their first illegal \(r\) (Section 19.5) with their theoretical values.

Listing 20.13: Advanced: function .illegal2theo.fvlist() (Listing 20.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() (Section 19.5.1, Table 19.6)

applies the S3 method .disrecommend2theo.fv() (Section 19.5.1) on each function-value-table in the input function-value-table list;
returns a function-value-table list.

Listing 20.14 replaces the recommended function values outside the recommended range of each function-value-table in the malformed function-value-table list fvL_mal (Listing 20.6) with their theoretical values.

Listing 20.14: Advanced: function .disrecommend2theo.fvlist() (Listing 20.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

20.6 Cumulative Average Vertical Height of Trapzoidal Integration

The S3 method cumvtrapz.fvlist() (Section 10.2, Table 10.1),

applies the S3 method cumvtrapz.fv() (Section 19.3) to all function-value-tables of the input function-value-table list, with the first NaN-values (Listing 10.7) removed;
returns a numeric vector-list (vectorlist, Chapter 42).

Listing 20.15 finds the cumulative average vertical height of the trapezoidal integration of the recommended function values, per function-value-table of the good function-value-table list fvL_good (Listing 20.3). Listing 20.16 visualizes this concept in Figure 20.1.

Listing 20.15: Example: function cumvtrapz.fvlist() (Listing 20.3)

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

Listing 20.16: Figure: function visualize_vtrapz.listof() (Listing 20.3)

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

Figure 20.1: *`fvL_good`* (Listing 20.3)

20.7 Group-Generic

20.7.1 `Math`

The S3 method Math.fvlist() serves a similar purpose (Table 36.2) to the S3 method spatstat.geom::Math.imlist() (v3.7.0.6). This function

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

Listing 20.17 takes the square root of the function values in the good function-value-table list fvL_good (Listing 20.3) and visualize (Section 20.6) them in Figure 20.2.

Listing 20.17: Figure: Visualize square root of fvL_good (Listing 20.3)

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

Figure 20.2: Square root of *`fvL_good`* (Listing 20.3)

20.7.2 `Summary`

The S3 method Summary.fvlist() serves a similar purpose (Table 36.3) to the S3 method spatstat.geom::Summary.imlist() (v3.7.0.6). This function

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

Listing 20.18 and Listing 20.19 find the minimum and the range of function values in the good function-value-table list fvL_good (Listing 20.3).

Listing 20.18: Example: minimum function values of fvL_good (Listing 20.3)

fvL_good |>
  min()
#  anemones  longleaf 
#  3.336539 11.148859

Listing 20.19: Example: range of function values of fvL_good (Listing 20.3)

fvL_good |>
  range()
# $anemones
# [1] 3.336539 4.339186
# 
# $longleaf
# [1] 11.14886 26.84366

Listing 20.20 finds the range of function values in the malformed function-value-table list fvL_mal (Listing 20.6), after replacing the recommended function values outside the recommended range with the theoretical values (Section 20.5).

Listing 20.20: Example: range of function values of fvL_mal (Listing 20.6)

fvL_mal |>
  .disrecommend2theo() |>
  range() |>
  suppressMessages()
# $bronzefilter
# [1] 0.1318823 0.1670236
# 
# $spruces
# [1] 0.2455994 0.2503731