ebirdst (version 2.2021.3)

ebirdst_extent: Construct a spatiotemporal extent object to subset Status and Trends data

Description

ebirdst_extent object are used to subset the eBird Status and Trends data spatially and/or temporally. This function constructs these objects.

Usage

ebirdst_extent(x, t, ...)
# S3 method for bbox
ebirdst_extent(x, t, ...)
# S3 method for numeric
ebirdst_extent(x, t, crs = 4326, ...)
# S3 method for sfc
ebirdst_extent(x, t, ...)
# S3 method for sf
ebirdst_extent(x, t, ...)

Value

An ebirdst_extent object consisting of a list with three elements: the spatial extent extent, the temporal extent t, and type (either "bbox" or "polygon").

Arguments

x

the spatial extent; either a rectangular bounding box (defined as a vector of numbers representing the coordinates of the boundaries or an st_bbox() object) or a polygon (an sf object). See Details for further explanation of the format of x.

t

the temporal extent; a 2-element vector of the start and end dates of the temporal extent, provided either as dates (Date objects or strings in ISO format "YYYY-MM-DD") or numbers between 0 and 1 representing the fraction of the year. Note that dates can wrap around the year, e.g. `c("2021-12-01", "2021-01-31") is acceptable. See Details for further explanation of the format of t. Leave the argument blank to include the full year of data.

...

Additional arguments used by methods.

crs

coordinate reference system, provided as a crs object or argument to st_crs(). Defaults to unprojected, lat/long coordinates (crs = 4326). Only required if x is given as a numeric vector defining the bounding box, ignored in all other cases.

Methods (by class)

• ebirdst_extent(bbox): bounding box created with st_bbox()

• ebirdst_extent(numeric): bounding box given as edges

• ebirdst_extent(sfc): polygons as sfc spatial feature column

• ebirdst_extent(sf): polygons as sf object

Details

The spatial extent, x, can be either a rectangular bounding box or a set of spatial polygons. The bounding box can be defined either as an st_bbox() object or by providing the coordinates of the rectangle edges directly as a named vector with elements xmin, xmax, ymin, and ymax (note that latitude and longitude correspond to y and x, respectively). In this latter case, a coordinate reference system must be provided explicitly via the crs argument (crs = 4326 is the default and is a short form for unprojected lat/long coordinates). For a polygon spatial extent, x should be either an sf or sfc object (with feature type POLYGON or MULTIPOLYGON) from the sf package. To import data from a Shapefile or GeoPackage into this format, use read_sf().

The temporal extent defines the start and end dates of the time period. These are most easily provided as Date objects or date strings in ISO format ("YYYY-MM-DD"). If dates are defined as strings, the year can be omitted (i.e. "MM-DD"). Alternatively, dates can be defined in terms of fractions of the year, e.g. t = c(0.25, 0.5) would subset to data within the second quarter of the year. In all cases, dates can wrap around the year, e.g. c("2021-12-01", "2021-01-31") would subset to data in December or January.

Examples

# bounding box of the north eastern united stats as a numeric vector
bb_vec <- c(xmin = -80, xmax = -70, ymin = 40, ymax = 47)
ebirdst_extent(bb_vec)

# bbox object
bb <- sf::st_bbox(bb_vec, crs = 4326)
ebirdst_extent(bb)

# polygon imported from a shapefile
poly <- sf::read_sf(system.file("shape/nc.shp", package="sf"))
ebirdst_extent(poly)

# subset to january
ebirdst_extent(bb, t = c("2021-01-01", "2021-01-31"))

# dates can wrap around, e.g. to use dec-jan
ebirdst_extent(bb, t = c("2021-12-01", "2021-01-31"))

# dates can also be given without an associated year
ebirdst_extent(bb, t = c("12-01", "01-31"))