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"    "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 'vectorlist', for vector-list, which inherits from the classes 'anylist' (Chapter 14), 'listof' and 'list' and is assigned 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 25).

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

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

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

42.1 Creation & Print

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 9.16) into a character vector-list and prints its vital information.

Listing 42.1: Data: a vectorlist object Kovesi_v

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

Listing 42.2 creates a toy numeric vector-list toy_vecL and prints its vital information. Listing 42.3 prints each of the numeric-vector members in the vector-list toy_vecL.

Listing 42.2: Data: a toy numeric vectorlist

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

Listing 42.3: Review: function base::print.default() on vectorlist

toy_vecL |>
  print.default()
# [[1]]
# [1] -1.4805676  1.5771695 -0.9567445 -0.9200052 -1.9976421 -0.2722960
# 
# [[2]]
# [1] -0.3153487 -0.6282552 -0.1064639  0.4280148 -0.7777196 -1.2938823
# 
# [[3]]
# [1] -0.77956651  0.01195176 -0.15241624 -0.70346425  1.18887916  0.34051227
# 
# [[4]]
# [1]  0.5069682 -0.2933051  0.2236414  2.0072015  1.0119791 -0.3024592
# 
# [[5]]
# [1] -1.0252448 -0.2673848 -0.1991057  0.1311226  0.1457999  0.3620647
# 
# attr(,"class")
# [1] "vectorlist" "anylist"    "listof"     "list"      
# attr(,"mode")
# [1] "numeric"

42.2 Validity

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

are all atomic vectors;
have identical mode;
have identical length;
have identical attributes, e.g., names, etc.

The hypercolumn spatstat.data::Kovesi$values (Section 9.16) qualifies as a 'character' vector-list (Listing 42.4), but not as a 'numeric' vector-list (Listing 42.5).

Listing 42.4: Example: function is.vectorlist()

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

Listing 42.5: 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.6 transposes the vector-list in Listing 42.1.

Listing 42.6: Example: function t.vectorlist()

Kovesi_v_t = spatstat.data::Kovesi$values |>
  as.vectorlist(mode = 'character') |> 
  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.7) is slow.

Listing 42.7: Review: function with.hyperframe() (Listing 42.6)

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 25) as of package spatstat.geom v3.7.0.6. Listing 42.8 calls the S3 method t.vectorlist() explicitly as a workaround before package spatstat.geom (ever) supports the class 'vectorlist'.

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

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

Listing 42.9 and Listing 42.10 aggregate the toy vector-list toy_vecL (Listing 42.2) by a pre-specified factor, using the point-wise mean and median (Chapter 49), respectively.

Listing 42.9: Example: function aggregate.vectorlist() using point-wise mean (Listing 42.2)

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.10: Example: function aggregate.vectorlist() using point-wise median (Listing 42.2)

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