visitation: Calculate visitation metrics
In samc: Spatial Absorbing Markov Chains

visitation

R Documentation

Calculate visitation metrics

Description

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

Usage

visitation(samc, init, origin, dest, time)

## S4 method for signature 'samc,missing,missing,missing,numeric'
visitation(samc, time)

## S4 method for signature 'samc,missing,location,missing,numeric'
visitation(samc, origin, time)

## S4 method for signature 'samc,missing,missing,location,numeric'
visitation(samc, dest, time)

## S4 method for signature 'samc,missing,location,location,numeric'
visitation(samc, origin, dest, time)

## S4 method for signature 'samc,ANY,missing,missing,numeric'
visitation(samc, init, time)

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

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

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

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

## S4 method for signature 'samc,ANY,missing,missing,missing'
visitation(samc, init)

## S4 method for signature 'samc,ANY,missing,location,missing'
visitation(samc, init, dest)

Arguments

`samc`	A `samc-class` object created using the `samc` function.
`init`	Sets the initial state `\psi` of the transients states. Input must be able to pass the `check` function when compared against the `samc-class` object. Can only contain positive finite values.
`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.
`time`	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.

Details

\tilde{F}_{t} = (\sum_{n=0}^{t-1}{Q}^n)

visitation(samc, time)

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

The result is a vector \mathbf{v} where \mathbf{v}_j is the number of times that transient state \mathit{j} is visited after \mathit{t} time steps 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, time)

The result is a vector \mathbf{v} where \mathbf{v}_i is the number of times that transient state \mathit{j} is visited after \mathit{t} time steps 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, time)

The result is a numeric value that is the number of times transient state \mathit{j} is visited after \mathit{t} time steps if starting at transient state \mathit{i}.

\psi^T \tilde{F}_{t}

visitation(samc, init, time)

The result is a vector \mathbf{v} where \mathbf{v}_j is the number of times that transient state \mathit{j} is visited after \mathit{t} time steps before absorption 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.
visitation(samc, init, dest, time)

The result is a numeric value that is the number of times transient state \mathit{j} is visited after \mathit{t} time steps given an initial state \psi.

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}.

\psi^TF

visitation(samc, init)

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 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.
visitation(samc, init, dest)

The result is a numeric value that is the number of times transient state \mathit{j} is visited before absorption given an initial state \psi.

Value

See Details

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::example_split_corridor$res
abs_data <- samc::example_split_corridor$abs
init_data <- samc::example_split_corridor$init


# Make sure our data meets the basic input requirements of the package using
# the check() function.
check(res_data, abs_data)
check(res_data, init_data)

# Setup the details for a random-walk model
rw_model <- 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, model = rw_model)


# Convert the initial state data to probabilities
init_prob_data <- init_data / sum(init_data, na.rm = TRUE)


# Calculate short- and long-term metrics using the analytical functions
short_mort <- mortality(samc_obj, init_prob_data, time = 50)
short_dist <- distribution(samc_obj, origin = 3, time = 50)
long_disp <- dispersal(samc_obj, init_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)

samc documentation built on Oct. 31, 2024, 1:07 a.m.