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.

...

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.

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
poly <- sf::read_sf(system.file("shape/nc.shp", package="sf"))
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
#>   CRS: +proj=longlat +datum=NAD27 +no_defs 
#>   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