Calculates the probability of absorption at individual transient states.

mortality(samc, occ, origin, dest, time)

# S4 method for samc,missing,missing,missing,numeric
mortality(samc, time)

# S4 method for samc,missing,location,missing,numeric
mortality(samc, origin, time)

# S4 method for samc,missing,missing,location,numeric
mortality(samc, dest, time)

# S4 method for samc,missing,location,location,numeric
mortality(samc, origin, dest, time)

# S4 method for samc,ANY,missing,missing,numeric
mortality(samc, occ, time)

# S4 method for samc,missing,missing,missing,missing
mortality(samc)

# S4 method for samc,missing,location,missing,missing
mortality(samc, origin)

# S4 method for samc,missing,missing,location,missing
mortality(samc, dest)

# S4 method for samc,missing,location,location,missing
mortality(samc, origin, dest)

# S4 method for samc,ANY,missing,missing,missing
mortality(samc, occ)

## Arguments

samc A samc-class object created using the samc function. The initial state $$\psi$$ of the Markov chain. If the samc-class objects was constructed using map inputs, then occ must be the same type of input (either RasterLayer-class or matrix), and must have the same properties as initial map inputs (see the check function). A positive integer or character name representing transient state $$\mathit{i}$$. Corresponds to row $$\mathit{i}$$ of matrix $$\mathbf{P}$$ in the samc-class object. When paired with the dest parameter, multiple values may be provided as a vector. A positive integer or character name representing transient state $$\mathit{j}$$. Corresponds to column $$\mathit{j}$$ of matrix $$\mathbf{P}$$ in the samc-class object. When paired with the origin parameter, multiple values may be provided as a vector. A positive integer or a vector of positive integers representing $$\mathit{t}$$ time steps. Vectors must be ordered and contain no duplicates. Vectors may not be used for metrics that return dense matrices. The maximum time step value is capped at 10,000 due to numerical precision issues.

See Details

## Details

$$\tilde{B}_t = (\sum_{n=0}^{t-1} Q^n) \tilde{R}$$

• mortality(samc, time)

The result is a matrix $$M$$ where $$M_{i,j}$$ is the probability of absorption at transient state $$\mathit{j}$$ within $$\mathit{t}$$ or fewer steps if starting at transient state $$\mathit{i}$$.

The returned matrix will always be dense and cannot be optimized. Must enable override to use (see samc-class).

• mortality(samc, origin, time)

The result is a vector $$\mathbf{v}$$ where $$\mathbf{v}_j$$ is the probability of absorption at transient state $$\mathit{j}$$ within $$\mathit{t}$$ or fewer steps if starting at transient state $$\mathit{i}$$.

If multiple time steps were provided as a vector, then the result will be an ordered named list containing a vector for each time step.

If the samc-class object was created using matrix or RasterLayer maps, then vector $$\mathbf{v}$$ can be mapped to a RasterLayer using the map function.

• mortality(samc, dest, time)

The result is a vector $$\mathbf{v}$$ where $$\mathbf{v}_i$$ is the probability of absorption at transient state $$\mathit{j}$$ within $$\mathit{t}$$ or fewer steps if starting at transient state $$\mathit{i}$$.

If multiple time steps were provided as a vector, then the result will be an ordered named list containing a vector for each time step.

If the samc-class object was created using matrix or RasterLayer maps, then vector $$\mathbf{v}$$ can be mapped to a RasterLayer using the map function.

• mortality(samc, origin, dest, time)

The result is a numeric value that is the probability of absorption at transient state $$\mathit{j}$$ within $$\mathit{t}$$ or fewer time steps if starting at transient state $$\mathit{i}$$.

If multiple time steps were provided as a vector, then the result will be an ordered named list containing a numeric value for each time step.

$$\psi^T \tilde{B}_t$$

• mortality(samc, occ, time)

The result is a vector $$\mathbf{v}$$ where $$\mathbf{v}_j$$ is the unconditional probability of absorption at transient state $$\mathit{j}$$ within $$\mathit{t}$$ or fewer steps given an initial state $$\psi$$.

If multiple time steps were provided as a vector, then the result will be an ordered named list containing a vector for each time step.

If the samc-class object was created using matrix or RasterLayer maps, then vector $$\mathbf{v}$$ can be mapped to a RasterLayer using the map function.

$$B = F \tilde{R}$$

• mortality(samc)

The result is a matrix $$M$$ where $$M_{i,j}$$ is the probability of absorption at transient state $$\mathit{j}$$ if starting at transient state $$\mathit{i}$$.

The returned matrix will always be dense and cannot be optimized. Must enable override to use (see samc-class).

• mortality(samc, origin)

The result is a vector $$\mathbf{v}$$ where $$\mathbf{v}_j$$ is the probability of absorption at transient state $$\mathit{j}$$ if starting at transient state $$\mathit{i}$$.

If the samc-class object was created using matrix or RasterLayer maps, then vector $$\mathbf{v}$$ can be mapped to a RasterLayer using the map function.

• mortality(samc, dest)

The result is a vector $$\mathbf{v}$$ where $$\mathbf{v}_i$$ is the probability of absorption at transient state $$\mathit{j}$$ if starting at transient state $$\mathit{i}$$.

If the samc-class object was created using matrix or RasterLayer maps, then vector $$\mathbf{v}$$ can be mapped to a RasterLayer using the map function.

• mortality(samc, origin, dest)

The result is a numeric value that is the probability of absorption at transient state $$\mathit{j}$$ if starting at transient state $$\mathit{i}$$.

$$\psi^T B$$

• mortality(samc, occ)

The result is a vector $$\mathbf{v}$$ where $$\mathbf{v}_j$$ is the unconditional probability of absorption at transient state $$\mathit{j}$$ given an initial state $$\psi$$.

If the samc-class object was created using matrix or RasterLayer maps, then vector $$\mathbf{v}$$ can be mapped to a RasterLayer using the map function.

## Performance

Any relevant performance information about this function can be found in the performance vignette: vignette("performance", package = "samc")

## 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)