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

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] TRUEcheck(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)
#>
#> 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)