Type: | Package |
Title: | Virtual Arrays |
Version: | 0.2.0 |
Collate: | zzz.R data.R generics.R utility.R classes.R VirtualArray-base.R VirtualArray-xattrib.R VirtualArray-subset.R VirtualArray-replace.R VirtualArray-combine.R XArray-base.R XArray-xattrib.R XArray-combine.R RasterArray-base.R RasterArray-xattrib.R RasterArray-groupgen.R RasterArray-replace.R RasterArray-combine.R RasterArray-rast.R SfcArray-base.R SfcArray-replace.R SfcArray-sf.R SfArray-base.R SfArray-replace.R conversions.R |
Maintainer: | Adam T. Kocsis <adam.t.kocsis@gmail.com> |
Description: | The base class 'VirtualArray' is defined, which acts as a wrapper around lists allowing users to fold arbitrary sequential data into n-dimensional, R-style virtual arrays. The derived 'XArray' class is defined to be used for homogeneous lists that contain a single class of objects. The 'RasterArray' and 'SfArray' classes enable the use of stacked spatial data instead of lists. |
License: | CC BY 4.0 |
Date: | 2023-05-15 |
BugReports: | https://github.com/adamkocsis/via |
Encoding: | UTF-8 |
LazyData: | false |
Depends: | R (≥ 4.0.0) |
Imports: | methods |
NeedsCompilation: | no |
RoxygenNote: | 7.2.3 |
Suggests: | tinytest, knitr, rmarkdown, terra, sp, sf |
Packaged: | 2023-05-16 13:20:28 UTC; root |
Author: | Adam T. Kocsis |
Repository: | CRAN |
Date/Publication: | 2023-05-16 13:50:02 UTC |
Array of 'SpatRaster
'-class objects
Description
Array class for easier navigation of multilayer rasters
Arguments
stack |
A |
index |
A |
dim |
A |
Details
The class implements structures to organize single-layer 'SpatRaster
'-class objects that have the same dimensions and coordinate reference system. Subsetting rules were defined using the proxy object in the @index
slot. See examples for implementations.
The class has two slots:
@stack
: A 'SpatRaster
'-class object with multiple layers, the actual data.
index
: A proxy object that represents the organization of the layer in the array.
Value
A 'RasterArray
'-class object.
Examples
# example data
ex <- rastex()
st <-ex@stack
ind <- 1:6
names(ind) <- letters[1:length(ind)]
ra<- RasterArray(stack=st, index=ind)
Array of 'sf
'-derived class data
Description
Array class for easier navigation of vector spatial datasets
Arguments
stack |
A |
index |
A |
dim |
A |
Details
The class implements structures to organize entire 'sfc
' and 'sf
' objects that share coordinate reference systems. The 'SfcArray' class is derived from 'XArray
' and represents arrays of geometry sets. The 'SfArray
' class is derived from 'SfArray
', that allows the wrapping of 'sf
' objects with attributes. Subsetting rules were defined using the proxy object in the @index
slot. See examples for implementations.
The classes have two slots:
@stack
: A list
object with multiple 'sf
' class layers, the actual data.
@index
: A proxy object that represents the organization of the layers.
Value
An 'SfcArray
' or 'SfArray
'-class object.
Examples
# example data
library(sf)
data(paleocoastlines)
st <-paleocoastlines@stack
ind <- 1:nlayers(st)
dim(ind) <- c(3,2)
dimnames(ind) <- list(age=c(0, 10, 20), c("margin", "coastlines"))
sa<- SfcArray(stack=st, index=ind)
Virtual array of general R objects
Description
Template for construction of virtual arrays ('VirtualArray
') and a derived class ('XArray
') to instantiate it with general objects.
Arguments
stack |
A |
index |
A |
dim |
A |
Details
The 'VirtualArray
' class implements structures to organize objects of the same class in multidimensional arrays. Subsetting rules were defined using the proxy object in the index
slot. The 'VirtualArray
' is the base class for 'XArray
' and 'RasterArray
' classes.
The 'XArray
' class derived from VirtualArray
allows the instantiation of basic virtual arrays with genearl R objects, which form a single list
in the @stack slot
. The 'SfArray
' class is derived from the 'XArray
' class.
The class has two slots:
@stack
: A list containing objects of the same class (i.e. layers).
@index
: A proxy object that represents the structure of the entities.
Value
An XArray
-class object.
Examples
# 2d XArray of vectors
data(exemplar)
st <-exemplar@stack
ind <- 1:nlayers(st)
dim(ind) <- c(3,4)
dimnames(ind) <- list(n = c(10, 20, 30), seed = 1:4)
xa<- XArray(stack=st, index=ind)
Replace layers in an object that is of a class derived from 'VirtualArray
'.
Description
Single bracket '['
refers to indices and names within the 'VirtualArray
'-class object. Use double brackets to replace layers based on their names (in the @stack
).
Object types of the same kind class can be used to replace values in 'XArray
'-class objects. 'SpatRaster
'-class objects can be used to replace values in 'RasterArray
'-class objects. Classes inheriting from 'sf
' can be used with 'SfArray
'-class objects.
Usage
## S4 replacement method for signature 'VirtualArray,ANY,ANY,logical'
x[i, j, ...] <- value
## S4 replacement method for signature 'RasterArray,ANY,ANY,SpatRaster'
x[i, j, ...] <- value
## S4 replacement method for signature 'SfcArray,ANY,ANY,sfc'
x[i, j, ...] <- value
## S4 replacement method for signature 'SfArray,ANY,ANY,sf'
x[i, j, ...] <- value
Arguments
x |
|
i |
subscript of the first dimension(rows) or vector-like subsetting. |
j |
subscript of the second dimension (columns). |
... |
subscript of additional dimensions. |
value |
A same class object as |
Value
The function has no return value.
Examples
ex <- rastex()
# replace third element with missing value
ex[3] <- NA
# duplicate first element and make it the second too
ex[2] <- ex[1]
ex
Indexing to extract subsets of a 'codeVirtualArray'-class object
Description
Single bracket '['
refers to indices and names within the 'VirtualArray
'-class object. Use double brackets to extract layers based on their names (in the @stack
).
Usage
## S4 method for signature 'VirtualArray,ANY,ANY'
x[i, j, ..., drop = TRUE]
Arguments
x |
An object from a |
i |
subscript of the first dimension(rows) or vector-like subsetting. |
j |
subscript of the second dimension (columns). |
... |
subscript of additional dimensions. |
drop |
|
Value
An object from either the same class as x
or the class of its elements.
Examples
ex <- rastex()
# numeric subsetting
firstThree <- ex[1:3]
# character subsetting
second <- ex["d"]
# logical subsetting
subscript <- rep(FALSE, length(ex))
subscript[2] <- TRUE
second2 <- ex[subscript]
data(paleocoastlines)
present<- paleocoastlines["0", ]
allMargin <- paleocoastlines[, "margin"]
Replace elements of 'VirtualArray
'-class objects.
Description
Double bracket '[['
refers to layers' name in the names of the @stack
member of the 'VirtualArray
'. Use single brackets to replace elements based on their position in the 'VirtualArray
'-class object.
Usage
## S4 replacement method for signature 'VirtualArray,ANY'
x[[i]] <- value
Arguments
x |
Object from a class derived from |
i |
subscript of layers to replace. |
value |
|
Value
The function has no return value.
Indexing to extract the elements of a 'VirtualArray
'-derived class object.
Description
Double bracket '[['
refers to elements'/layers' name in the @stack
of the 'VirtualArray
'-derived object. Use single brackets to extract elements based on their position in the 'VirtualArray
'.
Usage
## S4 method for signature 'VirtualArray,ANY,ANY'
x[[i, drop = TRUE]]
Arguments
x |
|
i |
subscript of the first dimension(rows) or vector-like subsetting. |
drop |
|
Value
A VirtualArray
-derived class object, or an object of the class that makes up the VirtualArray
Examples
data(exemplar)
# finds a layer
exemplar[["sample1"]]
# returns a stack
exemplar[[c("sample1", "sample2")]]
# replaces a layervalues, but not the attributes of the layer
exemplar2 <- exemplar
exemplar2[["sample1"]] <- exemplar2[["sample2"]]
# compare every value in the they are all the same
exemplar2[["sample1"]]$x == exemplar2[["sample2"]]$x
Aggregate raster cells in a 'RasterArray
'-class object
Description
The method is inherited from the 'SpatRaster
' class.
Usage
## S4 method for signature 'RasterArray'
aggregate(x, ...)
Arguments
x |
a |
... |
arguments passed to the |
Value
An aggregated RasterArray
-class object.
Examples
library(terra)
ex <- rastex()
agg <- aggregate(ex, 30)
Coerce into an SfcArray
or SfArray
object
Description
Coerce into an SfcArray
or SfArray
object
Coerce into an SfArray or SfcArray object
Usage
as.XArray(from)
## S4 method for signature 'SfcArray'
as.XArray(from)
## S4 method for signature 'SfArray'
as.XArray(from)
as.SfcArray(from)
## S4 method for signature 'XArray'
as.SfcArray(from)
## S4 method for signature 'SfArray'
as.SfcArray(from)
as.SfArray(from)
## S4 method for signature 'XArray'
as.SfArray(from)
## S4 method for signature 'SfcArray'
as.SfArray(from)
Arguments
from |
Value
Either a SfcArray
, SfArray
or XArray
-class object
Combine a one-dimensional 'VirtualArray
'-class object with other objects
Description
NOTE: Sequences that start with an NA
do not yet work.
Usage
## S4 method for signature 'VirtualArray'
c(x, ...)
Arguments
x |
|
... |
additional objects to combine. |
Value
A VirtualArray
-class object.
Column names of two-dimensional 'VirtualArray
'-derived class object.
Description
Get or set the column names of two-dimensional 'VirtualArray
'-derived class objects
Usage
## S4 method for signature 'VirtualArray'
colnames(x)
## S4 replacement method for signature 'VirtualArray'
colnames(x) <- value
Arguments
x |
|
value |
|
Value
A character
vector of column names or NULL
.
Examples
data(paleocoastlines)
colnames(paleocoastlines)
colnames(paleocoastlines) <- c("a", "b")
Cropping a 'RasterArray
'-class object
Description
The method is inherited from the 'SpatRaster
' class.
Usage
## S4 method for signature 'RasterArray'
crop(x, y, ...)
Arguments
x |
a |
y |
an |
... |
arguments passed to the |
Value
A cropped RasterArray
-class object.
Examples
ex <- rastex()
# crop to a specific area
if(requireNamespace("terra", quietly=TRUE)){
ext <- terra::ext(c(
xmin = 106.58,
xmax = 157.82,
ymin = -45.23,
ymax = 1.14
))
# cropping all
au<- crop(ex, ext)
}
Dimensions of 'VirtualArray
'-derived class objects
Description
The function returns the dimensions of the array in which elements are organized.
Usage
## S4 method for signature 'VirtualArray'
dim(x)
Arguments
x |
A |
Value
A numeric
vector.
Examples
data(exemplar)
dim(exemplar)
Dimensions of layers in a 'VirtualArray
'-class object
Description
The funcion will return the dimensions 'SpatRaster
'-class layers.
Usage
dimlayer(x, ...)
## S4 method for signature 'RasterArray'
dimlayer(x)
Arguments
x |
A |
... |
additional arguments passed to class-specific methods. |
Value
A numeric
vector with the number of rows and columns in the VirtualArray
s.
Names of a multidimensional 'VirtualArray
'-derived class object.
Description
Get or set the dimnames of multidimensional VirtualArray
-derived class object.
Usage
## S4 method for signature 'VirtualArray'
dimnames(x)
## S4 replacement method for signature 'VirtualArray'
dimnames(x) <- value
Arguments
x |
|
value |
|
Value
A list
of character
vectors or NULL
.
Examples
ex <- rastex()
dimnames(ex)
data(paleocoastlines)
dimnames(paleocoastlines)
dimnames(paleocoastlines)[[2]] <- c("first", "second")
names(dimnames(paleocoastlines)) <- c("age", "type")
Disaggregate raster cells in a 'RasterArray
'-class object
Description
The method is inherited from the 'SpatRaster
' class.
Usage
## S4 method for signature 'RasterArray'
disagg(x, ...)
Arguments
x |
a |
... |
arguments passed to the |
Value
A disaggregated RasterArray
class object.
Examples
ex <- rastex()
disagg <- disagg(ex, 3)
Example 'XArray
'-class object
Description
A 'XArray
'-class objects of data.frame
s, which were made from a single data.frame
with random sampling. The original object had two columns, the first (x
) an integer seqence 1:100
, the second y
a variable produced with 0.5 * x -30 + N(0,10)
.
Usage
data(exemplar)
Format
: XArray
with 3 sample sizes (rows), and 4 different seeds (column).
Extent of a 'RasterArray
'-class object
Description
The method is inherited from the 'SpatRaster
' class.
Usage
## S4 method for signature 'RasterArray'
ext(x, ...)
Arguments
x |
a |
... |
arguments passed to the |
Value
An aggregated RasterArray
-class object.
Examples
ex <- rastex()
extent <- ext(ex)
Positions of missing values in a 'RasterArray
'-class object
Description
The function behaves similar to the regular is.na()
function applied to the proxy object of a 'RasterArray
'.
Usage
## S3 method for class 'RasterArray'
is.na(x)
Arguments
x |
A |
Value
A logical
vector
, matrix
or array
matching the structure of the RasterArray
.
Examples
ex <- rastex()
ex[2] <- NA
is.na(ex)
Names of layers in the stack
of a 'VirtualArray
'-class object
Description
Names of layers in the stack
of a 'VirtualArray
'-class object
Usage
layers(x, ...)
## S4 method for signature 'VirtualArray'
layers(x)
Arguments
x |
A |
... |
additional arguments passed to class-specific methods. |
Value
A character
vector of names.
Examples
# names of layers in the stack
data(exemplar)
layers(exemplar)
Names of one-dimensional 'VirtualArray
'-derived class objects.
Description
Get or set the names of one-dimensional 'VirtualArray
'-derived class objects
Usage
## S4 method for signature 'VirtualArray'
names(x)
## S4 replacement method for signature 'VirtualArray'
names(x) <- value
Arguments
x |
|
value |
|
Value
A character
vector of names or NULL
.
Examples
ex <- rastex()
names(ex)
names(ex)[4] <- "weirdo"
# NULL
Number of cells in a 'RasterArray
'-class object
Description
The method is inherited from the 'SpatRaster
' class.
Usage
## S4 method for signature 'RasterArray'
ncell(x)
Arguments
x |
a |
Value
A numeric
value.
Examples
ex <- rastex()
ncell(ex)
Number of columns and rows of a 'VirtualArray
'-derived class object.
Description
Unlike the ncol
and nrow
functions of the 'terra
' package, this function returns the number of columns and rows of the 'VirtualArray
'-derived container, rather than the dimensions of the contained 'SpatRaster
'-class object.
Usage
## S4 method for signature 'VirtualArray'
ncol(x)
## S4 method for signature 'VirtualArray'
nrow(x)
Arguments
x |
A |
Value
A numeric
value of the number of columns and rows.
Examples
data(paleocoastlines)
ncol(paleocoastlines)
nrow(paleocoastlines)
Redefine bounds of a named matrix
Description
The function restructures a matrix
and extends its current limits to a range defined by a names attribute
Usage
newbounds(x, cols = NULL, rows = NULL)
Arguments
x |
The matrix to be restructured. |
cols |
Column names guiding the restructuring. |
rows |
Row names guiding the restructuring. |
Details
This is essentially a subsetting function that allows you to subset even when the rownames or colnames vector extends beyond the bounds of a matrix and traditional subsetting methods result in the notorious 'out of bounds' error.
Value
A matrix with extended bounds.
Examples
a<-matrix(1:9, ncol=3)
rownames(a) <- c("a", "c", "d")
newbounds(a, rows=letters[1:5])
Number of elements or layers in a 'VirtualArray
'-derived class object
Description
Function to return the length of the array in which elements are organized.
Usage
nlayers(x)
## S4 method for signature 'list'
nlayers(x)
## S4 method for signature 'SpatRaster'
nlayers(x)
## S4 method for signature 'VirtualArray'
length(x)
## S4 method for signature 'XArray'
nlayers(x)
## S4 method for signature 'RasterArray'
nlayers(x)
Arguments
x |
a |
Details
The length()
function returns the number elements that should be present based on the array structure itself, and not the total number of values stored in the object. As the object can contain missing values, the number of actual layers can be queried with nlayers
.
Value
A numeric
value.
Examples
ex <- rastex()
# omit third element
ex[3] <- NA
# number of elements in the RasterArray
length(ex)
# remaining number values in the stack
length(ex@stack)
# the number of remaining layers in the RasterArray
nlayers(ex)
Names as numerics
Description
The set of functions return names of objects directly cast to numeric values.
Usage
nums(x)
colnums(x)
rownums(x)
Arguments
x |
Object with names, colnames or rownames attributes. |
Value
Numeric vector.
Examples
# base R object
a <- 1:10
names(a) <- seq(10, 100, 10)
nums(a)
# XArray
data(exemplar)
colnums(exemplar)
rownums(exemplar)
The total number of values in a 'RasterArray
'-class object
Description
The total number of values in a 'RasterArray
'-class object
Usage
nvalues(x, ...)
## S4 method for signature 'RasterArray'
nvalues(x)
Arguments
x |
A |
... |
additional arguments passed to class-specific methods. |
Value
A numeric
value.
Examples
ex <- rastex()
nvalues(ex)
PaleoMAP PaleoCoastlines (excerpt)
Description
A dataset containing the coastline reconstructions based on the PaleoMAP PaleoDEMS https://www.earthbyte.org/paleodem-resource-scotese-and-wright-2018/ and the Paleobiology Database https://paleobiodb.org for 0, 10 and 20Ma.
Usage
data(paleocoastlines)
Format
A SfcArray
with 3 continental margin and 3 paleocoastline layers (3 rows and 2 columns).
Details
This is version v7. The article describing the entire set is under review. Once that is published, the entire dataset will be available.
Source
Kocsis, A. T., & Scotese, C. R. (2020). PaleoMAP PaleoCoastlines data [Data set]. Zenodo. https://doi.org/10.5281/zenodo.3903164
Project a 'RasterArray
'-class object
Description
The method implemets the project
function for 'RasterArray
'-class objects.
The method is inherited from the 'SpatRaster
' class. See project
for details.
Usage
project
## S4 method for signature 'RasterArray'
project(x, y, ...)
Arguments
x |
A |
y |
A |
... |
additional arguments as for |
Format
An object of class standardGeneric
of length 1.
Value
A projected RasterArray
-class object.
Examples
# project first three to mollweide
ex <- rastex()
mollEx <- project(ex[1:3], y="ESRI:54009")
The proxy of an from a class derived from 'VirtualArray
'
Description
This function returns an object that symbolizes the structure of layers in the 'XArray
', 'RasterArray
' or 'SfArray
'.
Usage
proxy(x, ...)
## S4 method for signature 'VirtualArray'
proxy(x)
Arguments
x |
|
... |
additional arguments passed to class-specific methods. |
Details
The proxy
method wraps the names of layers in the @stack
using the @index
slot of the 'VirtualArray
'.
Value
A vector
, matrix
or array
of characters representing the VirtualArray
structure.
Examples
data(exemplar)
proxy(exemplar)
data(paleocoastlines)
proxy(paleocoastlines)
Procedural example structure to demonstrate the capabilities of the 'RasterArray
' class
Description
Binary versions of SpatRaster
-class objects are problematic, this function is used to instantiate a RasterArray
example.
Usage
rastex()
Value
A two-dimensional RasterArray
-class object, with three rows and four columns.
Examples
# create example
example <- rastex()
# subset - single bracket
example['b']
# subset - single bracket
example[c(4, 6)]
# subset - double bracket
example[["layer_2"]]
Resampling a 'RasterArray
'-class object
Description
The method is inherited from the 'SpatRaster
' class.
Usage
## S4 method for signature 'RasterArray,ANY'
resample(x, y, ...)
Arguments
x |
a |
y |
The y argument of the |
... |
arguments passed to the |
Value
A resampled RasterArray
-class object.
Examples
ex <- rastex()
if(requireNamespace("terra", quietly=TRUE)){
template <- terra::rast(res=5)
resampled <- resample(ex, template)
}
Rotate a 'RasterArray
'-class object
Description
The method is inherited from the 'SpatRaster
' class.
Usage
## S4 method for signature 'RasterArray'
rotate(x, ...)
Arguments
x |
( |
... |
Additional arguments passed to the |
Value
A RasterArray
-class object.
Row names of two-dimensional 'VirtualArray
'-derived class objects.
Description
Get or set the row names of two-dimensional 'VirtualArray
'-derived class object
Usage
## S4 method for signature 'VirtualArray'
rownames(x)
## S4 replacement method for signature 'VirtualArray'
rownames(x) <- value
Arguments
x |
|
value |
|
Value
A character
vector of row names or NULL
.
Examples
data(paleocoastlines)
rownames(paleocoastlines)
rownames(paleocoastlines) <- paste(rownames(paleocoastlines), "Ma")
Bounding box of an 'SfArray
'-class object
Description
The method is inherited from the 'sf
' class.
Usage
## S3 method for class 'SfcArray'
st_bbox(obj, ...)
Arguments
obj |
a |
... |
arguments passed to the |
Value
An RasterArray
class object.
Examples
data(paleocoastlines)
bb<- st_bbox(paleocoastlines)
Coordinate reference system of an 'SfArray
'-class object
Description
The method is inherited from the 'sf
' class.
Usage
## S3 method for class 'SfcArray'
st_crs(x, ...)
Arguments
x |
a |
... |
arguments passed to the |
Value
An aggregated RasterArray
class object.
Examples
data(paleocoastlines)
crs <- st_crs(paleocoastlines)
Projection change of an 'SfArray
'-class object
Description
The method is inherited from the 'sf
' class.
Usage
## S3 method for class 'SfcArray'
st_transform(x, ...)
Arguments
x |
a |
... |
arguments passed to the |
Value
An RasterArray
-class object.
Examples
data(paleocoastlines)
moll<- st_transform(paleocoastlines, "ESRI:54009")
plot(moll["20", "margin"], col="cyan")
plot(moll["20", "coast"], add=TRUE, col="brown")
Subset a 'VirtualArray
'-class object
Description
Extract subsets of an object from a class derived from 'VirtualArray
' similarly to a regular array.
Usage
## S4 method for signature 'VirtualArray'
subset(x, i, j, ..., oneDim = FALSE, drop = TRUE)
Arguments
x |
|
i |
subscript of the first dimension(rows) or vector-like subsetting. |
j |
subscript of the second dimension (columns). |
... |
subscript of additional dimensions. |
oneDim |
|
drop |
|
Value
Either the same class as x
, or the class that forms the element of the VirtualArray
.
Examples
ex <- rastex()
# first 4
subset(ex, i=1:4)
# missing at the end
subset(ex, i=1:12)
# character subscript
subset(ex, i=c("a", "b"))
# logical subscript
subs <- rep(TRUE, length(ex))
subs[1] <- FALSE # remove first
subset(ex, i= subs)
# no drop
subset(ex, i=1, drop=FALSE)
Transpose a 'VirtualArray
'-class object
Description
Transpose a 'VirtualArray
'-class object
Usage
## S4 method for signature 'VirtualArray'
t(x)
Arguments
x |
A |
Value
A VirtualArray
-class object.
Examples
data(exemplar)
t(exemplar)
data(paleocoastlines)
t(paleocoastlines)
Virtual Arrays
Description
The base class 'VirtualArray
' is defined, which acts as a wrapper around lists allowing users to fold arbitrary sequential data into n-dimensional, R-style virtual arrays. The derived 'XArray
' class is defined to be used for homogeneous lists that contain a single class of objects. The 'RasterArray
' and 'SfArray
' classes enable the use of stacked spatial data instead of lists.
#'
This is still the pre-alpha version. As is R, this is free software and comes with ABSOLUTELY NO WARRANTY. Nevertheless, notes about found bugs and suggestions are more than welcome.
Author(s)
Adam T. Kocsis (adam.t.kocsis@gmail.com)
Resolution of a 'RasterArray
'-class object
Description
The methods are inherited from the 'SpatRaster
' class, see res
. Replacement is not allowed.
Usage
## S4 method for signature 'RasterArray'
xres(x)
## S4 method for signature 'RasterArray'
yres(x)
## S4 method for signature 'RasterArray'
res(x)
Arguments
x |
a |
Value
A numeric
vector.
Examples
ex <- rastex()
res(ex)
yres(ex)
xres(ex)