Skip to contents

Map simulate_occurrences() over multiple species

Source: R/map_simulate_occurrences.R
map_simulate_occurrences.Rd

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

Usage

map_simulate_occurrences(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 simulate_occurrences() 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 simulate_occurrences(). 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 simulate_occurrences() and the function specified in its temporal_function argument. If column names differ, they must be specified as a named list where the names are the argument names of simulate_occurrences() or the function specified in its temporal_function argument, 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 simulate_occurrences(). 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_sample_observations()

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",
  seed = 123)

# Simulate occurrences
sim_occ_nested <- map_simulate_occurrences(df = species_dataset_df)
#> [1] [using unconditional Gaussian simulation]
#> [2] [using unconditional Gaussian simulation]
#> [3] [using unconditional Gaussian simulation]
sim_occ_nested
#> # A tibble: 3 × 9
#>   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
#> # ℹ 4 more variables: sd_step <dbl>, spatial_pattern <chr>, seed <dbl>,
#> #   occurrences <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)

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

# Simulate occurrences
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]
#> # A tibble: 3 × 9
#>   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
#> # ℹ 3 more variables: spatial_pattern <chr>, seed <dbl>, occurrences <list>