41 `vectorlist` from `anylist`

The examples in Chapter 41 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 'vectorlist' (Section 41.2), which inherits from the class 'anylist' (Chapter 15), 'listof' and 'list', with additional attributes,

attr(., 'mode'), a character scalar, the storage mode;
attr(., 'suffix') a character scalar, the suffix when used as a hypercolumn of a hyper data frame (Chapter 26).

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

Table 41.1: S3 methods groupedHyperframe::*.vectorlist (v0.3.2.20251225)

	visible	generic	isS4
`aggregate.vectorlist`	TRUE	`stats::aggregate`	FALSE
`print.vectorlist`	TRUE	`base::print`	FALSE
`t.vectorlist`	TRUE	`base::t`	FALSE

41.1 Creation

Function as.vectorlist() inspects whether the input qualifies as a vectorlist (Section 41.2), and if true, appends the derived class 'vectorlist' to the returned value.

The S3 method print.vectorlist() prints the vital information of a vectorlist.

Listing 41.1 converts the hypercolumn Kovesi$values (Section 10.14) into a vectorlist.

Listing 41.1: Data: a vectorlist object Kovesi_v

Kovesi_v = spatstat.data::Kovesi$values |>
  as.vectorlist(mode = 'character')
Kovesi_v
# A 'vectorlist' of 41 vectors 
# Storage Mode: character 
# Individual Vector Length: 256

41.2 Validity

Function is.vectorlist() inspects whether all elements of an 'anylist'

are all atomic vectors;
have all-equal vector-mode, as determined by function base::is.vector();
have all-equal lengths, i.e., length-per-element.

All criteria listed here, especially the last one, are tailored specifically for the summary statistics from Section 3.3.

The hypercolumn spatstat.data::Kovesi$values (Section 10.14) qualifies as a 'character' vectorlist (Listing 41.2), but not as a 'numeric' vectorlist (Listing 41.3).

Listing 41.2: Example: function is.vectorlist()

spatstat.data::Kovesi$values |>
  is.vectorlist(mode = 'character')
# [1] TRUE

Listing 41.3: Example: function is.vectorlist()

spatstat.data::Kovesi$values |>
  is.vectorlist(mode = 'numeric')
# [1] FALSE

41.3 Transpose

The S3 method t.vectorlist() transposes a vectorlist into another vectorlist, with the length and lengths of the input swapped. Table 41.2 explains the rational of using the S3 generic function base::t().

Table 41.2: Rational of “Transpose”

	`base:::t.default()` on `matrix`	`t.vectorlist()`
Swaps	`ncol` & `nrow` of a `matrix`	`length` & `lengths` of a `vectorlist`
Returns	A `matrix`	A `vectorlist`

Listing 41.4 transposes the vectorlist Kovesi_v (Listing 41.1).

Listing 41.4: Example: function t.vectorlist() (Listing 41.1)

Kovesi_v_t = Kovesi_v |> 
  t()
Kovesi_v_t
# A 'vectorlist' of 256 vectors 
# Storage Mode: character 
# Individual Vector Length: 41

The motivation of the derived class 'vectorlist' and the S3 method t.vectorlist() is that using the S3 method spatstat.geom::with.hyperframe() in a batch process (Listing 41.5) is slow.

Listing 41.5: Review: function spatstat.geom::with.hyperframe() (Listing 41.4)

Code

spatstat.data::Kovesi |> 
  spatstat.geom::with.hyperframe(expr = values[1L]) |>
  identical(y = Kovesi_v_t[[1L]]) |>
  stopifnot()
spatstat.data::Kovesi |> 
  spatstat.geom::with.hyperframe(expr = values[2L]) |>
  identical(y = Kovesi_v_t[[2L]]) |>
  stopifnot()
spatstat.data::Kovesi |> 
  spatstat.geom::with.hyperframe(expr = values[256L]) |>
  identical(y = Kovesi_v_t[[256L]]) |>
  stopifnot()

The derived class 'vectorlist' is not supported as a hypercolumn in a hyper data frame (Chapter 26) as of package spatstat.geom v3.6.1.16. Listing 41.6 calls the S3 method t.vectorlist() explicitly as a workaround before package spatstat.geom (ever) supports the class vectorlist.

Listing 41.6: Workaround: without derived class 'vectorlist' (Listing 41.4)

spatstat.data::Kovesi$values |>
  t.vectorlist() |>
  identical(y = Kovesi_v_t) |>
  stopifnot()

41.4 Aggregation

The S3 method aggregate.vectorlist() aggregates a numeric vectorlist by a factor specified in the parameter by, using the aggregation method provided in the parameter fun. Available aggregation methods are the point-wise minima base::pmin(), maxima base::pmax(), means pmean() (default, Chapter 47) and medians pmedian() (Chapter 47). The S3 method aggregate.vectorlist() returns a vectorlist.

Listing 41.7 creates a toy numeric vectorlist.

Listing 41.7: Data: a toy example of vectorlist

set.seed(12); toy_vecL = replicate(n = 5L, expr = rnorm(n = 6L), simplify = FALSE) |> 
  do.call(what = spatstat.geom::anylist, args = _) |>
  as.vectorlist(mode = 'numeric')
toy_vecL
# A 'vectorlist' of 5 vectors 
# Storage Mode: numeric 
# Individual Vector Length: 6

Listing 41.8 and Listing 41.9 aggregate the toy vectorlist toy_vecL (Listing 41.7) by a pre-specified factor, using point-wise mean and median (Chapter 47), respectively.

Listing 41.8: Example: function aggregate.vectorlist() using point-wise mean (Listing 41.7)

toy_vecL |>
  aggregate(by = factor(c('a', 'a', 'b', 'b', 'b')), fun = pmean)
# A 'vectorlist' of 2 vectors 
# Name(s): a, b 
# Storage Mode: numeric 
# Individual Vector Length: 6

Listing 41.9: Example: function aggregate.vectorlist() using point-wise median (Listing 41.7)

toy_vecL |>
  aggregate(by = factor(c('a', 'a', 'b', 'b', 'b')), fun = pmedian)
# A 'vectorlist' of 2 vectors 
# Name(s): a, b 
# Storage Mode: numeric 
# Individual Vector Length: 6