samc (version 1.3.0)

mortality: Calculate mortality metrics

Description

Calculates the probability of experiencing mortality at specific locations.

Usage

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,RasterLayer,missing,missing,numeric
mortality(samc, occ, time)
# S4 method for samc,matrix,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,RasterLayer,missing,missing,missing
mortality(samc, occ)
# S4 method for samc,matrix,missing,missing,missing
mortality(samc, occ)

Arguments

samc

A samc-class object. This should be output from the samc function.

occ

A RasterLayer-class or matrix. The input type must match the input type used to create the samc-class object, and must have the same properties as the rest of the landscape data. See the check function for more details.

origin

A positive integer or named location representing a cell in the landscape. Corresponds to row i of matrix P in the samc-class object. When paired with the dest parameter, multiple values may be provided as a vector.

dest

A positive integer or named location representing a cell in the landscape. Corresponds to column j of matrix P in the samc-class object. When paired with the origin parameter, multiple values may be provided as a vector.

time

A positive integer or a vector of positive integers representing 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.

Value

A matrix, vector, or numeric

Performance

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

Details

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

• mortality(samc, time)

  The result is a matrix where element (i,j) is the probability of experiencing mortality at location j within t or fewer steps if starting at location i.

  The returned matrix will always be dense and cannot be optimized. Must enable override to use.

• mortality(samc, origin, time)

  The result is a vector (single time step) or a list of vectors (multiple time steps) where each element corresponds to a cell in the landscape, and can be mapped back to the landscape using the map function. Element j is the probability of experiencing mortality at location j within t or fewer steps if starting at a given origin.

• mortality(samc, dest, time)

  The result is a vector (single time step) or a list of vectors (multiple time steps) where each element corresponds to a cell in the landscape, and can be mapped back to the landscape using the map function. Element i is the probability of experiencing mortality at a given destination within t or fewer steps if starting at location i.

• mortality(samc, origin, dest, time)

  The result is a numeric value (single time step) or a list of numeric values (multiple time steps) that is the probability of experiencing mortality at a given destination within t or fewer steps if starting at a given origin.

\(\psi^T \tilde{B}_t\)

• mortality(samc, occ, time)

  The result is a vector (single time step) or a list of vectors (multiple time steps) where each element corresponds to a cell in the landscape, and can be mapped back to the landscape using the map function. Element j is the unconditional probability of experiencing mortality at location j within t or fewer time steps.

\(B = F \tilde{R}\)

• mortality(samc)

  The result is a matrix where element (i,j) is the probability of experiencing mortality at location j if starting at location i.

  The returned matrix will always be dense and cannot be optimized. Must enable override to use.

• mortality(samc, origin)

  The result is a vector where each element corresponds to a cell in the landscape, and can be mapped back to the landscape using the map function. Element j is the probability of experiencing mortality at location j if starting at a given origin.

• mortality(samc, dest)

  The result is a vector where each element corresponds to a cell in the landscape, and can be mapped back to the landscape using the map function. Element i is the probability of experiencing mortality at a given destination if starting at location i.

• mortality(samc, origin, dest)

  The result is a numeric value that is the probability of experiencing mortality at a given destination if starting at a given origin

\(\psi^T B\)

• mortality(samc, occ)

  The result is a vector where each element corresponds to a cell in the landscape, and can be mapped back to the landscape using the map function. Element j is the unconditional probability of experiencing mortality at location j, regardless of the initial state.

Examples

# NOT RUN {
# "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)
check(res_data, occ_data)


# 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. If using RasterLayers, the latlon parameter must be set.
samc_obj <- samc(res_data, abs_data, tr_fun = function(x) 1/mean(x))


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