samc (version 1.0.4)

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,numeric,missing,numeric
mortality(samc, origin,
  time)
# S4 method for samc,missing,missing,numeric,numeric
mortality(samc, dest,
  time)
# S4 method for samc,missing,numeric,numeric,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,numeric,missing,missing
mortality(samc, origin)
# S4 method for samc,missing,missing,numeric,missing
mortality(samc, dest)
# S4 method for samc,missing,numeric,numeric,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 representing a cell in the landscape, excluding NA cells. Corresponds to row i of matrix P in the samc-class object.

dest

A positive integer representing a cell in the landscape, excluding NA cells. Corresponds to column j of matrix P in the samc-class object.

time

A positive integer representing time steps

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