as.matrix: Retrieve Species Matrix with Specified Storage Mode
In vegsoup: Classes and Methods for Phytosociology
Description
Usage
Arguments
Details
Value
Note
Author(s)
References
See Also
Examples
Description
The methods retrieve a community table as class 'matrix' and of mode according to the methods literal name.
Method as.matrix returns corresponding types of matrices but specified by an argument typeof, the same holds true for as.array.
The indices method extracts the (possibly converted) values and row and column indices of these in a matrix (sparse matrix representation), as well as corresponding row and column names.
The latter have a special meaning in all methods, since they carry an attribute assigning species to vegetation layer or strata (cross-classifying factors).
Usage
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
## S4 method for signature 'Vegsoup'
as.logical(x, mode)
## S4 method for signature 'Vegsoup'
as.numeric(x, mode)
## S4 method for signature 'Vegsoup'
as.character(x, mode)
## S4 method for signature 'Vegsoup'
as.matrix(x, typeof, ...)
## S4 method for signature 'Vegsoup'
as.array(x, typeof, ...)
## S4 method for signature 'Vegsoup'
indices(x, typeof)
## S4 method for signature 'Vegsoup'
as.vector(x, mode)
Arguments
x
Vegsoup object.
mode
character. If mode = "R" the method returns the transposed matrix. If missing, the default
no transposition happens (mode = "Q"). Lower and upper case letters are treated the same.
See ‘Details’.
typeof
Selects the desired storage mode or type of the object.
Can be one of "character", "numeric" or "logical".
...
Arguments passed to as.logical etc. to supply a value for
argument mode. See argument mode.
Details
For any object inheriting from class Vegsoup the methods return an object of class 'matrix' with dimnames giving plot and species names.
The latter are strings where any occurrence in a layer is labeled using the layer name and the species abbreviation, collapsed with the "@" glyph (layer-replicate or pseudo-species, see layers, splitAbbr and abbr).
The object returned by a method (except indices and as.vector) is suitable as input to functions in other packages that demand an object of class 'matrix'.
Dispatch is guaranteed if these functions internally coerce objects to this class by calls to as.matrix.
Besides that, it is possible to supply a Vegsoup* object to a base function by wrapping it into a respective method (see ‘Examples’).
As there is no way to specify the typeof or mode arguments in a call to a base function the S3 method for as.matrix() uses typeof = "numeric" as default, which is suitable for most applications.
If the user wants to ensure that presence/absence data should be returned by calls to as.matrix inside functions of other packages , simply assign a standardization method beforehand (e.g. decostand(x) <- "pa").
See also as.data.frame for passing data to model-fitting and plotting functions.
Note, the behavior of the as.numeric and two related as.* methods is rather untypical, in the way that they do not return vectors but also matrices (see below)!
The idea here is to simplify the writing of code.
Certainly, the as.vector method returns a vector of length ncell(x), where the storage mode can be controlled by argument mode.
Let's recall the above mentioned as.* methods as as.matrix calls these internally:
as.numeric returns a matrix of mode "numeric" with species abundances coded by coverscale(obj)@lims.
Absences are zeros.
Equals as.matrix(x, typeof = "numeric").
as.character returns a matrix of mode "character" with species abundances in the data set's original scale (coverscale(x)@codes).
Absences are coded as zeros not dots!
Equals as.matrix(x, typeof = "character").
as.logical returns a matrix of mode "numeric" with zeros coding for species absences and ones for presences.
Equals as.matrix(x, mode = "logical").
It has to be noted that, as.logical and as.matrix(x, "logical") do not return a boolean or logical matrix composed of TRUE and FALSE but use ones to code presences (TRUE) and zeros (FALSE) for absences.
The mode (storage.mode) of the returned matrix is of type "numeric" (more specifically of mode "integer").
As outlined above, the somehow misleading named argument mode refers to the type of analysis intended on the returned object (recall, "typeof" determines mode (storage.mode) of the returned matrix).
This is due to constraints implied by the definition of the imported generic methods.
The argument mode can be passed to all methods and has two possible values.
If mode = "Q" pairs of objects are compared and the analysis is said to be in R mode –
this is what users usually want or expect.
When pairs of descriptors are compared, the analysis is said to be in Q mode (Legendre & Legendre 2012).
For example, as.matrix(x, "logical", "R") returns a transposed presence/absence matrix.
Of course, this can also be written as t(as.matrix(x, "logical")) or as.logical(x, mode = "R").
The as.array method is useful when an object having more than one layer should be represented as a multidimensional dimensional array, where there are as many dimensions as there are layers – method as.array returns such an array.
Note, the order in which species appear in the column names is alphabetic and there is currently no implementation of the 'mode' argument to simultaneously transpose the array!
Finally, the indices method returns the locations (row and column pointers) and values of nonzero entries in a matrix.
Those indices can be used to construct a sparseMatrix. Coercion method as(x, "sparseMatrix") helps in doing so.
Summary of the meaning of arguments mode and typeof for all methods.
method mode typeof
as.logical, as.numeric, as.character Q or R mode analysis defined by literal name
as.matrix, as.array Q or R mode analysis character, numeric or logical
as.vector character, numeric or logical not defined
indices not defined character, numeric or logical
Value
A 'matrix' (or 'array') of mode "numeric" or "character". See ‘Details’.
For as.vector, a vector of length of ncell(x).
Note
If the object has non NULL values in its data standardization slot the method defined by decostand(x) applies!
Author(s)
Roland Kaiser
References
Legendre, P. and Legendre, L. (2012). Chapter 7 in Numerical ecology. Developments in environmental modeling, 24.
See Also
as.data.frame for passing data to model-fitting and plotting functions,
as.data.frame,
Vegsoup,
decostand and
Coverscale
Examples
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
require(vegsoup)
data(barmstein)
x <- barmstein
# presence/absence representation
x.pa <- as.logical(x)
# the same results can be achieved using the classes decostand property
decostand(x) <- "pa"
# note, results of as.numeric() and as.logical()
# are equal if presence/absence (transformation) is applied
x.pa2 <- as.numeric(x)
# for a true boolean matrix change mode
mode(x.pa) <- "logical"
head(x.pa)
all.equal(x.pa, x.pa2, check.attributes = FALSE)
# using as.matrix and argument mode
as.matrix(x, typeof = "character", mode = "R")
# compact display
as(as.matrix(x, "logical", "R"), "sparseMatrix")
pro <- protest(as.logical(x), as.numeric(x))
# objects of class Vegsoup used in arguments of base functions
# where an object of class matrix is expected
decostand(x) <- "hellinger"
decorana(x)
decostand(x) <- NULL # reset the default
# species matrix representations and memory demands
# class "matrix"
s1 <- object.size(as.matrix(x)) # most efficient
# class "list" (pointers and values of all non zero entries)
s2 <- object.size(indices(x)) # almost equal
# coercion to class "sparseMatrix" is based on method indices
s3 <- object.size(as(x, "sparseMatrix")) # efficient
# the long format as stored in Vegsoup* objects (slot 'species')
s4 <- object.size(species(x)) # most general but least efficent
# a multi-dimensional array of layer replicates
s5 <- object.size(as.array(x)) # least efficent
( s <- data.frame(size = as.numeric(c(s1, s2, s3, s4, s5)),
row.names = c("matrix", "indices", "sparseMatrix",
"Species", "array")) )
barplot(t(s), ylab = "object size")
# comparison of memory demands of objects of other classes
# package multitable was removed from the CRAN repository
# s0 <- object.size(as(x, "data.list")) # least efficent, but highly generic
s1 <- object.size(as(x, "mefa")) # more efficent, but less generic
s2 <- object.size(as.data.frame(x)) # efficent, but rather meaningless
# for comparison subtract slots with sp objects
sp.object.size <- object.size(x@sp.points) + object.size(x@sp.polygons)
s3 <- object.size(x) - sp.object.size # most general and most efficent
( s <- data.frame(size = as.numeric(c(s1, s2, s3)),
row.names = c("mefa", "data.frame", "vegsoup")) )
barplot(t(s), ylab = "object size")
vegsoup documentation built on Feb. 24, 2021, 3 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description Usage Arguments Details Value Note Author(s) References See Also Examples
Description
The methods retrieve a community table as class 'matrix' and of mode according to the methods literal name.
Method as.matrix returns corresponding types of matrices but specified by an argument typeof, the same holds true for as.array.
The indices method extracts the (possibly converted) values and row and column indices of these in a matrix (sparse matrix representation), as well as corresponding row and column names.
The latter have a special meaning in all methods, since they carry an attribute assigning species to vegetation layer or strata (cross-classifying factors).
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | ## S4 method for signature 'Vegsoup'
as.logical(x, mode)
## S4 method for signature 'Vegsoup'
as.numeric(x, mode)
## S4 method for signature 'Vegsoup'
as.character(x, mode)
## S4 method for signature 'Vegsoup'
as.matrix(x, typeof, ...)
## S4 method for signature 'Vegsoup'
as.array(x, typeof, ...)
## S4 method for signature 'Vegsoup'
indices(x, typeof)
## S4 method for signature 'Vegsoup'
as.vector(x, mode)
|
Arguments
x |
Vegsoup object. |
mode |
character. If |
typeof |
Selects the desired storage mode or type of the object.
Can be one of |
... |
Arguments passed to |
Details
For any object inheriting from class Vegsoup the methods return an object of class 'matrix' with dimnames giving plot and species names.
The latter are strings where any occurrence in a layer is labeled using the layer name and the species abbreviation, collapsed with the "@" glyph (layer-replicate or pseudo-species, see layers, splitAbbr and abbr).
The object returned by a method (except indices and as.vector) is suitable as input to functions in other packages that demand an object of class 'matrix'.
Dispatch is guaranteed if these functions internally coerce objects to this class by calls to as.matrix.
Besides that, it is possible to supply a Vegsoup* object to a base function by wrapping it into a respective method (see ‘Examples’).
As there is no way to specify the typeof or mode arguments in a call to a base function the S3 method for as.matrix() uses typeof = "numeric" as default, which is suitable for most applications.
If the user wants to ensure that presence/absence data should be returned by calls to as.matrix inside functions of other packages , simply assign a standardization method beforehand (e.g. decostand(x) <- "pa").
See also as.data.frame for passing data to model-fitting and plotting functions.
Note, the behavior of the as.numeric and two related as.* methods is rather untypical, in the way that they do not return vectors but also matrices (see below)!
The idea here is to simplify the writing of code.
Certainly, the as.vector method returns a vector of length ncell(x), where the storage mode can be controlled by argument mode.
Let's recall the above mentioned as.* methods as as.matrix calls these internally:
as.numeric returns a matrix of mode "numeric" with species abundances coded by coverscale(obj)@lims.
Absences are zeros.
Equals as.matrix(x, typeof = "numeric").
as.character returns a matrix of mode "character" with species abundances in the data set's original scale (coverscale(x)@codes).
Absences are coded as zeros not dots!
Equals as.matrix(x, typeof = "character").
as.logical returns a matrix of mode "numeric" with zeros coding for species absences and ones for presences.
Equals as.matrix(x, mode = "logical").
It has to be noted that, as.logical and as.matrix(x, "logical") do not return a boolean or logical matrix composed of TRUE and FALSE but use ones to code presences (TRUE) and zeros (FALSE) for absences.
The mode (storage.mode) of the returned matrix is of type "numeric" (more specifically of mode "integer").
As outlined above, the somehow misleading named argument mode refers to the type of analysis intended on the returned object (recall, "typeof" determines mode (storage.mode) of the returned matrix).
This is due to constraints implied by the definition of the imported generic methods.
The argument mode can be passed to all methods and has two possible values.
If mode = "Q" pairs of objects are compared and the analysis is said to be in R mode –
this is what users usually want or expect.
When pairs of descriptors are compared, the analysis is said to be in Q mode (Legendre & Legendre 2012).
For example, as.matrix(x, "logical", "R") returns a transposed presence/absence matrix.
Of course, this can also be written as t(as.matrix(x, "logical")) or as.logical(x, mode = "R").
The as.array method is useful when an object having more than one layer should be represented as a multidimensional dimensional array, where there are as many dimensions as there are layers – method as.array returns such an array.
Note, the order in which species appear in the column names is alphabetic and there is currently no implementation of the 'mode' argument to simultaneously transpose the array!
Finally, the indices method returns the locations (row and column pointers) and values of nonzero entries in a matrix.
Those indices can be used to construct a sparseMatrix. Coercion method as(x, "sparseMatrix") helps in doing so.
Summary of the meaning of arguments mode and typeof for all methods.
| method | mode | typeof |
| as.logical, as.numeric, as.character | Q or R mode analysis | defined by literal name |
| as.matrix, as.array | Q or R mode analysis | character, numeric or logical |
| as.vector | character, numeric or logical | not defined |
| indices | not defined | character, numeric or logical |
Value
A 'matrix' (or 'array') of mode "numeric" or "character". See ‘Details’.
For as.vector, a vector of length of ncell(x).
Note
If the object has non NULL values in its data standardization slot the method defined by decostand(x) applies!
Author(s)
Roland Kaiser
References
Legendre, P. and Legendre, L. (2012). Chapter 7 in Numerical ecology. Developments in environmental modeling, 24.
See Also
as.data.frame for passing data to model-fitting and plotting functions,
as.data.frame,
Vegsoup,
decostand and
Coverscale
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 | require(vegsoup)
data(barmstein)
x <- barmstein
# presence/absence representation
x.pa <- as.logical(x)
# the same results can be achieved using the classes decostand property
decostand(x) <- "pa"
# note, results of as.numeric() and as.logical()
# are equal if presence/absence (transformation) is applied
x.pa2 <- as.numeric(x)
# for a true boolean matrix change mode
mode(x.pa) <- "logical"
head(x.pa)
all.equal(x.pa, x.pa2, check.attributes = FALSE)
# using as.matrix and argument mode
as.matrix(x, typeof = "character", mode = "R")
# compact display
as(as.matrix(x, "logical", "R"), "sparseMatrix")
pro <- protest(as.logical(x), as.numeric(x))
# objects of class Vegsoup used in arguments of base functions
# where an object of class matrix is expected
decostand(x) <- "hellinger"
decorana(x)
decostand(x) <- NULL # reset the default
# species matrix representations and memory demands
# class "matrix"
s1 <- object.size(as.matrix(x)) # most efficient
# class "list" (pointers and values of all non zero entries)
s2 <- object.size(indices(x)) # almost equal
# coercion to class "sparseMatrix" is based on method indices
s3 <- object.size(as(x, "sparseMatrix")) # efficient
# the long format as stored in Vegsoup* objects (slot 'species')
s4 <- object.size(species(x)) # most general but least efficent
# a multi-dimensional array of layer replicates
s5 <- object.size(as.array(x)) # least efficent
( s <- data.frame(size = as.numeric(c(s1, s2, s3, s4, s5)),
row.names = c("matrix", "indices", "sparseMatrix",
"Species", "array")) )
barplot(t(s), ylab = "object size")
# comparison of memory demands of objects of other classes
# package multitable was removed from the CRAN repository
# s0 <- object.size(as(x, "data.list")) # least efficent, but highly generic
s1 <- object.size(as(x, "mefa")) # more efficent, but less generic
s2 <- object.size(as.data.frame(x)) # efficent, but rather meaningless
# for comparison subtract slots with sp objects
sp.object.size <- object.size(x@sp.points) + object.size(x@sp.polygons)
s3 <- object.size(x) - sp.object.size # most general and most efficent
( s <- data.frame(size = as.numeric(c(s1, s2, s3)),
row.names = c("mefa", "data.frame", "vegsoup")) )
barplot(t(s), ylab = "object size")
|
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.