Calculates the probability of absorption for absorbing states rather than individual transient states. This is distint from, yet very closely linked to, the mortality() metric, which calculates the probability of absorption at individual transient states. If the results of the mortality() metric are decomposed into individual results for each absorbing state, then the sums of the individual results for every transient state are equivalent to the results of the absorption() metric.

absorption(samc, occ, origin)

# S4 method for samc,missing,missing

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

# S4 method for samc,RasterLayer,missing
absorption(samc, occ)

# S4 method for samc,matrix,missing
absorption(samc, occ)



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.


See Details


\(A = F R\)

  • absorption(samc)

    The result is a matrix \(M\) where \(M_{i,k}\) is the probability of absorption due to absorbing state \(\mathit{k}\) if starting at transient state \(\mathit{i}\).

  • absorption(samc, origin)

    The result is a vector \(\mathbf{v}\) where \(\mathbf{v}_{k}\) is the probability of absorption due to absorbing state \(\mathit{k}\) if starting at transient state \(\mathit{i}\).

\(\psi^T A\)

  • absorption(samc, occ)

    The result is a vector \(\mathbf{v}\) where \(\mathbf{v}_{k}\) is the probability of absorption due to absorbing state \(\mathit{k}\) given an initial state \(\psi\).


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


# "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] TRUE
check(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)
#> #> Cached diagonal not found. #> 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)