R/ebirdst-extent.R
ebirdst_extent.Rdebirdst_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, ...)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.
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.
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.
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").
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.
# 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