Overview

Andrew Marx

2019-08-20

Data

Required Data

In order to use this package, two different sets of landscape data are required: resistance and absorption. There are certain requirements for these:

If using RasterLayer objects, then additional conditions must be met:

Optional Data

The use of landscape fidelity data is optional. By default, the package treats all cells in the landscape data the same and uses a value of 0 for fidelity. If custom data is desired, then it must meet all of the same requirements listed above for the resistance and absorption landscape data.

Built-in Example Data

The package includes built-in example data. Some of this data was used to create the figures in the SAMC paper, and is used in this tutorial. They are:

The samc-class

The samc-class is used to manage the transition matrix and information about your landscape data to help ensure that the calculations used by the rest of the package are used correctly. Creating an samc-class object is the mandatory first step in the package, and is created using the samc() utility function. The samc() function has several parameters. Some of these are mandatory, some are only mandatory in certain situations, and some are optional. The overall function signature is as follows:

samc(resistance, absorption, fidelity, latlon, tr_fun, override)

An explanation of the arguments:

Utility Functions

In addition to the extremely important samc() function, the package has other utility functions that users might find helpful:

Analytical Functions

The package implements functions for the formulas provided in Table 1 of Fletcher et al. (2019). Many of the formulas are related conceptually, and are grouped together into single functions with multiple parameter signatures to reduce the number of unique function names needed. Note that the descriptions assume \(\psi\) contains probability of occurrence. If \(\psi\) instead contains the number of individuals, then the metrics with \(\psi\) will return the number of expected individuals rather than a probability.

Function Equation Description
dispersal() \(\tilde{D}_{jt}=({\sum}_{n=0}^{t-1}\tilde{Q}^n)\tilde{q}_j\) Probability of an individual visiting a location, if starting at any other location, before or at time t
\(\psi^T\tilde{D}_{jt}\) Probability of an individual visiting a location, before or at time t, regardless of initial location
\(D=(F-I)diag(F)^{-1}\) Probability of an individual visiting a location
\(\psi^TD\) Probability of an individual visiting a location, regardless of initial location
distribution() \(Q^t\) Probability of an individual being at a location at time t
\(\psi^TQ^t\) Probability of an individual being at a location at time t, regardless of initial location
mortality() \(\tilde{B}_t = (\sum_{n=0}^{t-1} Q^n) \tilde{R}\) Probability of an individual experiencing mortality at a location before or at time t
\(\psi^T \tilde{B}_t\) Probability of an individual experiencing mortality at a location, before or at time t, regardless of initial location
\(B = F \tilde{R}\) Probability of an individual experiencing mortality at a location
\(\psi^T B\) Probability of an individual experiencing mortality at a location, regardless of initial location
survival() \(z=(I-Q)^{-1}{\cdot}1=F{\cdot}1\) Expected life expectancy of an individual
\({\psi}^Tz\) Overall life expectancy, regardless of initial location
visitation() \(F = (I-Q)^{-1}\) Expected number of times an individual visits a location

Depending on the combination of inputs used, a function might return a single value, a vector, or a matrix. In some cases, the calculations will not be practical with sufficiently large landscape datasets due to memory and other performance constraints. To work around this, many equations have multiple associated function signatures that allow users to calculate individual portions of the result rather than the entire result. This opens up multiple optimizations that makes calculating many of the metrics more practical. More specific details about performance considerations can be found in the Performance vignette.