Skip to contents

Map sample_observations() over multiple species

Source: R/map_sample_observations.R
map_sample_observations.Rd

This function executes sample_observations() over multiple rows of a dataframe, representing different species, with potentially different function arguments over multiple columns.

Usage

map_sample_observations(df, nested = TRUE, arg_list = NA)

Arguments

df

A dataframe containing multiple rows, each representing a different species. The columns are function arguments with values used for mapping sample_observations() for each species. Columns not used by this function will be retained in the output.

nested

Logical. If TRUE (default), retains list-column containing sf objects calculated by sample_observations(). Otherwise, expands this list-column into rows and columns.

arg_list

A named list or NA. If NA (default), the function assumes column names in df are identical to argument names of sample_observations(). If column names differ, they must be specified as a named list where the names are the argument names of sample_observations(), and the associated values are the corresponding column names in df.

Value

In case of nested = TRUE, a dataframe identical to df, with an extra list-column called occurrences containing an sf object with POINT geometry for each row computed by sample_observations(). In case of nested = FALSE, this list-column is expanded into additional rows and columns.

See also

Other multispecies: generate_taxonomy(), map_add_coordinate_uncertainty(), map_filter_observations(), map_grid_designation(), map_simulate_occurrences()

Examples

# Load packages
library(sf)
library(dplyr)

# Create polygon
plgn <- st_polygon(list(cbind(c(5, 10, 8, 2, 3, 5), c(2, 1, 7, 9, 5, 2))))

## Example with simple column names
# Specify dataframe for 3 species with custom function arguments
species_dataset_df <- tibble(
  taxonID = c("species1", "species2", "species3"),
  species_range = rep(list(plgn), 3),
  initial_average_occurrences = c(50, 100, 200),
  n_time_points = rep(6, 3),
  temporal_function = c(simulate_random_walk, simulate_random_walk, NA),
  sd_step = c(1, 1, NA),
  spatial_pattern = "random",
  detection_probability = c(0.8, 0.9, 1),
  seed = 123)

# Simulate occurrences
sim_occ1 <- map_simulate_occurrences(df = species_dataset_df)
#> [1] [using unconditional Gaussian simulation]
#> [2] [using unconditional Gaussian simulation]
#> [3] [using unconditional Gaussian simulation]

# Sample observations
samp_obs_nested <- map_sample_observations(df = sim_occ1)
samp_obs_nested
#> # A tibble: 3 × 11
#>   taxonID  species_range initial_average_occur…¹ n_time_points temporal_function
#>   <chr>    <list>                          <dbl>         <dbl> <list>           
#> 1 species1 <XY>                               50             6 <fn>             
#> 2 species2 <XY>                              100             6 <fn>             
#> 3 species3 <XY>                              200             6 <lgl [1]>        
#> # ℹ abbreviated name: ¹​initial_average_occurrences
#> # ℹ 6 more variables: sd_step <dbl>, spatial_pattern <chr>,
#> #   detection_probability <dbl>, seed <dbl>, occurrences <list>,
#> #   observations_total <list>

## Example with deviating column names
# Specify dataframe for 3 species with custom function arguments
species_dataset_df2 <- species_dataset_df %>%
  rename(polygon = species_range,
         sd = sd_step,
         det_prob = detection_probability)

# Create named list for argument conversion
arg_conv_list <- list(
    species_range = "polygon",
    sd_step = "sd",
    detection_probability = "det_prob"
  )

# Simulate occurrences
sim_occ2 <- map_simulate_occurrences(
  df = species_dataset_df2,
  arg_list = arg_conv_list)
#> [1] [using unconditional Gaussian simulation]
#> [2] [using unconditional Gaussian simulation]
#> [3] [using unconditional Gaussian simulation]

# Sample observations
map_sample_observations(
  df = sim_occ2,
  arg_list = arg_conv_list)
#> # A tibble: 3 × 11
#>   taxonID  polygon initial_average_occur…¹ n_time_points temporal_function    sd
#>   <chr>    <list>                    <dbl>         <dbl> <list>            <dbl>
#> 1 species1 <XY>                         50             6 <fn>                  1
#> 2 species2 <XY>                        100             6 <fn>                  1
#> 3 species3 <XY>                        200             6 <lgl [1]>            NA
#> # ℹ abbreviated name: ¹​initial_average_occurrences
#> # ℹ 5 more variables: spatial_pattern <chr>, det_prob <dbl>, seed <dbl>,
#> #   occurrences <list>, observations_total <list>