eBird Status and Trends

https://ebird.github.io/ebirdst/
Admin
R package providing tools for downloading, loading, and analyzing eBird machine-learning bird...
Tokens:55,677
Snippets:544
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Download Example and Species Data

Source: https://ebird.github.io/ebirdst/reference/ebirdst_download_status.html

Demonstrates downloading the example dataset for 'yebsap-example' and the full data package for 'woothr'. The example data is smaller and accessible without an access key.

```R
if (FALSE) { # \dontrun{
# download the example data
ebirdst_download_status("yebsap-example")

# download the data package for wood thrush
ebirdst_download_status("woothr")

```

--------------------------------

### Load Example Range Data

Source: https://ebird.github.io/ebirdst/reference/load_ranges.html

Demonstrates loading smoothed range polygons for the example dataset. Note that only 27km resolution data is provided for the example. Ensure example data is downloaded first.

```R
if (FALSE) { # \dontrun{
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example")

# load smoothed ranges
# note that only 27 km data are provided for the example data
ranges <- load_ranges("yebsap-example", resolution = "27km")
} # } 
```

--------------------------------

### Download Example Data for Loading

Source: https://ebird.github.io/ebirdst/reference/load_raster.html

Downloads the example dataset required for testing the load_raster function. This should be run before attempting to load the example data.

```r
if (FALSE) { # \dontrun{
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example")

```

--------------------------------

### Example Download URL

Source: https://ebird.github.io/ebirdst/articles/api.html

This is an example of a complete download URL for a specific file, assuming a known object path and access key.

```text
https://st-download.ebird.org/v1/fetch?objKey=2023/woothr/seasonal/woothr_abundance_seasonal_mean_3km_2023.tif&key=XXXXXXXX
```

--------------------------------

### Example: Load Full Annual Cycle Map Parameters

Source: https://ebird.github.io/ebirdst/reference/load_fac_map_parameters.html

Demonstrates how to download example data and then load the full annual cycle map parameters for a species. Ensure example data is downloaded before calling the function.

```R
if (FALSE) { # \dontrun{
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example")

# load configuration parameters
load_fac_map_parameters(path)
} # } 
```

--------------------------------

### Example: Rasterize Percent Per Year Trend

Source: https://ebird.github.io/ebirdst/reference/rasterize_trends.html

Demonstrates how to download example trends data, load it, and then rasterize the 'abd_ppy' layer. This example requires prior download of example data.

```R
# download example trends data if it hasn't already been downloaded
ebirdst_download_trends("yebsap-example")

# load trends
trends <- load_trends("yebsap-example")

# rasterize percent per year trend
rasterize_trends(trends, "abd_ppy")
```

--------------------------------

### Load Configuration Parameters

Source: https://ebird.github.io/ebirdst/reference/load_config.html

Loads the configuration parameters for a specified species. Ensure example data is downloaded first if using the example dataset.

```r
if (FALSE) { # \dontrun{
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example")

# load configuration parameters
p <- load_config("yebsap-example")
} # }
```

--------------------------------

### Review and Confirm Deletion of Example Data

Source: https://ebird.github.io/ebirdst/reference/ebirdst_delete.html

Use this example to review and confirm the deletion of example data. The function will prompt for confirmation before proceeding.

```R
if (FALSE) { # \dontrun{
# review and confirm deletion of example data
ebirdst_delete(species = "yebsap-example")

# delete all data for a given version year without prompting
ebirdst_delete(year = 2021, force = TRUE)

# delete a specific species and year
ebirdst_delete(species = "Yellow-bellied Sapsucker", year = 2022,
               force = TRUE)
} # }
```

--------------------------------

### Example Usage of get_species_path

Source: https://ebird.github.io/ebirdst/reference/get_species_path.html

Demonstrates how to use `get_species_path` to obtain the data package path for a species. It shows examples using a special example identifier, common name, scientific name, and species code.

```R
if (FALSE) { # \dontrun{
# get the path
path <- get_species_path("yebsap-example")

# get the path to the full data package for yellow-bellied sapsucker
# common name, scientific name, or species code can be used
path <- get_species_path("Yellow-bellied Sapsucker")
path <- get_species_path("Sphyrapicus varius")
path <- get_species_path("yebsap")
} # }
```

--------------------------------

### Example: Load Single Week of Site Selection Probability

Source: https://ebird.github.io/ebirdst/reference/load_data_coverage.html

Demonstrates loading a single week of site selection probability data. Requires prior download of example data.

```R
# download example data if hasn't already been downloaded
ebirdst_download_data_coverage()

# load a single week of site selection probability data
load_data_coverage("selection-probability", weeks = "01-04")
```

--------------------------------

### Download and Load eBird Status Data

Source: https://ebird.github.io/ebirdst/index.html

Demonstrates how to download example data for a specific species and load the relative abundance raster stack. Ensure the ebirdst package is installed and loaded.

```r
library(fields)
library(rnaturalearth)
library(sf)
library(terra)
library(ebirdst)

# download example data, yellow-bellied sapsucker in michigan
ebirdst_download_status(species = "yebsap-example")

# load relative abundance raster stack with 52 layers, one for each week
abd <- load_raster("yebsap-example", resolution = "27km")
```

--------------------------------

### Download Example Data

Source: https://ebird.github.io/ebirdst/reference/ebirdst_download_trends.html

Use this snippet to download a small, example dataset for Yellow-bellied Sapsucker, which does not require an access key. This is useful for testing and quick processing.

```R
ebirdst_download_trends("yebsap-example")
```

--------------------------------

### Example: Load All Weeks of Spatial Coverage

Source: https://ebird.github.io/ebirdst/reference/load_data_coverage.html

Demonstrates loading multiple weeks of spatial coverage data. Requires prior download of example data.

```R
# load all weeks of spatial coverage data
load_data_coverage("spatial-coverage", weeks = c("01-04", "01-11"))
```

--------------------------------

### Install ebirdst R Package

Source: https://ebird.github.io/ebirdst/index.html

Installs the 'ebirdst' R package from GitHub. Ensure the 'remotes' package is installed first.

```r
if (!requireNamespace("remotes", quietly = TRUE)) {
  install.packages("remotes")
}
remotes::install_github("ebird/ebirdst")
```

--------------------------------

### GNU GPL Notice for Interactive Program Start

Source: https://ebird.github.io/ebirdst/LICENSE.html

This notice should be displayed by a program when it starts in interactive mode, informing users about its free software status and warranty limitations.

```text
<program>  Copyright (C) <year>  <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type 'show c' for details.
```

--------------------------------

### Download eBird Status Data for Example Species

Source: https://ebird.github.io/ebirdst/articles/status.html

Downloads a simplified example dataset for Yellow-bellied Sapsucker in Michigan. Set `download_all = TRUE` to retrieve all available data products. Data for other species requires an access key.

```R
library(dplyr)
library(sf)
library(terra)
library(ebirdst)

# download a simplified example dataset for Yellow-bellied Sapsucker in Michigan
ebirdst_download_status(species = "yebsap-example", download_all = TRUE)
```

--------------------------------

### List Available PI Predictors and Load Top Predictor Raster

Source: https://ebird.github.io/ebirdst/reference/load_pi.html

This example demonstrates how to identify the top predictor for a species using `list_available_pis` and then load the corresponding predictor importance raster for the occurrence model using `load_pi`. Ensure example data is downloaded first.

```r
if (FALSE) { # \dontrun{
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example", download_pis = TRUE)

# identify the top predictor
top_preds <- list_available_pis("yebsap-example")
print(top_preds[1, ])

# load predictor importance raster of top predictor for occurrence
load_pi("yebsap-example", top_preds$predictor[1])
} # }
```

--------------------------------

### Load PPM Raster Data

Source: https://ebird.github.io/ebirdst/reference/load_ppm.html

Demonstrates how to download example data and load a specific PPM raster (binary_pr_auc) using the `load_ppm` function. This is useful for analyzing model performance metrics.

```r
if (FALSE) { # \dontrun{
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example", download_ppms = TRUE)

# load area under the precision-recall curve PPM raster
load_ppm("yebsap-example", ppm = "binary_pr_auc")
} # }
```

--------------------------------

### Download and Load PPM Data

Source: https://ebird.github.io/ebirdst/articles/applications.html

Downloads PPM data for a species and loads a specific model. Ensure the 'ebirdst' package is installed and the species code is correct.

```R
ebirdst_download_status("horlar", download_ppms = TRUE)
bernoulli_dev <- load_ppm("horlar", ppm = "occ_bernoulli_dev")
print(bernoulli_dev)
```

--------------------------------

### Convert PPY Trend to Cumulative Trend

Source: https://ebird.github.io/ebirdst/reference/convert_ppy_to_cumulative.html

This example demonstrates how to use the `convert_ppy_to_cumulative` function to convert a randomly generated percent per year trend into a cumulative trend over 5 years. It then displays both the original and converted trends side-by-side.

```r
ppy_trend <- runif(100, min = -100, 100)
cumulative_trend <- convert_ppy_to_cumulative(ppy_trend, n_years = 5)
cbind(ppy_trend, cumulative_trend)
```

--------------------------------

### ebirdst_download_trends

Source: https://ebird.github.io/ebirdst/reference/ebirdst_download_trends.html

Downloads eBird Trends Data Products for specified species. An access key is required for full datasets, but an example dataset is available without one. Users can specify species by name or code and choose a download directory.

```APIDOC
## ebirdst_download_trends

### Description
Downloads eBird Trends Data Products for a set of species, or for an example species. Downloading Status and Trends data requires an access key; consult `set_ebirdst_access_key()` for instructions on how to obtain and store this key. The example data consist of the results for Yellow-bellied Sapsucker subset to Michigan and are much smaller than the full dataset, making these data quicker to download and process. The example data are accessible without an access key.

### Function Signature
```R
ebirdst_download_trends(
  species,
  path = ebirdst_data_dir(),
  force = FALSE,
  show_progress = TRUE
)
```

### Arguments

* **species** (character) - Required. One or more species given as scientific names, common names or six-letter species codes (e.g. "woothr"). The full list of valid species can be viewed in the `ebirdst_runs` data frame included in this package; species with trends estimates are indicated by the `has_trends` column. To access the example dataset, use "yebsap-example".
* **path** (character) - Optional. Directory to download the data to. All downloaded files will be placed in a sub-directory of this directory named for the data version year, e.g. "2020" for the 2020 Status Data Products. Each species' data package will then appear in a directory named with the eBird species code. Defaults to a persistent data directory, which can be found by calling `ebirdst_data_dir()`.
* **force** (logical) - Optional. If the data have already been downloaded, should a fresh copy be downloaded anyway.
* **show_progress** (logical) - Optional. Whether to print download progress information.

### Value
Character vector of paths to the folders containing the downloaded data packages for the given species. The trends data will be in the `trends/` subdirectory.

### Examples
```R
# download the example data
ebirdst_download_trends("yebsap-example")

# download the data package for wood thrush
ebirdst_download_trends("woothr")

# multiple species can be downloaded at once
ebirdst_download_trends(c("Sage Thrasher", "Abert's Towhee"))
```
```

--------------------------------

### Inventory Downloaded eBird Data

Source: https://ebird.github.io/ebirdst/articles/status.html

Use `ebirdst_data_inventory()` to get a summary of all data currently downloaded. This helps in understanding disk usage and identifying data for specific species and version years.

```R
ebirdst_data_inventory()
#> eBird Status and Trends data: 51 species, 61 packages (6.1 GB)
#> 
#> 2022 Trends Data Products (53.1 MB)
#>   Abert's Towhee (abetow): 3 files, 364.9 KB
#>   Brewer's Sparrow (brespa): 3 files, 4.0 MB
#>   Brown Pelican (brnpel): 3 files, 1.7 MB
#>   Black-throated Green Warbler (btnwar): 3 files, 7.1 MB
#>   Burrowing Owl (burowl): 3 files, 4.8 MB
#>   Grasshopper Sparrow (graspa): 3 files, 7.3 MB
#>   Limpkin (limpki): 3 files, 1.1 MB
#>   Marsh Wren (marwre): 3 files, 5.9 MB
#>   Prairie Warbler (prawar): 3 files, 3.3 MB
#>   Sagebrush Sparrow (sagspa1): 3 files, 2.5 MB
#>   Sage Thrasher (sagthr): 3 files, 2.7 MB
#>   Seaside Sparrow (seaspa): 3 files, 215.5 KB
#>   American Coot (y00475): 3 files, 12.2 MB
#> 
#> 2023 Status Data Products (6.0 GB)
#>   Abert's Towhee (abetow): 2 files, 2.4 MB
#>   Puerto Rican Mango (antman3): 4 files, 51.9 MB
#>   Asian House-Martin (ashmar1): 28 files, 233.7 MB
#>   Baird's Sparrow (baispa): 6 files, 61.5 MB
#>   Bank Swallow (banswa): 2 files, 19.4 MB
#>   Barn Swallow (barswa): 27 files, 1.2 GB
#>   Black-bellied Plover (bkbplo): 3 files, 9.3 MB
#>   Bobolink (boboli): 6 files, 103.5 MB
#>   Brown-headed Thrush (brhthr1): 47 files, 105.2 MB
#>   Brown Pelican (brnpel): 4 files, 68.7 MB
#>   Black-throated Green Warbler (btnwar): 4 files, 121.2 MB
#>   Burrowing Owl (burowl): 4 files, 415.9 MB
#>   Cerulean Warbler (cerwar): 3 files, 583.3 KB
#>   Chestnut-collared Longspur (chclon): 6 files, 86.0 MB
#>   Colima Warbler (colwar): 10 files, 4.0 MB
#>   Data Coverage (data_coverage): 3 files, 91.9 MB
#>   Golden Eagle (goleag): 28 files, 881.9 MB
#>   Grasshopper Sparrow (graspa): 4 files, 139.8 MB
#>   Horned Lark (horlar): 47 files, 741.7 MB
#>   Kentucky Warbler (kenwar): 5 files, 31.7 MB
#>   Limpkin (limpki): 4 files, 181.6 MB
#>   Little Ringed Plover (lirplo): 3 files, 25.6 MB
#>   Long-toed Stint (lotsti): 3 files, 4.9 MB
#>   Marsh Wren (marwre): 4 files, 85.5 MB
#>   Pectoral Sandpiper (pecsan): 2 files, 5.8 MB
#>   Pinyon Jay (pinjay): 2 files, 828.2 KB
#>   Prairie Warbler (prawar): 4 files, 87.1 MB
#>   Puerto Rican Owl (prsowl): 4 files, 51.9 MB
#>   Red Knot (redkno): 3 files, 4.2 MB
#>   Red-necked Stint (rensti): 3 files, 4.7 MB
#>   Rock Pigeon (rocpig): 7 files, 24.0 MB
#>   Ruby-throated Hummingbird (rthhum): 8 files, 81.6 MB
#>   Ruddy Turnstone (rudtur): 3 files, 8.0 MB
#>   Rufous Hummingbird (rufhum): 5 files, 27.3 MB
#>   Sandhill Crane (sancra): 4 files, 177.5 MB
#>   Seaside Sparrow (seaspa): 4 files, 53.0 MB
#>   Sprague's Pipit (sprpip): 6 files, 73.7 MB
#>   Surf Scoter (sursco): 2 files, 2.4 MB
#>   Taiwan Barwing (taibar1): 3 files, 837.4 KB
#>   Tree Swallow (treswa): 2 files, 7.7 MB
#>   Upland Sandpiper (uplsan): 6 files, 138.5 MB
#>   Western Meadowlark (wesmea): 8 files, 225.4 MB
#>   Western Tanager (westan): 5 files, 48.5 MB
#>   White-cheeked Pintail (whcpin): 4 files, 85.1 MB
#>   Whimbrel (whimbr): 4 files, 122.0 MB
#>   American Coot (y00475): 4 files, 85.6 MB
#>   Yellow-breasted Crake (yebcra1): 4 files, 61.0 MB
#>   Yellow-bellied Sapsucker (yebsap-example): 52 files, 9.9 MB
```

--------------------------------

### load_fac_map_parameters

Source: https://ebird.github.io/ebirdst/reference/load_fac_map_parameters.html

Gets the map parameters used on the eBird Status and Trends website to optimally display the full annual cycle data. This includes bins for the abundance data, a projection, and an extent to map. The extent is the spatial extent of non-zero data across the full annual cycle and the projection is optimized for this extent.

```APIDOC
## load_fac_map_parameters

### Description
Gets the map parameters used on the eBird Status and Trends website to optimally display the full annual cycle data. This includes bins for the abundance data, a projection, and an extent to map. The extent is the spatial extent of non-zero data across the full annual cycle and the projection is optimized for this extent.

### Usage
```R
load_fac_map_parameters(species, path = ebirdst_data_dir())
```

### Arguments

* **species** (character) - Required - The species to load data for, given as a scientific name, common name or six-letter species code (e.g. "woothr"). The full list of valid species is in the ebirdst_runs data frame included in this package. To download the example dataset, use "yebsap-example".
* **path** (character) - Optional - Directory to download the data to. All downloaded files will be placed in a sub-directory of this directory named for the data version year, e.g. "2020" for the 2020 Status Data Products. Each species' data package will then appear in a directory named with the eBird species code. Defaults to a persistent data directory, which can be found by calling `ebirdst_data_dir()`.

### Value
A list containing elements:
* `custom_projection`: a custom projection optimized for the given species' full annual cycle
* `fa_extent`: a SpatExtent object storing the spatial extent of non-zero data for the given species in the custom projection
* `res`: a numeric vector with 2 elements giving the target resolution of raster in the custom projection
* `fa_extent_projected`: the extent in projected (Equal Earth) coordinates
* `weekly_bins`/`weekly_labels`: weekly abundance bins and labels for the full annual cycle
* `seasonal_bins`/`seasonal_labels`: seasonal abundance bins and labels for the full annual cycle

### Examples
```R
if (FALSE) { # \dontrun{
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example")

# load configuration parameters
load_fac_map_parameters(path)
} # }
```
```

--------------------------------

### Load Regional Summary Statistics

Source: https://ebird.github.io/ebirdst/reference/load_regional_stats.html

Loads regional summary statistics for a specified species. Requires downloading example data first if using the example species code.

```R
if (FALSE) { # \dontrun{
# download example data if hasn't already been downloaded
ebirdst_download_status("yebsap-example")

# load configuration parameters
regional <- load_regional_stats("yebsap-example")
} # } 
```

--------------------------------

### Filter Downloads with Pattern and Dry Run

Source: https://ebird.github.io/ebirdst/reference/ebirdst_download_status.html

Shows how to use the 'pattern' argument to filter downloaded files and 'dry_run' to preview which files would be downloaded. This is useful for selecting specific data resolutions or types.

```R
# use pattern to only download low resolution (27 km) geotiff data
# dry_run can be used to see what files will be downloaded
ebirdst_download_status("lobcur", pattern = "_27km_", dry_run = TRUE)
# use pattern to only download high resolution (3 km) weekly abundance data
ebirdst_download_status("lobcur", pattern = "abundance_median_3km",
                        dry_run = TRUE)
} # } 
```

--------------------------------

### List Available Files for a Species

Source: https://ebird.github.io/ebirdst/articles/api.html

Use this endpoint to list all available files for a given species and version year. Replace placeholders with your access key, species code, and desired version year. The response is a JSON array of file paths.

```http
https://st-download.ebird.org/v1/list-obj/{version_year}/{species_code}?key={access_key}
```

```http
https://st-download.ebird.org/v1/list-obj/2023/woothr?key=XXXXXXXX
```

--------------------------------

### Get eBird Status and Trends Data Directory

Source: https://ebird.github.io/ebirdst/reference/ebirdst_data_dir.html

Call this function to get the path to the default download directory for eBird Status and Trends data. The directory can be customized by setting the EBIRDST_DATA_DIR environment variable.

```r
ebirdst_data_dir()
#> [1] "/Users/mes335/data/ebirdst"
```

--------------------------------

### Standard GNU GPL Notice for Source Files

Source: https://ebird.github.io/ebirdst/LICENSE.html

This is the standard notice to be included at the beginning of each source file to declare it as free software under the GNU GPL.

```text
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
```

--------------------------------

### get_species_path()

Source: https://ebird.github.io/ebirdst/reference/index.html

Gets the file path to the data package for a specified species.

```APIDOC
## get_species_path()

### Description
Get the path to the data package for a given species.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### List Available Files

Source: https://ebird.github.io/ebirdst/articles/api.html

Lists all available data files for a specified species. This is useful for discovering which data products are available before downloading.

```APIDOC
## GET /v1/product/list

### Description
Lists available data files for a given species.

### Method
GET

### Endpoint
/v1/product/list

### Parameters
#### Query Parameters
- **speciesCode** (string) - Required - The unique eBird species code for which to list files.

### Response
#### Success Response (200)
- **files** (array of objects) - A list of available files, each with a `name` and `size`.

#### Response Example
```json
{
  "files": [
    {
      "name": "species_file_1.csv",
      "size": 102400
    },
    {
      "name": "species_file_2.csv",
      "size": 204800
    }
  ]
}
```
```

--------------------------------

### load_config()

Source: https://ebird.github.io/ebirdst/reference/index.html

Loads the eBird Status Data Products configuration file.

```APIDOC
## load_config()

### Description
Load eBird Status Data Products configuration file.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### Get Species Path Function Signature

Source: https://ebird.github.io/ebirdst/reference/get_species_path.html

This is the signature for the `get_species_path` function, showing its parameters and their default values.

```R
get_species_path(
  species,
  path = ebirdst_data_dir(),
  dataset = c("status", "trends"),
  check_downloaded = TRUE
)
```

--------------------------------

### Load Weekly Relative Abundance

Source: https://ebird.github.io/ebirdst/reference/load_raster.html

Loads weekly relative abundance data for a specified example dataset and resolution. The layer names represent the weeks.

```r
abd_weekly <- load_raster("yebsap-example", "abundance", resolution = "27km")
```

--------------------------------

### Download All Weeks in April

Source: https://ebird.github.io/ebirdst/reference/ebirdst_download_data_coverage.html

Use a pattern to download all data coverage products for the month of April.

```r
ebirdst_download_data_coverage(pattern = "04-")
```

--------------------------------

### Get eBird Status and Trends Data Inventory

Source: https://ebird.github.io/ebirdst/reference/ebirdst_data_inventory.html

Retrieves a summary of all downloaded eBird Status and Trends data packages. Defaults to the standard data directory.

```R
ebirdst_data_inventory()
```

```R
ebirdst_data_inventory("/path/to/data")
```

--------------------------------

### Download Single File URL Structure

Source: https://ebird.github.io/ebirdst/articles/api.html

Use this URL structure to download a single file. Replace `{object_path}` with the file's path and `{access_key}` with your user-specific access key.

```text
https://st-download.ebird.org/v1/fetch?objKey={object_path}&key={access_key}
```

--------------------------------

### Load Maximum Seasonal Abundance

Source: https://ebird.github.io/ebirdst/reference/load_raster.html

Loads the maximum seasonal abundance data for a specified example dataset, period, metric, and resolution. The layer names indicate the available seasons.

```r
abd_seasonal <- load_raster("yebsap-example", "abundance",
                            period = "seasonal", metric = "max",
                            resolution = "27km")
```

--------------------------------

### Download Spatial Coverage Products

Source: https://ebird.github.io/ebirdst/reference/ebirdst_download_data_coverage.html

Use the 'pattern' argument to filter and download only the spatial coverage products.

```r
ebirdst_download_data_coverage(pattern = "spatial-coverage")
```

--------------------------------

### Download and Load Seasonal Abundance Data

Source: https://ebird.github.io/ebirdst/articles/applications.html

Downloads seasonal mean relative abundance data for a species and loads the breeding season data. The `pattern` argument can filter specific files.

```r
# download seasonal relative abundance data
ebirdst_download_status("wesmea",
                        pattern = "abundance_seasonal_mean")

# load seasonal mean relative abundance at 3km resolution
abd_seasonal <- load_raster ("wesmea", 
                            product = "abundance", 
                            period = "seasonal",
                            metric = "mean",
                            resolution = "3km")

# extract just the breeding season relative abundance
abd_breeding <- abd_seasonal[["breeding"]]
```

--------------------------------

### Load Normalized PR-AUC PPM

Source: https://ebird.github.io/ebirdst/articles/status.html

Loads the normalized Precision-Recall Area Under the Curve (PR-AUC) for a specified example dataset. This metric is used for occurrence PPMs and is normalized to represent performance relative to random guessing.

```r
pr_auc <- load_ppm("yebsap-example", ppm = "occ_pr_auc_normalized")
print(pr_auc)
```

--------------------------------

### Download eBird Trends Data

Source: https://ebird.github.io/ebirdst/articles/trends.html

Use `ebirdst_download_trends()` to download breeding season trends data for a specified species. Ensure you have an API key and have consulted the eBird Status Data Products vignette for setup.

```r
ebirdst_download_trends("Sage Thrasher")
```

--------------------------------

### Load and Plot Site Selection Probability

Source: https://ebird.github.io/ebirdst/articles/status.html

Load the site selection probability data for a specific week and create a plot. Requires the 'ebirdst' package and assumes data has been downloaded.

```R
site_sel <- load_data_coverage("selection-probability", week = "05-10")
plot(site_sel, axes = FALSE)
```

--------------------------------

### View eBird Trends Data Time Period

Source: https://ebird.github.io/ebirdst/articles/trends.html

Filter and select columns from `trends_runs` to view the start and end years and dates for trend estimates for a specific species. This helps understand the temporal scope of the downloaded data.

```r
trends_runs |> 
  filter(common_name == "Sage Thrasher") |> 
  select(trends_start_year, trends_end_year,
         trends_start_date, trends_end_date)
```

--------------------------------

### Load Required R Packages

Source: https://ebird.github.io/ebirdst/articles/applications.html

Loads all necessary R packages for data manipulation, visualization, and eBird Status Data Products.

```r
library(dplyr)
library(ebirdst)
library(fields)
library(ggplot2)
library(lubridate)
library(rnaturalearth)
library(scico)
library(sf)
library(terra)
library(tidyr)
extract <- terra::extract
```

--------------------------------

### ebirdst_download_status

Source: https://ebird.github.io/ebirdst/reference/ebirdst_download_status.html

Downloads eBird Status Data Products for a specified species or an example dataset. Users can control which data products are downloaded and filter files using patterns. A dry run option is available to preview files before downloading.

```APIDOC
## ebirdst_download_status

### Description
Downloads eBird Status Data Products for a specified species or an example dataset. Users can control which data products are downloaded and filter files using patterns. A dry run option is available to preview files before downloading.

### Function Signature
```R
ebirdst_download_status(
  species,
  path = ebirdst_data_dir(),
  download_abundance = TRUE,
  download_occurrence = FALSE,
  download_count = FALSE,
  download_ranges = FALSE,
  download_regional = FALSE,
  download_pis = FALSE,
  download_ppms = FALSE,
  download_all = FALSE,
  pattern = NULL,
  dry_run = FALSE,
  force = FALSE,
  show_progress = TRUE
)
```

### Arguments

* **species** (character) - Required - A single species given as a scientific name, common name, or six-letter species code (e.g., "woothr"). To download the example dataset, use "yebsap-example".
* **path** (character) - Optional - Directory to download the data to. Defaults to a persistent data directory.
* **download_abundance** (logical) - Optional - Whether to download estimates of abundance and proportion of population. Defaults to TRUE.
* **download_occurrence** (logical) - Optional - Whether to download estimates of occurrence. Defaults to FALSE.
* **download_count** (logical) - Optional - Whether to download estimates of count. Defaults to FALSE.
* **download_ranges** (logical) - Optional - Whether to download the range polygons. Defaults to FALSE.
* **download_regional** (logical) - Optional - Whether to download the regional summary stats, e.g., percent of population in regions. Defaults to FALSE.
* **download_pis** (logical) - Optional - Whether to download spatial estimates of predictor importance. Defaults to FALSE.
* **download_ppms** (logical) - Optional - Whether to download spatial predictive performance metrics. Defaults to FALSE.
* **download_all** (logical) - Optional - Download all files in the data package. Equivalent to setting all the `download_` arguments to `TRUE`. Defaults to FALSE.
* **pattern** (character) - Optional - Regular expression pattern to filter files to download. This filter will be applied in addition to any of the `download_` arguments.
* **dry_run** (logical) - Optional - Whether to do a dry run, just listing files that will be downloaded. Defaults to FALSE.
* **force** (logical) - Optional - If the data have already been downloaded, should a fresh copy be downloaded anyway. Defaults to FALSE.
* **show_progress** (logical) - Optional - Whether to print download progress information. Defaults to TRUE.

### Value
Path to the folder containing the downloaded data package for the given species. If `dry_run = TRUE`, a list of files to download will be returned.

### Details
The complete data package for each species contains a large number of files. By default, this function only downloads the most commonly used files: GeoTIFFs providing estimates of relative abundance and proportion of population. The `download_` arguments and the `pattern` argument provide finer-grained control over what gets downloaded.

### Examples
```R
# download the example data
ebirdst_download_status("yebsap-example")

# download the data package for wood thrush
ebirdst_download_status("woothr")

# use pattern to only download low resolution (27 km) geotiff data
# dry_run can be used to see what files will be downloaded
ebirdst_download_status("lobcur", pattern = "_27km_", dry_run = TRUE)

# use pattern to only download high resolution (3 km) weekly abundance data
ebirdst_download_status("lobcur", pattern = "abundance_median_3km", dry_run = TRUE)
```
```

--------------------------------

### Access and Subset Seasonal Abundance

Source: https://ebird.github.io/ebirdst/reference/load_raster.html

Demonstrates how to view the available seasons in the seasonal abundance stack and subset the data to a specific season, such as breeding.

```r
names(abd_seasonal)
# subset to just breeding season abundance
abd_seasonal[["breeding"]]
```

--------------------------------

### Clone ebirdst Repository

Source: https://ebird.github.io/ebirdst/CONTRIBUTING.html

Clone your forked version of the ebirdst repository to your local machine.

```bash
git clone https://github.com/<yourgithubusername>/ebirdst.git
```

--------------------------------

### Get eBird Species Codes

Source: https://ebird.github.io/ebirdst/reference/get_species.html

Use this function to convert species names or codes into eBird species codes. It requires a character vector as input and returns a character vector of codes. Only species with eBird Status and Trends results are supported.

```R
get_species(c("Black-capped Chickadee", "Poecile gambeli", "carchi"))
#> [1] "bkcchi" "mouchi" "carchi"
```

--------------------------------

### Get eBird Status and Trends Data Product Versions

Source: https://ebird.github.io/ebirdst/reference/ebirdst_version.html

Call this function to retrieve the version years for eBird Status and Trends data products. The output includes the status version year, trends version year, and the release year.

```r
ebirdst_version()
```

```r
ebirdst_version()
#> $status_version_year
#> [1] 2023
#> 
#> $trends_version_year
#> [1] 2022
#> 
#> $release_year
#> [1] 2025
#> 

```

--------------------------------

### Create Quantile Bins for Abundance Data

Source: https://ebird.github.io/ebirdst/articles/applications.html

Generates quantile-based breaks for non-zero abundance values and adds a bin for zero values. Also defines a color palette for mapping.

```r
# quantiles of non-zero values
v <- values(abd_breeding_laea, na.rm = TRUE, mat = FALSE)
v <- v[v > 0]
breaks <- quantile(v, seq(0, 1, by = 0.1))
# add a bin for 0
breaks <- c(0, breaks)

# status and trends palette
pal <- ebirdst_palettes(length(breaks) - 2)
# add a color for zero
pal <- c("#e6e6e6", pal)

# map using the quantile bins
plot(abd_breeding_laea, breaks = breaks, col = pal, axes = FALSE)
```

--------------------------------

### load_data_coverage()

Source: https://ebird.github.io/ebirdst/reference/index.html

Loads eBird Status and Trends Data Coverage Products.

```APIDOC
## load_data_coverage()

### Description
Load eBird Status and Trends Data Coverage Products.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```

--------------------------------

### View Trend Season Dates for a Specific Species in R

Source: https://ebird.github.io/ebirdst/articles/trends.html

Filters the `trends_runs` data frame to display the start and end years and dates for the trend season of a specific species. Useful for understanding the temporal scope of trend estimates. Requires the `dplyr` package.

```R
trends_runs |> 
  filter(common_name == "Canvasback") |> 
  select(trends_start_year, trends_end_year, 
         trends_start_date, trends_end_date)
#> # A tibble: 1 × 4
#>   trends_start_year trends_end_year trends_start_date trends_end_date
#>               <dbl>           <dbl> <chr>             <chr>          
#> 1              2011            2021 12-20             01-25

```

--------------------------------

### load_trends

Source: https://ebird.github.io/ebirdst/reference/load_trends.html

Loads relative abundance trend estimates for specified species. Users can choose to get summarized ensemble estimates or individual fold-level estimates. The function requires species identification and optionally accepts a directory path for data storage and a flag to indicate whether to return fold-level estimates.

```APIDOC
## Function: load_trends

### Description
Loads the relative abundance trend estimates for a single species or a set of species. Trends are estimated on a 27 km by 27 km grid for a single season per species (breeding, non-breeding, or resident). Note that data must be downloaded using `ebirdst_download_trends()` prior to loading it using this function.

### Usage
```R
load_trends(species, fold_estimates = FALSE, path = ebirdst_data_dir())
```

### Arguments

* **species** (character) - Required. One or more species given as scientific names, common names or six-letter species codes (e.g. "woothr"). The full list of valid species can be viewed in the `ebirdst_runs` data frame included in this package; species with trends estimates are indicated by the `has_trends` column. To access the example dataset, use "yebsap-example".
* **fold_estimates** (logical) - Optional. By default, the trends summarized across the 100-fold ensemble are returned; however, by setting `fold_estimates = TRUE` the individual fold-level estimates are returned.
* **path** (character) - Optional. Directory to download the data to. All downloaded files will be placed in a sub-directory of this directory named for the data version year, e.g. "2020" for the 2020 Status Data Products. Each species' data package will then appear in a directory named with the eBird species code. Defaults to a persistent data directory, which can be found by calling `ebirdst_data_dir()`.

### Value
A data frame containing the trends estimates for a set of species. The following columns are included:
  * `species_code`: the alphanumeric eBird species code uniquely identifying the species.
  * `season`: season that the trend was estimated for: breeding, non-breeding, or resident.
  * `start_year`/`end_year`: the start and end years of the trend time period.
  * `start_date`/`end_date`: the start and end dates (`MM-DD` format) of the season for which the trend was estimated.
  * `srd_id`: unique integer identifier for the grid cell.
  * `longitude`/`latitude`: longitude and latitude of the grid cell center.
  * `abd`: relative abundance estimate for the middle of the trend time period (e.g. 2014 for a 2007-2021 trend).
  * `abd_ppy`: the median estimated percent per year change in relative abundance.
  * `abd_ppy_lower`/`abd_ppy_upper`: the 80% confidence interval for the estimated percent per year change in relative abundance.
  * `abd_ppy_nonzero`: a logical (TRUE/FALSE) value indicating if the 80% confidence limits overlap zero (FALSE) or don't overlap zero (TRUE)
  * `abd_trend`: the median estimated cumulative change in relative abundance over the trend time period.
  * `abd_trend_lower`/`abd_trend_upper`: the 80% confidence interval for the estimated cumulative change in relative abundance over the trend time period.

If `fold_estimates = TRUE`, a data frame of fold-level trend estimates is returned with the following columns:
  * `species_code`: the alphanumeric eBird species code uniquely identifying the species.
  * `season`: season that the trend was estimated for: breeding, non-breeding, or resident.
  * `srd_id`: unique integer identifier for the grid cell.
  * `abd`: relative abundance estimate for the middle of the trend time period (e.g. 2014 for a 2007-2021 trend).
  * `abd_ppy`: the estimated percent per year change in relative abundance.

### Details
The trends in relative abundance are estimated using a double machine learning model. To quantify uncertainty, an ensemble of 100 estimates is made at each location, each based on a random subsample of eBird data. The estimated trend is the median across the ensemble, and the 80% confidence intervals are the lower 10th and upper 90th percentiles across the ensemble. To access estimates from the individual folds making up the ensemble use `fold_estimates = TRUE`. These fold-level estimates can be used to quantify uncertainty, for example, when calculating the trend for a given region. For further details on the methodology used to estimate trends consult Fink et al. 2023.

### References
Fink, D., Johnston, A., Strimas-Mackey, M., Auer, T., Hochachka, W. M., Ligocki, S., Oldham Jaromczyk, L., Robinson, O., Wood, C., Kelling, S., & Rodewald, A. D. (2023). A Double machine learning trend model for citizen science data. Methods in Ecology and Evolution, 00, 1–14. https://doi.org/10.1111/2041-210X.14186

### Examples
```R
if (FALSE) { # \dontrun{
# download example trends data if it hasn't already been downloaded
ebirdst_download_trends("yebsap-example")

# load trends
trends <- load_trends("yebsap-example")

# load fold-level estimates
trends_folds <- load_trends("yebsap-example", fold_estimates = TRUE)
} # }
```
```

--------------------------------

### Access and Convert Weekly Layer Names

Source: https://ebird.github.io/ebirdst/reference/load_raster.html

Shows how to access the names of the weekly abundance layers and convert them to date objects.

```r
names(abd_weekly)
as.Date(names(abd_weekly))
```

--------------------------------

### Download Seasonal Proportion of Population Layer

Source: https://ebird.github.io/ebirdst/articles/applications.html

Downloads a specific seasonal mean proportion of population layer for a given species. Useful for analyzing species distribution across different seasons.

```r
# download only the season proportion of population layer
ebirdst_download_status("Surf Scoter", 
                        pattern = "proportion-population_seasonal_mean_3km")

```

--------------------------------

### Add Upstream Remote

Source: https://ebird.github.io/ebirdst/CONTRIBUTING.html

Add the official ebirdst repository as an upstream remote to track its progress.

```bash
git remote add upstream https://github.com/ebird/ebirdst.git
```

--------------------------------

### ebirdst_download_data_coverage()

Source: https://ebird.github.io/ebirdst/reference/index.html

Downloads eBird Status and Trends Data Coverage Products.

```APIDOC
## ebirdst_download_data_coverage()

### Description
Download eBird Status and Trends Data Coverage Products.

### Method
Not applicable (R function)

### Endpoint
Not applicable (R function)

### Parameters
None explicitly documented.

### Request Example
Not applicable (R function)

### Response
Not applicable (R function)
```
Tokens:
Raw