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, ...)| x | the spatial extent; either a rectangular bounding box (defined as a
vector of numbers representing the coordinates of the boundaries or an
|
|---|---|
| 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 |
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.
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
# 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