Coerce

Coerces an object to a *Matrix object.

Usage

as_long(from, ...)

as_count(from)

as_composition(from)

as_incidence(from)

as_occurrence(from)

as_features(from)

as_stratigraphy(from)

# S4 method for ANY
as_count(from)

# S4 method for ANY
as_composition(from)

# S4 method for ANY
as_incidence(from)

# S4 method for ANY
as_occurrence(from)

# S4 method for ANY
as_stratigraphy(from)

# S4 method for matrix
as_long(from, factor = FALSE, reverse = FALSE)

# S4 method for AbundanceMatrix
as_long(from, factor = FALSE, reverse = FALSE)

# S4 method for AbundanceMatrix
as_features(from)

Arguments

from: An object to be coerced.
...: Currently not used.
factor: A logical scalar: should character string be coerced to factor? Default to FALSE, if TRUE the original ordering is preserved.
reverse: A logical scalar: should the order of factor levels be reversed? Only used if factor is TRUE. Useful for plotting.

Value

A coerced object.

Details

The following methods coerce an object to a *Matrix object:

Method	Target	Details
`as_count()`	CountMatrix	absolute frequency data
`as_composition()`	CompositionMatrix	relative frequency data
`as_incidence()`	IncidenceMatrix	presence/absence data
`as_occurrence()`	OccurrenceMatrix	co-occurrence
`as_stratigraphy()`	StratigraphicMatrix	stratigraphic relationships

Note that as_count() rounds numeric values to zero decimal places and then coerces to integer as by as.integer().

as_stratigraphy() converts a set of stratigraphic relationships (edges) to a stratigraphic (adjacency) matrix. from can be a matrix, list, or data.frame: the first column/component is assumed to contain the bottom units and the second the top units (adjacency).

Method	Target	Details
`as_long()`	`data.frame`	long S3 data frame
`as_features()`	`data.frame`	wide S3 data frame

as_features() converts a *Matrix object to a collection of features: a data.frame with all informations as extra columns (result may differ according to the class of from).

Abundance Matrix

The CountMatrix, CompositionMatrix and IncidenceMatrix classes have special slots:

samples for replicated measurements/observation,
groups to group data by site/area,
dates to specify the date point estimate of an assemblage,
tqp and taq to specify the chronology of an assemblage.

When coercing a data.frame to a *Matrix object, an attempt is made to automatically assign values to these slots by mapping column names (case insensitive, plural insensitive). This behavior can be disabled by setting options(arkhe.autodetect = FALSE) or overrided by explicitly specifying the columns to be used in as_*().

Chronology

The way chronological information is handled is somewhat opinionated. Sub-annual precision is overkill/meaningless in most situations: dates are assumed to be expressed in years CE and are stored as integers (values are coerced with as.integer() and hence truncated towards zero).

Author

N. Frerebeau

Examples

## Create a count matrix
A0 <- matrix(data = sample(0:10, 100, TRUE), nrow = 20, ncol = 5)

## Coerce to absolute frequencies
A1 <- as_count(A0)

## Coerce to relative frequencies
B0 <- as_composition(A1)

## Row sums are internally stored before coercing to relative frequencies
## (use get_totals() to retrieve these values)
## This allows to restore the source data
A2 <- as_count(B0)
all(A1 == A2)
#> [1] TRUE

## Coerce to presence/absence
C0 <- as_incidence(A1)

## Coerce to a co-occurrence matrix
D0 <- as_occurrence(A1)

## Coerce to an S3 matrix or data.frame
X <- as.matrix(A1)
all(A0 == X)
#> [1] TRUE

Y <- data.frame(A1)
head(Y)
#>      col1 col2 col3 col4 col5
#> row1    8    7    7   10    0
#> row2    2    3    2    3    5
#> row3    1    8    3    3    8
#> row4    8    1    9    2    4
#> row5    4    1    9    1    1
#> row6    3    5    9    5    9