Skip to contents

Observation Process

Source: R/get_observations.R
get_observations.Rd

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

# \donttest{

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
)
#> 
  |                                                                            
  |                                                                      |   0%
  |                                                                            
  |====                                                                  |   5%
  |                                                                            
  |=======                                                               |  11%
  |                                                                            
  |===========                                                           |  16%
  |                                                                            
  |===============                                                       |  21%
  |                                                                            
  |==================                                                    |  26%
  |                                                                            
  |======================                                                |  32%
  |                                                                            
  |==========================                                            |  37%
  |                                                                            
  |=============================                                         |  42%
  |                                                                            
  |=================================                                     |  47%
  |                                                                            
  |=====================================                                 |  53%
  |                                                                            
  |=========================================                             |  58%
  |                                                                            
  |============================================                          |  63%
  |                                                                            
  |================================================                      |  68%
  |                                                                            
  |====================================================                  |  74%
  |                                                                            
  |=======================================================               |  79%
  |                                                                            
  |===========================================================           |  84%
  |                                                                            
  |===============================================================       |  89%
  |                                                                            
  |==================================================================    |  95%
  |                                                                            
  |======================================================================| 100%

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

# }