42 `vectorlist` from `anylist`

The examples in Chapter 42 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.20260108) defines a derived S3 class 'vectorlist', for vector-list, which inherits from the classes '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 42.1 summarizes the S3 methods for the class 'vectorlist' in package groupedHyperframe (v0.3.2.20260108),

Table 42.1: S3 methods groupedHyperframe::*.vectorlist (v0.3.2.20260108)

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

42.1 Creation

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

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

Listing 42.1 converts the hypercolumn Kovesi$values (Section 10.14) into a vector-list.

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

42.2 Validity

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

are all atomic vectors;
have all-equal mode, as determined by the 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' vector-list (Listing 42.2), but not as a 'numeric' vector-list (Listing 42.3).

Listing 42.2: Example: function is.vectorlist()

spatstat.data::Kovesi$values |>
  is.vectorlist(mode = 'character') |>
  stopifnot()

Listing 42.3: Example: function is.vectorlist()

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

42.3 Transpose

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

Table 42.2: Rational of “Transpose”

	`base:::t.default()`	`t.vectorlist()`
Input & Output	`matrix`	`vectorlist`
Swaps	`ncol` & `nrow`	`length` & `lengths`

Listing 42.4 transposes the vector-list Kovesi_v (Listing 42.1).

Listing 42.4: Example: function t.vectorlist() (Listing 42.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 42.5) is slow.

Listing 42.5: Review: function with.hyperframe() (Listing 42.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.24. Listing 42.6 calls the S3 method t.vectorlist() explicitly as a workaround before package spatstat.geom (ever) supports the class 'vectorlist'.

Listing 42.6: Workaround: without derived class 'vectorlist' (Listing 42.4)

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

42.4 Aggregation

The S3 method aggregate.vectorlist()

aggregates a numeric vector-list 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 48) and medians pmedian() (Chapter 48);
returns a vector-list.

Listing 42.7 creates a toy numeric vector-list toy_vecL.

Listing 42.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 42.8 and Listing 42.9 aggregate the toy vector-list toy_vecL (Listing 42.7) by a pre-specified factor, using the point-wise mean and median (Chapter 48), respectively.

Listing 42.8: Example: function aggregate.vectorlist() using point-wise mean (Listing 42.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 42.9: Example: function aggregate.vectorlist() using point-wise median (Listing 42.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