This function is used to create a samc-class object. There are
two options for creating this object.
Option 1: Raster and Matrix Inputs
The samc-class object can be created from a combination of
resistance, absorption, and fidelity data. These different landscape data
inputs must be the same type (a matrix or RasterLayer), and have identical
properties, including dimensions, location of NA cells, and CRS (if using
RasterLayers). Some of the inputs are mandatory, whereas others are optional.
The resistance and absorption inputs are always mandatory, whereas the
fidelity input is optional. If the fidelity input is not provided, then it it
is assumed that there is no site fidelity (i.e., individuals will always move
to an adjacent cell each time step).
The latlon parameter is required if the landscape data inputs are RasterLayer
objects. The package does not attempt to determine this automatically, and it
does not assume a default. Users must set it to TRUE if they are using
latitude and longitude data.
The tr_fun parameter is mandatory. It used when calculating the values for
the transition matrix. Internally, this is passed to the transition
function in the gdistance package to create the transition matrix.
Option 2: P Matrix Input
The p_mat parameter can be used to create a samc-class object
directly from a preconstructed P matrix. This matrix must be either a base R
matrix, or a sparse matrix (dgCMatrix format) from the Matrix package. It
must meet the requirement of a P matrix described in Fletcher et al. (2019).
This includes:
The number of rows must equal the number of columns (a square matrix)
The last row must contain all 0's, except the last element, which must be 1
Each row must sum to 1
All values must be in the range of 0-1
Additionally, the columns and rows of the P matrix may be named (e.g., using
dimnames(), rowname(), colnames(), etc). When specifying origin or dest inputs
to metrics, these names may be used instead of cell numbers. This has the
advantage of making the code for an analysis easier to read and interpret,
which may also help to eliminate unintentional mistakes. There are two
requirements for naming the rows/cols of a P matrix. First, since the P matrix
represents a pairwise matrix, the row and column names must be the same. Second,
there must be no duplicate names. The exception to these rules is the very last
column and the very last row of the P matrix. Since these are not part of the
pairwise transition matrix, they may have whatever names the user prefers.
Other Parameters
The override parameter is optional. To prevent users from unintentionally
running memory intensive versions of functions that could make their systems
non-responsive or crash software, it is set to FALSE by default. For various
reasons, it can be set to TRUE. In particular, a user might do this if they
are using a very small landscape dataset, or perhaps for a moderately sized
dataset if they have access to a system with exceptionally large amounts of
RAM. Before setting this to TRUE, users should read the Performance vignette/
article to understand the expected memory requirements. They should also
consider starting with scaled down version of their data and then gradually
scaling back up while monitoring their memory usage as a means to gauge what
is reasonable for their system.
The directions parameter is optional. When constructing the P matrix from
matrix or raster data, the samc() function must decide how adjacent cells are
connected. This value can be set to either 4 or 8. When set to 4, nodes are
connected horizontally and vertically (similar to the directions of how a rook
moves in chess). When set to 8, nodes are connected diagonally in addition to
horizontally and vertically (queen movement in chess). When not specified,
the samc() function defaults to a value of 8. When using large datasets to
construct a P matrix, setting the directions to 4 may lead to significant
improvements in computation time and the amount of memory needed to perform
an analysis.
Additional Information
Depending on the data used to construct the samc-class object, some metrics
may cause crashes. This is a result of the underlying P matrix having specific
properties that make some equations unsolvable. One known case is a P matrix
that represents a disconnected graph, which can lead to the cond_passage()
function crashing. In terms of raster/matrix inputs, a disconnected graph
occurs when one or more pixels/cells are unreachable from other pixels/cells
due to the presence of a full barrier made up of NA values. In a raster, these
may be obvious as islands, but can be as inconspicuous as a rogue isolated
pixel. There may be other currently unknown situations that lead to unsolvable
metrics.
Future work is planned towards identifying these issues during creation of the
samc-class object and handling them appropriately to prevent inadvertent
crashes.