Lookup table functions and helpers — lkup

These functions provide access to reference data like species, age classes, and more. Data are cached within the R session to minimize API calls.

Usage

lkup_species(species_name = NULL, species_id = NULL, enabled = TRUE)

lkup_species_id(species_name)

lkup_species_opts()

lkup_age(
  species_name = NULL,
  species_id = NULL,
  age_class = NULL,
  age_class_id = NULL
)

lkup_age_id(age_class, species_name = NULL, species_id = NULL)

lkup_age_opts(species_name = NULL, species_id = NULL)

lkup_gmu(
  gmu_name = NULL,
  gmu_id = NULL,
  species_name = NULL,
  species_id = NULL,
  dau_name = NULL,
  dau_id = NULL
)

lkup_gmu_id(gmu_name, species_name = NULL, species_id = NULL)

lkup_gmu_opts(
  species_name = NULL,
  species_id = NULL,
  dau_name = NULL,
  dau_id = NULL
)

lkup_dau_versions(species_name = NULL, species_id = NULL)

lkup_dau(
  dau_name = NULL,
  dau_id = NULL,
  species_name = NULL,
  species_id = NULL
)

lkup_dau_id(dau_name, species_name = NULL, species_id = NULL)

lkup_dau_opts(species_name = NULL, species_id = NULL)

lkup_aircraft(aircraft_name = NULL, aircraft_id = NULL)

lkup_aircraft_id(aircraft_name)

lkup_aircraft_opts()

lkup_survey_type(
  species_name = NULL,
  species_id = NULL,
  survey_type_name = NULL,
  survey_type_id = NULL
)

lkup_survey_type_id(survey_type_name, species_name = NULL, species_id = NULL)

lkup_survey_type_opts(species_name = NULL, species_id = NULL)

lkup_strata(
  strata_name = NULL,
  strata_id = NULL,
  survey_type_name = NULL,
  survey_type_id = NULL,
  species_name = NULL,
  species_id = NULL
)

lkup_strata_id(
  strata_name,
  species_name = NULL,
  species_id = NULL,
  survey_type_name = NULL,
  survey_type_id = NULL
)

lkup_strata_opts(
  species_name = NULL,
  species_id = NULL,
  survey_type_name = NULL,
  survey_type_id = NULL
)

lkup_model(model_name = NULL, model_id = NULL)

lkup_model_id(model_name)

lkup_model_opts()

lkup_ipm_param(
  species_name = NULL,
  species_id = NULL,
  param_name = NULL,
  param_id = NULL,
  target = NULL
)

lkup_ipm_param_id(param_name, species_name = NULL, species_id = NULL)

lkup_ipm_param_opts(species_name = NULL, species_id = NULL, target = NULL)

Arguments

species_name: character, filter to name of the species
species_id: integer, filter to a particular species by id
enabled: logical, when TRUE (default) filter to enabled species, see details
age_class: Character string matching the age_class column. If NULL, returns all age classes for the species.
age_class_id: Integer matching the id column. If NULL, returns all age classes, potentially filtered to the species.
gmu_name: character, the name of the management unit to filter to
gmu_id: integer, the id of the management unit to filter to
dau_name: character, the name of the analysis unit to filter to
dau_id: integer, the id of the analysis unit to filter to
aircraft_name: character, the name of the aircraft to filter to
aircraft_id: integer, the id of the aircraft to filter to
survey_type_name: character, the name of the survey type to filter to
survey_type_id: integer, the id of the survey type to filter to
strata_name: character, the name of the strata to filter to
strata_id: integer, the id of the strata to filter to
model_name: character, the name of the model to filter to
model_id: integer, the id of the model to filter to
param_name: character, the name of the IPM parameter to filter to
param_id: integer, the id of the IPM parameter to filter to
target: character, the name of the target of the IPM parameters to filter to.

Value

Functions come in three flavors:

Tibble functions (lkup_species, lkup_age, lkup_gmu, etc.) return a tibble with S3 class c("spdgt_lkup", "tbl_df", "tbl", "data.frame"). The spdgt_lkup class adds a contextual header when printed interactively. When no rows match the filter, a 0-row tibble with the same columns is returned (no error). See Returned columns below for column details.

_opts functions (lkup_species_opts, lkup_gmu_opts, etc.) return a named integer vector suitable for shiny::selectInput(). Names are display labels, values are integer IDs. The label column varies by function: lkup_species_opts() uses species_name as labels and species_id as values; all other _opts functions use name (or age_class) as labels and id as values. When no rows match, returns setNames(integer(), character()) with a warning.

_id functions (lkup_species_id, lkup_gmu_id, etc.) return an integer vector of matching IDs. Can be length > 1 if the name matches multiple records. Aborts with an error if the name cannot be resolved; never returns NULL.

Details

The results of calling the lookup function are stored in a cache for future use. In fact, unless the user needs these values "in hand" there is no reason to call this function. The lookup tables will be retrieved and stored on the user's behalf by any function that depends on these tables. So, in most cases the user can forget this function exists.

The lookup cache will persist for the duration of the session. If R is restarted the cache will be cleared. If values in the database are updated the user can call this function again to refresh the cache.

An enabled species is one for which we intend to model. This is a way to filter out species that are not of interest from a modeling perspective. Which species are enabled is currently controlled by the SPDGT team.

If the user requires spatial versions of the management units or additional information about analysis units then please see lkup_read_gmu_sf() and lkup_read_dau_sf().

When calling one of the name lookup functions users should be aware that there is no guarantee that the name is unique enough to only return one result.

Returned columns

lkup_species(): id, project_id, species_id, species_name, model_day, model_month, is_enabled

lkup_age(): id, project_id, species_id, age_class, age_num, age_min_months, age_max_months, is_first_reproduction, created_at, updated_at

lkup_gmu(): id, analysis_unit_id, region_id, project_id, species_id, name, abbreviation, number, sort_order

lkup_dau(): id, version_id, number, name, abbreviation, sort_order, species_id

lkup_dau_versions(): id, project_id, species_id, date, name, source, created_by

lkup_survey_type(): id, project_id, species_id, name, cutoff_day, cutoff_month, category

lkup_aircraft(): id, name

lkup_strata(): id, survey_type_id, parent_stratum_id, stratum_order, abbreviation, name, extrapolate, map_color, default_prop, can_sample

lkup_model(): id, type, name, approach, proc_suffix, definition, metadata, created_at, updated_at, covars, survey_type_ids

lkup_ipm_param(): id, parent_id, species_id, project_id, name, abbreviation, is_prior, target, has_se, has_lcl, has_ucl, min_mean, max_mean, validate_mean, min_lcl, max_lcl, validate_lcl, min_ucl, max_ucl, validate_ucl, created_at, updated_at

Examples

if (FALSE) { # \dontrun{
# Common workflow: Using a species name to get details and IDs
# First, view details about the species, pick a species in your project!
lkup_species(species_name = "Mule Deer")

# Get the species ID for use in other functions
lkup_species_id(species_name = "Mule Deer")

# Use species ID to get age classes
lkup_age(species_id = 1)

# Get specific age class ID for a species
lkup_age_id(species_id = 1, age_class = "Adult")

# View available management units for a species
lkup_gmu(species_name = "Elk")

# Get specific GMU ID using name - gmu_name is fake, change it
lkup_gmu_id(species_id = 2, gmu_name = "Goose 37")

# View data analysis units for a species
lkup_dau(species_id = 1)

# Get DAU ID using name - dau name is fake, change it
lkup_dau_id(species_id = 1, dau_name = "Sublette 104")

# Get choices for dropdown menus in shiny apps
lkup_species_opts()

lkup_age_opts(species_id = 1)

lkup_gmu_opts(species_id = 1)

lkup_dau_opts(species_id = 1)

lkup_survey_type("Mule Deer")
} # }