Assign count data to strata and filter by species of interest. Routes are
assigned to strata based on their geographic location and the stratification
specified by the user. Species are filtered by matching English, French or
Scientific names to those in the BBS species data (see search_species() for
a flexible search to identify correct species names).
Usage
stratify(
by,
species,
strata_custom = NULL,
combine_species_forms = TRUE,
release = 2022,
sample_data = FALSE,
return_omitted = FALSE,
quiet = FALSE,
lump_species_forms,
bbs_data
)Arguments
- by
Character. Stratification type. Either an established type, one of "prov_state", "bcr", "latlong", "bbs_cws", "bbs_usgs", or a custom name (see
strata_customfor details).- species
Character. Bird species of interest. Can be specified by English, French, or Scientific names, or AOU code. Use
search_species()for loose matching to find the exact name/code needed.- strata_custom
(
sf) Data Frame. Data frame of modified existing stratification, or asfspatial data frame with polygons defining the custom stratifications. See Details.- combine_species_forms
Logical. Whether to combine ambiguous species forms. Default
TRUE. See Details.- release
Numeric. Which yearly release to use, 2022 (including data through 2021 field season) or 2020 (including data through 2019). Default 2022.
- sample_data
Logical. Use sample data (just Pacific Wrens). Default
FALSE.- return_omitted
Logical. Whether or not to return a data frame of route-years which were omitted during stratification as they did not overlap with any stratum. For checking and troubleshooting. Default
FALSE.- quiet
Logical. Suppress progress messages? Default
FALSE.- lump_species_forms
Deprecated. Use
combine_species_formsinstead- bbs_data
Defunct.
Value
List of (meta) data.
meta_datameta data defining the analysismeta_stratacontains a data frame listing strata names and area for all strata relevant to the data (i.e. some may have been removed due to lack of count data). Contains at leaststrata_name(the label of the stratum), andarea_sq_km(area of the stratum).birds_stratacontains stratified count-level data filtered by speciesroutes_stratacontains stratified route-level data filtered by species
Details
To define a custom subset of an existing stratification, specify the
stratification in by (e.g., "bbs_cws") and then supply a subset of
bbs_strata[["bbc_cws"]] to strata_custom (see examples).
To define a completely new custom stratification, specify the name you
would like use in by (e.g., "east_west_divide") and then supply a spatial
data frame with polygons identifying the different strata to
strata_custom. Note that this data must have a column called
strata_name which names all the strata contained (see examples).
If combine_species_forms is TRUE (default), species with multiple forms
(e.g., "unid. Dusky Grouse / Sooty Grouse") are included in overall species
groupings (i.e., "unid." are combined with "Dusky Grouse" and "Sooty
Grouse" into "Blue Grouse (Dusky/Sooty)"). If the user wishes to keep the
forms separate, combine_species_forms can be set to FALSE. See the data
frame species_forms, for which species are set to be combined with which
other species.
See vignette("stratification", package = "bbsBayes") and the article
custom stratification
for more details.
Examples
# Sample Data - USGS BBS strata
s <- stratify(by = "bbs_usgs", sample_data = TRUE)
#> Using 'bbs_usgs' (standard) stratification
#> Using sample BBS data...
#> Using species Pacific Wren (sample data)
#> Stratifying data...
#> Renaming routes...
# Full data - species and stratification
# Use `search_species()` to get correct species name
# Stratify by CWS BBS strata
s <- stratify(by = "bbs_cws", species = "Common Loon")
#> Using 'bbs_cws' (standard) stratification
#> Loading BBS data...
#> Filtering to species Common Loon (70)
#> Stratifying data...
#> Combining BCR 7 and NS and PEI...
#> Renaming routes...
# Use use English, French, Scientific, or AOU codes for species names
s <- stratify(by = "bbs_cws", species = "Plongeon huard")
#> Using 'bbs_cws' (standard) stratification
#> Loading BBS data...
#> Filtering to species Common Loon (70)
#> Stratifying data...
#> Combining BCR 7 and NS and PEI...
#> Renaming routes...
s <- stratify(by = "bbs_cws", species = 70)
#> Using 'bbs_cws' (standard) stratification
#> Loading BBS data...
#> Filtering to species Common Loon (70)
#> Stratifying data...
#> Combining BCR 7 and NS and PEI...
#> Renaming routes...
s <- stratify(by = "bbs_cws", species = "Gavia immer")
#> Using 'bbs_cws' (standard) stratification
#> Loading BBS data...
#> Filtering to species Common Loon (70)
#> Stratifying data...
#> Combining BCR 7 and NS and PEI...
#> Renaming routes...
# Stratify by Bird Conservation Regions
s <- stratify(by = "bcr", species = "Great Horned Owl")
#> Using 'bcr' (standard) stratification
#> Loading BBS data...
#> Filtering to species Great Horned Owl (3750)
#> Stratifying data...
#> Renaming routes...
# Stratify by CWS BBS strata
s <- stratify(by = "bbs_cws", species = "Canada Jay")
#> Using 'bbs_cws' (standard) stratification
#> Loading BBS data...
#> Filtering to species Canada Jay (4840)
#> Stratifying data...
#> Combining BCR 7 and NS and PEI...
#> Renaming routes...
# Stratify by State/Province/Territory only
s <- stratify(by = "prov_state", species = "Common Loon")
#> Using 'prov_state' (standard) stratification
#> Loading BBS data...
#> Filtering to species Common Loon (70)
#> Stratifying data...
#> Renaming routes...
s <- stratify(by = "prov_state", species = "Plongeon huard")
#> Using 'prov_state' (standard) stratification
#> Loading BBS data...
#> Filtering to species Common Loon (70)
#> Stratifying data...
#> Renaming routes...
s <- stratify(by = "prov_state", species = 70)
#> Using 'prov_state' (standard) stratification
#> Loading BBS data...
#> Filtering to species Common Loon (70)
#> Stratifying data...
#> Renaming routes...
# Stratify by blocks of 1 degree of latitude X 1 degree of longitude
s <- stratify(by = "latlong", species = "Snowy Owl")
#> Using 'latlong' (standard) stratification
#> Loading BBS data...
#> Filtering to species Snowy Owl (3760)
#> Stratifying data...
#> Renaming routes...
#> Omitting 80/119,567 route-years that do not match a stratum.
#> To see omitted routes use `return_omitted = TRUE` (see ?stratify)
# Check routes omitted by stratification
s <- stratify(by = "latlong", species = "Snowy Owl", return_omitted = TRUE)
#> Using 'latlong' (standard) stratification
#> Loading BBS data...
#> Filtering to species Snowy Owl (3760)
#> Stratifying data...
#> Renaming routes...
#> Omitting 80/119,567 route-years that do not match a stratum.
#> Returning omitted routes.
s[["routes_omitted"]]
#> # A tibble: 80 × 11
#> year strata_name country state route route…¹ latit…² longi…³ bcr obs_n
#> <dbl> <chr> <chr> <chr> <chr> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 1988 NA US CALIFOR… 14-1… SANTA … 34.0 -120. 32 1.06e6
#> 2 1987 NA US FLORIDA 25-83 KEY WE… 24.7 -81.2 31 1.11e6
#> 3 1999 NA US FLORIDA 25-1… SUGARL… 24.7 -81.2 31 1.02e6
#> 4 2002 NA US FLORIDA 25-1… SUGARL… 24.7 -81.2 31 1.22e6
#> 5 2003 NA US FLORIDA 25-1… SUGARL… 24.7 -81.2 31 1.22e6
#> 6 2004 NA US FLORIDA 25-1… SUGARL… 24.7 -81.2 31 1.08e6
#> 7 2005 NA US FLORIDA 25-2… SUGARL… 24.6 -81.6 31 1.08e6
#> 8 2006 NA US FLORIDA 25-2… SUGARL… 24.6 -81.6 31 1.08e6
#> 9 2007 NA US FLORIDA 25-2… SUGARL… 24.6 -81.6 31 1.08e6
#> 10 2008 NA US FLORIDA 25-2… SUGARL… 24.6 -81.6 31 1.09e6
#> # … with 70 more rows, 1 more variable: total_spp <dbl>, and abbreviated
#> # variable names ¹route_name, ²latitude, ³longitude
# Use combined or non-combined species forms
search_species("Sooty grouse")
#> # A tibble: 2 × 9
#> aou english french spanish order family genus species unid_…¹
#> <dbl> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <lgl>
#> 1 2971 Sooty Grouse Tétra… Dendra… Gall… Phasi… Dend… fuligi… TRUE
#> 2 2973 Blue Grouse (Dusky/So… Tétra… Dendra… Gall… Phasi… Dend… obscur… TRUE
#> # … with abbreviated variable name ¹unid_combined
s <- stratify(by = "bbs_usgs", species = "Blue Grouse (Dusky/Sooty)")
#> Using 'bbs_usgs' (standard) stratification
#> Loading BBS data...
#> Filtering to species Blue Grouse (Dusky/Sooty) (2973)
#> Stratifying data...
#> Renaming routes...
nrow(s$birds_strata) # Contains all Dusky, Sooty and unidentified
#> [1] 1501
search_species("Sooty grouse", combine_species_forms = FALSE)
#> # A tibble: 2 × 9
#> aou english french spanish order family genus species unid_…¹
#> <dbl> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <lgl>
#> 1 2971 Sooty Grouse Tétra… Dendra… Gall… Phasi… Dend… fuligi… FALSE
#> 2 2973 unid. Dusky Grouse / … unid … Dendra… Gall… Phasi… Dend… obscur… FALSE
#> # … with abbreviated variable name ¹unid_combined
s <- stratify(by = "bbs_usgs", species = "unid. Dusky Grouse / Sooty Grouse",
combine_species_forms = FALSE)
#> Using 'bbs_usgs' (standard) stratification
#> Loading BBS data...
#> Filtering to species unid. Dusky Grouse / Sooty Grouse (2973)
#> Stratifying data...
#> Renaming routes...
nrow(s$birds_strata) # Contains *only* unidentified
#> [1] 90
# Stratify by a subset of an existing stratification
library(dplyr)
my_cws <- filter(bbs_strata[["bbs_cws"]], country_code == "CA")
s <- stratify(by = "bbs_cws", strata_custom = my_cws, species = "Snowy Owl")
#> Using 'bbs_cws' (subset) stratification
#> Loading BBS data...
#> Filtering to species Snowy Owl (3760)
#> Stratifying data...
#> Combining BCR 7 and NS and PEI...
#> Renaming routes...
#> Omitting 101,474/119,567 route-years that do not match a stratum.
#> To see omitted routes use `return_omitted = TRUE` (see ?stratify)
my_bcr <- filter(bbs_strata[["bcr"]], strata_name == "BCR8")
s <- stratify(by = "bcr", strata_custom = my_bcr,
species = "Yellow-rumped Warbler (all forms)")
#> Using 'bcr' (subset) stratification
#> Loading BBS data...
#> Filtering to species Yellow-rumped Warbler (all forms) (6556)
#> Stratifying data...
#> Renaming routes...
#> Omitting 118,210/119,567 route-years that do not match a stratum.
#> To see omitted routes use `return_omitted = TRUE` (see ?stratify)
# Stratify by Custom stratification, using sf map object
# e.g. with WBPHS stratum boundaries 2019
# available: https://ecos.fws.gov/ServCat/Reference/Profile/142628
if (FALSE) {
map <- sf::read_sf("../WBPHS_Stratum_Boundaries_2019") %>%
rename(strata_name = STRAT) # stratify expects this column
s <- stratify(by = "WBPHS_2019", strata_map = map)
}