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

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, ...)

## 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("2018-12-01", "2018-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.

...

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.

## 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").

## 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("2018-12-01", "2018-01-31") would subset to data in December or January.

## Methods (by class)

• bbox: bounding box created with st_bbox()

• numeric: bounding box given as edges

• sfc: polygons as sfc spatial feature column

• sf: polygons as sf object

## 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)
#> eBird Status & Trends extent:
#>   Bounding box: xmin -80; ymin 40; xmax -70; ymax 47
#>   CRS: +proj=longlat +datum=WGS84 +no_defs
#>   Temporal extent: 01-01  -  12-31

# bbox object
bb <- sf::st_bbox(bb_vec, crs = 4326)
ebirdst_extent(bb)
#> eBird Status & Trends extent:
#>   Bounding box: xmin -80; ymin 40; xmax -70; ymax 47
#>   CRS: +proj=longlat +datum=WGS84 +no_defs
#>   Temporal extent: 01-01  -  12-31

# polygon imported from a shapefile
ebirdst_extent(poly)
#> eBird Status & Trends extent:
#>   Polygon: 1 MULTIPOLYGON features
#>   Bounding box: xmin -84.32385; ymin 33.88199; xmax -75.45698; ymax 36.58965
#>   Temporal extent: 01-01  -  12-31

# subset to january
ebirdst_extent(bb, t = c("2018-01-01", "2018-01-31"))
#> eBird Status & Trends extent:
#>   Bounding box: xmin -80; ymin 40; xmax -70; ymax 47
#>   CRS: +proj=longlat +datum=WGS84 +no_defs
#>   Temporal extent: 01-01  -  01-31

# dates can wrap around, e.g. to use dec-jan
ebirdst_extent(bb, t = c("2018-12-01", "2018-01-31"))
#> eBird Status & Trends extent:
#>   Bounding box: xmin -80; ymin 40; xmax -70; ymax 47
#>   CRS: +proj=longlat +datum=WGS84 +no_defs
#>   Temporal extent: 12-01  -  01-31

# dates can also be given without an associated year
ebirdst_extent(bb, t = c("12-01", "01-31"))
#> eBird Status & Trends extent:
#>   Bounding box: xmin -80; ymin 40; xmax -70; ymax 47
#>   CRS: +proj=longlat +datum=WGS84 +no_defs
#>   Temporal extent: 12-01  -  01-31
`