Calculates the number of times that transient states are visited before absorption.

visitation(samc, origin, dest)

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

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

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

# S4 method for samc,location,location
visitation(samc, origin, dest)

Arguments

samc

A samc-class object created using the samc function.

origin

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.

dest

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.

Value

See Details

Details

\(F = (I-Q)^{-1}\)

  • visitation(samc)

    The result is a matrix \(M\) where \(M_{i,j}\) is the number of times that transient state \(\mathit{j}\) is visited before absorption 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).

  • visitation(samc, origin)

    The result is a vector \(\mathbf{v}\) where \(\mathbf{v}_j\) is the number of times that transient state \(\mathit{j}\) is visited before absorption 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.

  • visitation(samc, dest)

    The result is a vector \(\mathbf{v}\) where \(\mathbf{v}_i\) is the number of times that transient state \(\mathit{j}\) is visited before absorption 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.

  • visitation(samc, origin, dest)

    The result is a numeric value that is the number of times transient state \(\mathit{j}\) is visited before absorption if starting at transient state \(\mathit{i}\).

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