arkhe

Overview

A collection of classes that represent archaeological data. This package provides a set of S4 classes that represent different special types of matrix (absolute/relative frequency, presence/absence data, co-occurrence matrix, etc.) upon which package developers can build subclasses. It also provides a set of generic methods (mutators and coercion mechanisms) and functions (e.g. predicates). In addition, a few classes of general interest (e.g. that represent stratigraphic relationships) are implemented.

Installation

You can install the released version of arkhe from CRAN with:

install.packages("arkhe")

Or install the development version from GitHub with:

# install.packages("remotes")
remotes::install_github("nfrerebeau/arkhe")

Usage

# Load the package
library(arkhe)

arkhe provides a set of S4 classes that represent different special types of matrix.

• Integer matrix:
  • CountMatrix represents absolute frequency data,
• Numeric matrix:
  • AbundanceMatrix represents relative frequency data,
  • OccurrenceMatrix represents a co-occurrence matrix,
  • SimilarityMatrix represents a (dis)similarity matrix,
• Logical matrix:
  • IncidenceMatrix represents presence/absence data,
  • StratigraphicMatrix represents stratigraphic relationships.

It assumes that you keep your data tidy: each variable (type/taxa) must be saved in its own column and each observation (assemblage/sample) must be saved in its own row.

These new classes are of simple use, on the same way as the base matrix:

# Define a count data matrix
# (data will be rounded to zero decimal places, then coerced with as.integer)
quanti <- CountMatrix(data = sample(0:10, 100, TRUE), nrow = 10, ncol = 10)

# Define a logical matrix
# (data will be coerced with as.logical)
quali <- IncidenceMatrix(data = sample(0:1, 100, TRUE), nrow = 10, ncol = 10)

arkhe uses coercing mechanisms (with validation methods) for data type conversions:

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

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

## Coerce to relative frequencies
B <- as_abundance(A1)

## Row sums are internally stored before coercing to a frequency matrix
## (use get_totals() to get these values)
## This allows to restore the source data
A2 <- as_count(B)
all(A1 == A2)
#> [1] TRUE

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

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

Many familiar methods and group generic functions are available for all *Matrix classes (such as length, dim, rowSums, rowMeans, Arith, Compare, Logic…). In addition, all functions that call as.matrix or as.data.frame first on their main argument should work (e. g. apply).

rowSums(A1)
#>  row1  row2  row3  row4  row5  row6  row7  row8  row9 row10 
#>    48    51    54    46    47    44    61    49    60    50
apply(X = A1, MARGIN = 1, FUN = sum)
#>  row1  row2  row3  row4  row5  row6  row7  row8  row9 row10 
#>    48    51    54    46    47    44    61    49    60    50

Please note that all *Matrix classes extend the R base matrix, but the S3 part of the object does not store the data. Values are stored in a specific slot (allowing type checking).

X <- CountMatrix(data = sample(0:10, 25, TRUE), nrow = 5, ncol = 5)

## Get the S3 part
S3Part(X, strictS3 = TRUE)
#>      col1 col2 col3 col4 col5
#> row1    1    6   11   16   21
#> row2    2    7   12   17   22
#> row3    3    8   13   18   23
#> row4    4    9   14   19   24
#> row5    5   10   15   20   25

## Coerce to an S3 matrix
as.matrix(X)
#>      col1 col2 col3 col4 col5
#> row1    4    1    1    2    6
#> row2   10    0    5    0    8
#> row3    6   10    7    1   10
#> row4    9    0    7    2    7
#> row5    5    5    1    5    7

Contributing

Please note that the arkhe project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.