fws_occ: Species occurrence records on U.S. Fish and Wildlife...

Description Usage Arguments Details Value General overview Scrubbing details Taxonomy information details Additional boundary information Query timeout details Examples

View source: R/fws_occ.R


Geographic query of biodiversity databases based on U.S. Fish and Wildlife Service (USFWS) property boundaries


fws_occ(fws = NULL, bnd = c("admin", "acq"), buffer = 0,
  scrub = c("strict", "moderate", "none"), taxonomy = TRUE,
  verbose = TRUE, timeout = NULL)



data.frame of organizational names (ORGNAME) and type (RSL_TYPE) of USFWS properties and their associated USFWS region (FWSREGION), within and around which the user wishes to extract species occurrence records. It is strongly recommended to use the results generated by find_fws to ensure proper content and formatting. See examples.


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 fws bnd to include in the search for species occurrence records. Default is no buffer.


character; one of "strict" (default), "moderate", or "none", indicating the extent to which to reduce the number of records returned for a given fws. See details.


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., timeout = 2 doubles the amount of time to allow for HTTP requests to process. By default (timeout = NULL), the query timeout is set programmatically and conservatively. See details.


**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 certainly meaningless.

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.


an list of class fwspp with observations for each property with the following columns if taxonomic information is requested (taxonomy = TRUE; default). If 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.

General overview

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:

Scrubbing details

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

Taxonomy information details

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.

Additional boundary information

The boundaries specified by the "admin" option to the bnd argument 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 information.

The boundaries specified by the "acq" option to the bnd argument 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 more information.

Query timeout details

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 https://github.com/adamdsmith/fwspp/issues.


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

adamdsmith/fwspp documentation built on April 3, 2018, 12:02 p.m.