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.

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

```
if (FALSE) { # \dontrun{
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
)
} # }
```