Skip to contents

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

Usage

map_grid_designation(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 grid_designation() 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 grid_designation(). 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 grid_designation(). If column names differ, they must to be specified as a named list where the names are the argument names of grid_designation(), and the associated values are the corresponding column names in df.

Value

In case of nested = TRUE, a dataframe identical to df, but each sf object with POINT geometry in the list-column observations now has an additional column coordinateUncertaintyInMeters added by grid_designation(). In case of nested = FALSE, this list-column is expanded into additional rows and columns.

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

# Create grid
cube_grid <- st_make_grid(
    st_buffer(plgn, 25),
    n = c(20, 20),
    square = TRUE) %>%
  st_sf()

## 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),
  invert = FALSE,
  coords_uncertainty_meters = c(25, 30, 50),
  grid = rep(list(cube_grid), 3),
  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_obs1 <- map_sample_observations(df = sim_occ1)

# Filter observations
filter_obs1 <- map_filter_observations(df = samp_obs1)

# Add coordinate uncertainty
obs_uncertainty1 <- map_add_coordinate_uncertainty(df = filter_obs1)

# Grid designation
occ_cube_nested <- map_grid_designation(df = obs_uncertainty1)
occ_cube_nested
#> # A tibble: 3 × 16
#>   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
#> # ℹ 11 more variables: sd_step <dbl>, spatial_pattern <chr>,
#> #   detection_probability <dbl>, invert <lgl>, coords_uncertainty_meters <dbl>,
#> #   grid <list>, seed <dbl>, occurrences <list>, observations_total <list>,
#> #   observations <list>, occurrence_cube_df <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,
         inv = invert,
         coord_uncertainty = coords_uncertainty_meters,
         raster = grid)

# Create named list for argument conversion
arg_conv_list <- list(
    species_range = "polygon",
    sd_step = "sd",
    detection_probability = "det_prob",
    invert = "inv",
    coords_uncertainty_meters = "coord_uncertainty",
    grid = "raster"
  )

# 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
samp_obs2 <- map_sample_observations(
  df = sim_occ2,
  arg_list = arg_conv_list)

# Filter observations
filter_obs2 <- map_filter_observations(
  df = samp_obs2,
  arg_list = arg_conv_list)

# Add coordinate uncertainty
obs_uncertainty2 <- map_add_coordinate_uncertainty(
  df = filter_obs2,
  arg_list = arg_conv_list)

# Grid designation
map_grid_designation(
  df = obs_uncertainty2,
  arg_list = arg_conv_list)
#> # A tibble: 3 × 16
#>   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
#> # ℹ 10 more variables: spatial_pattern <chr>, det_prob <dbl>, inv <lgl>,
#> #   coord_uncertainty <dbl>, raster <list>, seed <dbl>, occurrences <list>,
#> #   observations_total <list>, observations <list>, occurrence_cube_df <list>