get_observations: Observation Process

In rangr: Mechanistic Simulation of Species Range Dynamics

Observation Process

Description

This function simulates an observation process. It accepts the sim_results object, which is generated by the sim function, and applies the virtual ecologist approach on the N_map component of the object. The function returns a data.frame with the 'observed' abundances.

Usage

get_observations(
  sim_data,
  sim_results,
  type = c("random_one_layer", "random_all_layers", "from_data", "monitoring_based"),
  obs_error = c("rlnorm", "rbinom"),
  obs_error_param = NULL,
  ...
)

Arguments

sim_data	sim_data object from initialise containing simulation parameters
sim_results	sim_results object; returned by sim function
type	character vector of length 1; describes the sampling type (case-sensitive): "random_one_layer" - random selection of cells for which abundances are sampled; the same set of selected cells is used across all time steps. "random_all_layers" - random selection of cells for which abundances are sampled; a new set of cells is selected for each time step. "from_data" - user-defined selection of cells for which abundances are sampled; the user is required to provide a data.frame containing three columns: "x", "y" and "time_step". "monitoring_based" - user-defined selection of cells for which abundances are sampled; the user is required to provide a matrix object with two columns: "x" and "y"; the abundance from given cell is sampled by different virtual observers in different time steps; a geometric distribution (rgeom) is employed to define whether a survey will be conducted by the same observer for several years or not conducted at all.
obs_error	character vector of length 1; type of the distribution that defines the observation process: "rlnorm" (the log normal distribution) or "rbinom" (the binomial distribution)
obs_error_param	numeric vector of length 1; standard deviation (on a log scale) of the random noise in observation process generated from the log-normal distribution (rlnorm) or probability of detection (success) when the binomial distribution ("rbinom") is used.
...	other necessary internal parameters: prop numeric vector of length 1; proportion of cells to be sampled (default prop = 0.1); used when ⁠type = "random_one_layer" or "random_all_layers"⁠, points data.frame or matrix with 3 numeric columns named "x", "y", and "time_step" containing coordinates and time steps from which observations should be obtained; used when type = "from_data", cells_coords data.frame or matrix with 2 columns named "x" and "y"; survey plots coordinates; used when type = "monitoring_based" prob numeric vector of length 1; a parameter defining the shape of rgeom distribution; defines whether an observation will be made by the same observer for several years, and whether it will not be made at all (default prob = 0.3); used when type = "monitoring_based" progress_bar logical vector of length 1; determines if a progress bar for observation process should be displayed (default progress_bar = FALSE); used when type = "monitoring_based"

Value

data.frame object with geographic coordinates, time steps, estimated abundance, observation error (if obs_error_param is provided), and observer identifiers (if type = "monitoring_based"). If type = "from_data", returned object is sorted in the same order as the input points.

Examples

library(terra)
n1_small <- rast(system.file("input_maps/n1_small.tif", package = "rangr"))
K_small <- rast(system.file("input_maps/K_small.tif", package = "rangr"))

# prepare data
sim_data <- initialise(
  n1_map = n1_small,
  K_map = K_small,
  r = log(2),
  rate = 1 / 1e3
)

sim_1 <- sim(obj = sim_data, time = 110, burn = 10)

# 1. random_one_layer
sample1 <- get_observations(
  sim_data,
  sim_1,
  type = "random_one_layer",
  prop = 0.1
)

# 2. random_all_layers
sample2 <- get_observations(
  sim_data,
  sim_1,
  type = "random_all_layers",
  prop = 0.15
)

# 3. from_data
sample3 <- get_observations(
  sim_data,
  sim_1,
  type = "from_data",
  points = observations_points
)

# 4. monitoring_based
# define observations sites
all_points <- xyFromCell(unwrap(sim_data$id), cells(unwrap(sim_data$K_map)))
sample_idx <- sample(1:nrow(all_points), size = 20)
sample_points <- all_points[sample_idx, ]

sample4 <- get_observations(
  sim_data,
  sim_1,
  type = "monitoring_based",
  cells_coords = sample_points,
  prob = 0.3,
  progress_bar = TRUE
)

# 5. noise "rlnorm"
sample5 <- get_observations(sim_data,
  sim_1,
  type = "random_one_layer",
  obs_error = "rlnorm",
  obs_error_param = log(1.2)
)

# 6. noise "rbinom"
sample6 <- get_observations(sim_data,
  sim_1,
  type = "random_one_layer",
  obs_error = "rbinom",
  obs_error_param = 0.8
)

rangr documentation built on April 12, 2025, 1:40 a.m.