16 `fvlist` from `anylist`

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

library(groupedHyperframe)

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

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 15.4) of all fv.objects, which is obviously <= max(attr(,'r')).

Package groupedHyperframe (v0.3.2) implements the following S3 methods to the class 'fvlist' (Table 16.1),

Table 16.1: S3 methods groupedHyperframe::*.fvlist (v0.3.2)

	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
`print.fvlist`	TRUE	`base::print`	FALSE
`visualize_vtrapz.fvlist`	TRUE	`groupedHyperframe::visualize_vtrapz`	FALSE

Listing 16.1 creates a malformed function-value-table list sprucesE_ using the S3 method Emark_.ppplist() (Section 28.6) and the point-pattern spruces (Section 10.17).

Listing 16.1: 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
#

16.1 Validity

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

Table 16.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	Table 15.2, Listing 15.4	Required	Not Required(?)
Name of recommended-function-value	Table 15.2, Listing 15.4	Required	Not Required(?)
Function name (and additional information)	`attr(,'fname')`	Required	Not Required(?)

Listing 16.2 validates that the function-value-table list sprucesE_ (Listing 16.1) is an fvlist.

Listing 16.2: Example: function is.fvlist()

stopifnot(is.fvlist(sprucesE_$m.E))

16.2 Creation

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

Listing 16.3: Example: function as.fvlist() to create fvlist_mal

fvlist_mal = sprucesE_$m.E |>
  as.fvlist()

Listing 16.4: 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 print.fvlist() (Listing 16.5) prints the vital information of an 'fvlist'.

Listing 16.5: Example: function print.fvlist()

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

16.3 Function Value

The S3 generic function keyval() has been introduced in Section 15.1 (Table 15.3). The S3 method keyval.fvlist()

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

Listing 16.6 finds the recommended function values in each function-value-table of fvlist_mal (Listing 16.3).

Listing 16.6: Example: function keyval.fvlist()

fvlist_mal |>
  keyval()
# Component 1:
#         0        10        20        30        40        50        60        70        80        90       100 
# 0.2456091 0.2486755 0.2499532 0.2523455 0.2505328 0.2527705 0.2406730 0.2766159 0.4502869       Inf       Inf 
# 
# Component 2:
#         0        10        20        30        40        50        60        70        80        90       100 
# 0.2456091 0.2486755 0.2499532 0.2523455 0.2505328 0.2527705 0.2406730 0.2766159 0.4502869       Inf       Inf

Listing 16.7 finds the theoretical function values in each function-value-table of fvlist_mal (Listing 16.3).

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

fvlist_mal |>
  keyval(key = 'theo')
# Component 1:
#         0        10        20        30        40        50        60        70        80        90       100 
# 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 
# 
# Component 2:
#         0        10        20        30        40        50        60        70        80        90       100 
# 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731 0.2503731

16.4 Handling Illegal Recommended-Function-Value

The S3 generic functions .illegal2theo() and .disrecommend2theo() have been introduced in Section 15.4.1 (Table 15.4, Table 15.5). 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 15.4).

The S3 method .illegal2theo.fvlist() (Listing 16.8) repeats the S3 method .illegal2theo.fv() (Section 15.4.1, Listing 15.18) on each function-value-table.

Listing 16.8: Advanced: function .illegal2theo.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

The S3 method .disrecommend2theo.fvlist() (Listing 16.9) repeats the S3 method .disrecommend2theo.fv() (Section 15.4.1, Listing 15.19) on each function-value-table.

Listing 16.9: Advanced: function .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

16.5 Cumulative Average Vertical Height of Trapzoidal Integration

The S3 generic function cumvtrapz() has been introduced in Section 11.1 (Table 11.1). The S3 method cumvtrapz.fvlist() calculates the cumulative average vertical height of the trapezoidal integration of the recommended function values, after removing the first NaN-value (Section 11.1), per function-value-table.

Listing 16.10: Example: function cumvtrapz.fvlist()

fvlist_mal |>
  .disrecommend2theo() |>
  cumvtrapz()
# r≥10.0 replaced with theo
# r≥10.0 replaced with theo
# [[1]]
#        10        20        30        40        50        60        70        80        90       100 
# 0.2479911 0.2491821 0.2495791 0.2497776 0.2498967 0.2499761 0.2500328 0.2500754 0.2501085 0.2501349 
# 
# [[2]]
#        10        20        30        40        50        60        70        80        90       100 
# 0.2479911 0.2491821 0.2495791 0.2497776 0.2498967 0.2499761 0.2500328 0.2500754 0.2501085 0.2501349