NaArray objects

EXPERIMENTAL!!!

Like SVT_SparseArray objects but the background value is NA instead of zero.

Usage

## Constructor function:
NaArray(x, dim=NULL, dimnames=NULL, type=NA)

Arguments

x

If dim is NULL (the default) then x must be an ordinary matrix or array, or a dgCMatrix/lgCMatrix object, or any matrix-like or array-like object that supports coercion to NaArray.

If dim is provided then x can either be missing, a vector (atomic or list), or an array-like object. If missing, then an all-NA NaArray object will be constructed. Otherwise x will be used to fill the returned object (length(x) must be <= prod(dim)). Note that if x is an array-like object then its dimensions are ignored i.e. it's treated as a vector.

dim

NULL or the dimensions (supplied as an integer vector) of the NaArray or NaMatrix object to construct. If NULL (the default) then the returned object will have the dimensions of matrix-like or array-like object x.

dimnames

The dimnames of the object to construct. Must be NULL or a list of length the number of dimensions. Each list element must be either NULL or a character vector along the corresponding dimension. If both dim and dimnames are NULL (the default) then the returned object will have the dimnames of matrix-like or array-like object x.

type

A single string specifying the requested type of the object.

By default the NaArray object returned by the constructor function will have the same type() as x. However the user can use the type argument to request a different type. Note that doing:

    naa <- NaArray(x, type=type)

is equivalent to doing:

    naa <- NaArray(x)
    type(naa) <- type

but the former is more convenient and will generally be more efficient.

The supported types for NaArray objects are "integer", "logical", "double", "complex", and "character".

Details

NaArray is a concrete subclass of the Array virtual class (the latter is defined in the S4Arrays package). This makes NaArray objects Array derivatives.

Like with SVT_SparseArray objects, the non-NA data in an NaArray object is stored in a Sparse Vector Tree. See ?SVT_SparseArray for more information.

Value

An NaArray or NaMatrix object.

See also

• The SVT_SparseArray class.

• is_nonna for is_nonna() and nna*() functions nnacount(), nnawhich(), etc...

• NaArray_aperm for permuting the dimensions of an NaArray object (e.g. transposition).

• NaArray_subsetting for subsetting an NaArray object.

• NaArray_abind for combining 2D or multidimensional NaArray objects.

• NaArray_summarization for NaArray summarization methods.

• NaArray_Arith, NaArray_Compare, and NaArray_Logic, for operations from the Arith, Compare, and Arith groups on NaArray objects.

• NaArray_Math for operations from the Math and Math2 groups on NaArray objects.

• NaArray_misc for miscellaneous operations on an NaArray object.

• NaArray_matrixStats for col/row summarization methods for NaArray objects.

• Ordinary array objects in base R.

Examples

## ---------------------------------------------------------------------
## Display details of class definition & known subclasses
## ---------------------------------------------------------------------

showClass("NaArray")
#> Class "NaArray" [package "SparseArray"]
#> 
#> Slots:
#>                                                                        
#> Name:           dim     dimnames         type        NaSVT .svt_version
#> Class:      integer         list    character NULL_OR_list      integer
#> 
#> Extends: "Array"
#> 
#> Known Subclasses: 
#> Class "NaMatrix", directly, with explicit coerce

## ---------------------------------------------------------------------
## The NaArray() constructor
## ---------------------------------------------------------------------

naa1 <- NaArray(dim=5:3)  # all-NA object
naa1
#> <5 x 4 x 3 NaArray> of type "logical" [nnacount=0 (0%)]:
#> ,,1
#>      [,1] [,2] [,3] [,4]
#> [1,]   NA   NA   NA   NA
#> [2,]   NA   NA   NA   NA
#> [3,]   NA   NA   NA   NA
#> [4,]   NA   NA   NA   NA
#> [5,]   NA   NA   NA   NA
#> 
#> ,,2
#>      [,1] [,2] [,3] [,4]
#> [1,]   NA   NA   NA   NA
#> [2,]   NA   NA   NA   NA
#> [3,]   NA   NA   NA   NA
#> [4,]   NA   NA   NA   NA
#> [5,]   NA   NA   NA   NA
#> 
#> ,,3
#>      [,1] [,2] [,3] [,4]
#> [1,]   NA   NA   NA   NA
#> [2,]   NA   NA   NA   NA
#> [3,]   NA   NA   NA   NA
#> [4,]   NA   NA   NA   NA
#> [5,]   NA   NA   NA   NA
#> 

naa2 <- NaArray(dim=c(35000, 2e6), type="integer")  # all-NA object
naa2
#> <35000 x 2000000 NaMatrix> of type "integer" [nnacount=0 (0%)]:
#>                [,1]       [,2]       [,3]       [,4] ... [,1999997] [,1999998]
#>     [1,]         NA         NA         NA         NA   .         NA         NA
#>     [2,]         NA         NA         NA         NA   .         NA         NA
#>     [3,]         NA         NA         NA         NA   .         NA         NA
#>     [4,]         NA         NA         NA         NA   .         NA         NA
#>     [5,]         NA         NA         NA         NA   .         NA         NA
#>      ...          .          .          .          .   .          .          .
#> [34996,]         NA         NA         NA         NA   .         NA         NA
#> [34997,]         NA         NA         NA         NA   .         NA         NA
#> [34998,]         NA         NA         NA         NA   .         NA         NA
#> [34999,]         NA         NA         NA         NA   .         NA         NA
#> [35000,]         NA         NA         NA         NA   .         NA         NA
#>          [,1999999] [,2000000]
#>     [1,]         NA         NA
#>     [2,]         NA         NA
#>     [3,]         NA         NA
#>     [4,]         NA         NA
#>     [5,]         NA         NA
#>      ...          .          .
#> [34996,]         NA         NA
#> [34997,]         NA         NA
#> [34998,]         NA         NA
#> [34999,]         NA         NA
#> [35000,]         NA         NA

## Add some non-NA values to 'naa2':
naa2[cbind( 1:99, 2:100)] <-  1L
naa2[cbind(1:100, 1:100)] <-  0L
naa2[cbind(2:100,  1:99)] <- -1L
naa2
#> <35000 x 2000000 NaMatrix> of type "integer" [nnacount=298 (4.3e-07%)]:
#>                [,1]       [,2]       [,3]       [,4] ... [,1999997] [,1999998]
#>     [1,]          0          1         NA         NA   .         NA         NA
#>     [2,]         -1          0          1         NA   .         NA         NA
#>     [3,]         NA         -1          0          1   .         NA         NA
#>     [4,]         NA         NA         -1          0   .         NA         NA
#>     [5,]         NA         NA         NA         -1   .         NA         NA
#>      ...          .          .          .          .   .          .          .
#> [34996,]         NA         NA         NA         NA   .         NA         NA
#> [34997,]         NA         NA         NA         NA   .         NA         NA
#> [34998,]         NA         NA         NA         NA   .         NA         NA
#> [34999,]         NA         NA         NA         NA   .         NA         NA
#> [35000,]         NA         NA         NA         NA   .         NA         NA
#>          [,1999999] [,2000000]
#>     [1,]         NA         NA
#>     [2,]         NA         NA
#>     [3,]         NA         NA
#>     [4,]         NA         NA
#>     [5,]         NA         NA
#>      ...          .          .
#> [34996,]         NA         NA
#> [34997,]         NA         NA
#> [34998,]         NA         NA
#> [34999,]         NA         NA
#> [35000,]         NA         NA

## The dimnames can be specified at construction time, or
## added/modified later:
naa3 <- NaArray(c(NA, NA, 1L, NA, 0:7, rep(NA, 4), 12:14, NA),
                dim=4:5, dimnames=list(letters[1:4], LETTERS[1:5]))
naa3
#> <4 x 5 NaMatrix> of type "integer" [nnacount=12 (60%)]:
#>    A  B  C  D  E
#> a NA  0  4 NA 12
#> b NA  1  5 NA 13
#> c  1  2  6 NA 14
#> d NA  3  7 NA NA

colnames(naa3) <- LETTERS[22:26]
naa3
#> <4 x 5 NaMatrix> of type "integer" [nnacount=12 (60%)]:
#>    V  W  X  Y  Z
#> a NA  0  4 NA 12
#> b NA  1  5 NA 13
#> c  1  2  6 NA 14
#> d NA  3  7 NA NA

## Sanity checks:
stopifnot(
  is(naa1, "NaArray"),
  identical(dim(naa1), 5:3),
  identical(as.array(naa1), array(dim=5:3)),
  is(naa2, "NaMatrix"),
  all.equal(dim(naa2), c(35000, 2e6)),
  identical(nnacount(naa2), 298L),
  is(naa3, "NaMatrix"),
  identical(dim(naa3), 4:5),
  identical(nnacount(naa3), 12L)
)