Geographic query of biodiversity databases based on U.S. Fish and Wildlife Service (USFWS) property boundaries
1 2 3
character scalar indicating the type of property boundary to use. Default ("admin") uses the current administrative boundary. The approved acquisition boundary ("acq") is another option.
numeric scalar; distance (km) from the
character; one of "strict" (default), "moderate", or "none",
indicating the extent to which to reduce the number of records returned for
logical (default TRUE); attempt to link occurrence records to standardized taxon information? See details.
logical (default TRUE); print messages during species occurrence queries?
numeric; if specified, serves as a multiplier for the timeout
value calculated internally (e.g.,
**Important usage limitations**: This function exists strictly to extract
occurrence data for a given
fws property. Attempts at estimating
or inferring relative abundance are most strongly discouraged and almost
Also note that the extraction of records occurs on a property-by-property basis so the same record may occur in multiple polygons depending on buffer specifications.
list of class
fwspp with observations for each property with
the following columns if taxonomic information is requested (
taxonomy = TRUE;
taxonomy = FALSE, only a subset of these columns is returned.
official organizational name of USFWS property
Scientific name associated with the observation.
Longitude (WGS84) of observation.
Latitude (WGS84) of observation.
Locational uncertainty (m) of observation coordinates; typically unavailable.
Year of observation, if available.
Month of observation, if available.
Day of month of observation, if available.
Attempt to link observation to a URL that best substantiates the observation, if available, generally in the following order: (1) URL to observation with media (photo, audio, video) or the media itself, (2) URL to the observation in the original collection, (3) URL of the collection, with catalog number, or (4) URL of the institution housing the collection, with catalog number.
Biodiversity database source of the observation, currently one of GBIF, BISON, iDigBio, VertNet, EcoEngine, or AntWeb.
Accepted/valid scientific name from ITIS, if available.
Regularly used vernacular names, if available.
Taxonomic rank of observation.
Generic taxonomic grouping for taxa used in NPSpecies database (https://irma.nps.gov/npspecies).
Accepted/valid Taxonomic Serial Number from ITIS, if available.
Additional notes on the observation, currently restricted to indicating that a matching taxon was not found in ITIS or trouble singling out a taxon from NPSpecies.
The basic process is to query GBIF, BISON, iDigBio, the Berkeley
'Ecoinformatics' Engine, and AntWeb based on the bounding box
associated with each
fws and any requested buffer. For VertNet,
the API requires spatial searches using a lat/lon coordinate and search
radius. We calculate the radius needed to fully capture the desired
geometry. Records are subsequently filtered based on the exact geometry.
Properties that occupy a relatively small area compared to the corresponding bounding box will be split into smaller pieces to avoid unnecessarily large queries. Likewise, queries (typically GBIF and BISON) that contain many records (> 125000) are split to improve efficiency (both) and recover all records (GBIF).
We provide the options to:
scrub records to reduce the number of returned records for each
fws (details below);
attempt to link each observation to some standardized taxonomic information (details below)
By default (
scrub = "strict"),
fws_occ scrubs a lot of records.
Specifically, within a given property, it retains a single record for each
species, giving preference to records with associated media (e.g., photo, audio).
The retained record is typically the most recent with evidence to support the
identification. Records for which evidence was not available (i.e., no associated
collection or catalog number) are removed. Moderate scrubbing
scrub = "moderate") attempts only to remove duplicate records (i.e., identical
catalog numbers) and redundant observations (i.e., multiple individuals of the same
species recorded on the same date at a single location). All records can be
returned with (
scrub = "none").
By default (
taxonomy = TRUE),
fwspp attempts to check the validity of
scientific names against the Integrated Taxonomic Information System (ITIS). It does
this not by connecting to ITIS directly, but by requesting information from a web
service maintained by the National Park Service as part of their NPSpecies database
(https://irma.nps.gov/npspecies). Note that this means if taxonomy information
is requested, and an ITIS match found, the scientific name will be converted to the
"accepted" ITIS scientific name, and the corresponding ITIS Taxonomic Serial Number,
an NPS-specific taxon code, a common name used by NPS, and a general organism
"category" (e.g., Mammals, Birds, Fungi) are returned.
The boundaries specified by the "admin" option to the
delineates those lands and waters administered by the USFWS in North
America, U.S. Trust Territories and Possessions. It may also include
inholdings that are not administered by the USFWS. The primary source
for this information is the USFWS Realty program. See
https://ecos.fws.gov/ServCat/Reference/Profile/60739 for more
The boundaries specified by the "acq" option to the
delineates the external boundaries of lands and waters that are approved
for acquisition by the USFWS in North America, U.S. Trust Territories and
Possessions. The primary source for this information is the USFWS Realty
program. See https://ecos.fws.gov/ServCat/Reference/Profile/60738 for
By default, timeout is calculated based on testing of BISON queries on a ~ 20 Mbps
internet connection. BISON queries are nearly always the largest (by # records)
*contiguous* requests (GBIF is slower but requests occur in smaller chunks). If
timeouts are a recurring problem, however, it may be worth checking your download
speed (e.g. http://www.speedtest.net) and setting this parameter if your
speeds are considerably below ~ 20 Mbps to allow more time for HTTP requests to
process. For example, if your download speed is estimated at 5 Mbps, you might
consider setting this parameter to
timeout = 4 or so. If regular timeout
persist after adjusting this parameter, however, please contact the maintainer
with details or, better yet, file an issue at
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
## Not run: # Single refuge, administrative boundary, no buffer # By default, records are scrubbed very strictly (see Details) # Mountain Longleaf National Wildlife Refuge ml <- find_fws("longleaf") ml_occ <- fws_occ(fws = ml) # Multiple refuges, acquisition boundary with 5 km buffer, moderate scrubbing, # no taxonomy info added multi <- find_fws(c("longleaf", "romain")) multi_occ <- fws_occ(fws = multi, bnd = "acq", buffer = 5, scrub = "moderate", taxonomy = FALSE) # All Region 4 (southeast) refuges, with defaults r4 <- find_fws(region = 4) r4_occ <- fw_spp(r4) ## End(Not run)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.