Create an samc object that contains the absorbing Markov chain data

samc(data, absorption, fidelity, tr_args)

# S4 method for TransitionLayer,RasterLayer,RasterLayer,missing
samc(data, absorption, fidelity)

# S4 method for TransitionLayer,RasterLayer,missing,missing
samc(data, absorption)

# S4 method for RasterLayer,RasterLayer,RasterLayer,list
samc(data, absorption, fidelity, tr_args)

# S4 method for RasterLayer,RasterLayer,missing,list
samc(data, absorption, tr_args)

# S4 method for matrix,matrix,matrix,list
samc(data, absorption, fidelity, tr_args)

# S4 method for matrix,matrix,missing,list
samc(data, absorption, tr_args)

# S4 method for dgCMatrix,missing,missing,missing
samc(data)

# S4 method for matrix,missing,missing,missing
samc(data)

## Arguments

data A RasterLayer-class or matrix or Matrix package dgCMatrix sparse matrix. A RasterLayer-class or matrix A RasterLayer-class or matrix A list with args for constructing a transition matrix.

## Value

A samc-class object

## Details

This function is used to create a samc-class object. There are multiple options for creating this object.

Option 1: Raster or Matrix Maps

samc(data = matrix, absorption = matrix, fidelity = matrix, tr_args = list())

samc(data = RasterLayer, absorption = RasterLayer, fidelity = RasterLayer, tr_args = list())

The samc-class object can be created from a combination of resistance (or conductance), 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).

The data and absorption inputs are always mandatory for this approach. 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 tr_args parameter is mandatory. It used when calculating the values for the transition matrix. Internally, is used in the transition function in the gdistance package to create the transition matrix. tr_args must be constructed as list with a transition function, the number of directions (4 or 8), and if the transition function is symmetric (TRUE or FALSE). Here is the template: list(fun = function, dir = numeric, sym = logical)

Option 2: TransitionLayer

samc(data = TransitionLayer, absorption = RasterLayer, fidelity = RasterLayer)

The data parameter can be a TransitionLayer object created using the gdistance package. In this case the absorption parameter is mandatory and should be a RasterLayer that has identical properties to the RasterLayer used to create the TransitionLayer object. The fidelity parameter is optional and has the same requirements as the absorption parameter. The check function can be used to verify these requirements.

The advantage of this approach is that it offers slightly more flexibility than the first option. Namely, it's useful if the TransitionLayer needs additional modifications before it is normalized with the absorption and fidelity inputs. The disadvantage compared to the first option is that samc() cannot detect certain issues when the TransitionLayer is manually created and modified. So if users do not need to manually modify the TransitionLayer, then the first option for creating a samc object is recommended.

Option 3: P Matrix

samc(data = matrix)

samc(data = dgCMatrix)

The data parameter can be used alone 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 following requirements:

• The number of rows must equal the number of columns (a square matrix)

• Total absorption must be a single column on the right-hand side of the matrix

• At the bottom of the matrix, there must be a row filled with 0's except for last element (bottom-right of the matrix diagonal), which must be set to 1

• Every disconnected region of the matrix must have at least one non-zero absorbing value

• 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.

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.

Version 2 Changes

Version 1.5.0 officially removed support for the deprecated resistance, tr_fun, directions, p_mat, latlon, and override arguments. Old code will have to be updated to the new samc() function structure in order to work.

## Examples

# "Load" the data. In this case we are using data built into the package.
# In practice, users will likely load raster data using the raster() function
# from the raster package.
res_data <- samc::ex_res_data
abs_data <- samc::ex_abs_data
occ_data <- samc::ex_occ_data

# Make sure our data meets the basic input requirements of the package using
# the check() function.
check(res_data, abs_data)
#> [1] TRUEcheck(res_data, occ_data)
#> [1] TRUE
# Setup the details for our transition function
tr <- list(fun = function(x) 1/mean(x), # Function for calculating transition probabilities
dir = 8, # Directions of the transitions. Either 4 or 8.
sym = TRUE) # Is the function symmetric?

# Create a samc-class object with the resistance and absorption data using
# the samc() function. We use the recipricol of the arithmetic mean for
# calculating the transition matrix. Note, the input data here are matrices,
# not RasterLayers.
samc_obj <- samc(res_data, abs_data, tr_args = tr)

# Convert the occupancy data to probability of occurrence
occ_prob_data <- occ_data / sum(occ_data, na.rm = TRUE)

# Calculate short- and long-term metrics using the analytical functions
short_mort <- mortality(samc_obj, occ_prob_data, time = 50)
short_dist <- distribution(samc_obj, origin = 3, time = 50)
long_disp <- dispersal(samc_obj, occ_prob_data)
#>
#> Performing setup. This can take several minutes... Complete.
#> Calculating matrix inverse diagonal...
#>
Complete
#> Diagonal has been cached. Continuing with metric calculation...visit <- visitation(samc_obj, dest = 4)
surv <- survival(samc_obj)

# Use the map() function to turn vector results into RasterLayer objects.
short_mort_map <- map(samc_obj, short_mort)
short_dist_map <- map(samc_obj, short_dist)
long_disp_map <- map(samc_obj, long_disp)
visit_map <- map(samc_obj, visit)
surv_map <- map(samc_obj, surv)