Skip to contents

Reads a bundle's pooling tracker (species_pooling.csv) and species groups (species_groups.csv) and returns, for each watershed group in aoi and each model species present there, the observation species whose records count as evidence for it. The tool knows nothing about any particular species: pooling Dolly Varden records into bull trout, or all salmon together, is a row in the tracker.

Usage

lnk_species_pooling(loaded, aoi, species, regions = NULL)

Arguments

loaded

Named list from lnk_load_overrides(). Uses wsg_species_presence (required: its species columns are also the set of known species codes), species_pooling and species_groups (both optional; without a tracker nothing is pooled).

aoi

Character vector of watershed group codes.

species

Character vector of model species codes.

regions

Data frame with watershed_group_code, region and subregion, or NULL (default) for the package's inst/extdata/wsg_regions.csv.

Value

A data frame, one row per WSG x model species x observation species: watershed_group_code, species_code, obs_species, scope_level (self for the species itself, else the winning row's level), scope, rule (the winning row's number in the tracker, NA for self) and obs_year_max (the winning row's year limit, NA for none; always NA for self). Consumers apply the year limit per record, and an undated record does not meet one. Codes are upper case.

Details

A tracker row is species_code (the model species or a group of them), species_obs (the observation species, a group, or a code records are filed under that is no species column, such as SST for summer-run steelhead), scope_level (province, region, subregion or wsg), scope (BC for province, else a name in inst/extdata/wsg_regions.csv or a WSG code) and pool (yes / no). So one table says both which species' records count as which and which alias codes count as a species: it is the record rule the pipeline, the presence check and the validator read (link#470). An optional obs_year_max limits a pooling row to records dated in or before that year, for evidence whose meaning changed over time (a name that was applied to another species until recording practice caught up). Empty means no limit. Other columns (confidence, rationale, source, verified, issue) are the record of why, and are not read here.

For each WSG, target and observation species pair, the applicable rows are resolved in order:

  1. the most specific scope wins (wsg over subregion over region over province);

  2. at equal scope, the row naming fewer groups wins (a species-to-species row beats one that names a group);

  3. rows still tied must agree on pool and obs_year_max, or the call errors.

Anything no row covers is not pooled. A species always counts as itself, and a model species yields rows only where wsg_species_presence marks it present.

Examples

cfg <- lnk_config("default")
loaded <- suppressWarnings(lnk_load_overrides(cfg))

# Which observation species count as each model species in three groups
# on different drainages?
p <- lnk_species_pooling(loaded, aoi = c("MORR", "ELKR", "COMX"),
                         species = c("BT", "CO"))
p
#>    watershed_group_code species_code obs_species scope_level
#> 1                  COMX           CO          CO        self
#> 2                  ELKR           BT          BT        self
#> 3                  ELKR           BT         ABT    province
#> 4                  ELKR           BT       BT/DV   subregion
#> 5                  ELKR           BT          DV   subregion
#> 6                  ELKR           BT       DV/BT   subregion
#> 7                  MORR           BT          BT        self
#> 8                  MORR           BT         ABT    province
#> 9                  MORR           BT       BT/DV   subregion
#> 10                 MORR           BT          DV   subregion
#> 11                 MORR           BT       DV/BT   subregion
#> 12                 MORR           CO          CO        self
#>                    scope rule obs_year_max
#> 1                   <NA>   NA           NA
#> 2                   <NA>   NA           NA
#> 3                     BC   13           NA
#> 4               Kootenay   17           NA
#> 5               Kootenay    5           NA
#> 6               Kootenay   22           NA
#> 7                   <NA>   NA           NA
#> 8                     BC   13           NA
#> 9  Skeena above Hazelton   18           NA
#> 10 Skeena above Hazelton    6           NA
#> 11 Skeena above Hazelton   23           NA
#> 12                  <NA>   NA           NA

# The pooled rows alone, with the tracker row that decided each one
p[p$scope_level != "self", ]
#>    watershed_group_code species_code obs_species scope_level
#> 3                  ELKR           BT         ABT    province
#> 4                  ELKR           BT       BT/DV   subregion
#> 5                  ELKR           BT          DV   subregion
#> 6                  ELKR           BT       DV/BT   subregion
#> 8                  MORR           BT         ABT    province
#> 9                  MORR           BT       BT/DV   subregion
#> 10                 MORR           BT          DV   subregion
#> 11                 MORR           BT       DV/BT   subregion
#>                    scope rule obs_year_max
#> 3                     BC   13           NA
#> 4               Kootenay   17           NA
#> 5               Kootenay    5           NA
#> 6               Kootenay   22           NA
#> 8                     BC   13           NA
#> 9  Skeena above Hazelton   18           NA
#> 10 Skeena above Hazelton    6           NA
#> 11 Skeena above Hazelton   23           NA