fws_occ: Species occurrence records on U.S. Fish and Wildlife...
In adamdsmith/fwspp: Querying Biodiversity Databases on USFWS Properties
fws_occ R Documentation
Species occurrence records on U.S. Fish and Wildlife properties
Description
Geographic query of biodiversity databases based on U.S. Fish and Wildlife
Service (USFWS) property boundaries
Usage
fws_occ(
fws = NULL,
bnd = c("admin", "acq"),
buffer = 0,
scrub = c("strict", "moderate", "none"),
taxonomy = TRUE,
verbose = TRUE,
timeout = NULL
)
Arguments
fws
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.
bnd
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.
buffer
numeric scalar; distance (km) from the fws bnd to
include in the search for species occurrence records. Default is no buffer.
scrub
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.
taxonomy
logical (default TRUE); attempt to link occurrence records to
standardized taxon information? See details.
verbose
logical (default TRUE); print messages during species occurrence
queries?
timeout
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.
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.
Value
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.
- org_name
official organizational name of USFWS property
- sci_name
Scientific name associated with the observation.
- lon
Longitude (WGS84) of observation.
- lat
Latitude (WGS84) of observation.
- loc_unc_m
Locational uncertainty (m) of observation coordinates; typically
unavailable.
- year
Year of observation, if available.
- month
Month of observation, if available.
- day
Day of month of observation, if available.
- evidence
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.
- bio_repo
Biodiversity database source of the observation, currently one of
GBIF, BISON, iDigBio, VertNet, EcoEngine, or AntWeb.
- acc_sci_name
Accepted/valid scientific name from ITIS, if available.
- com_name
Regularly used vernacular names, if available.
- taxon_rank
Taxonomic rank of observation.
- category
Generic taxonomic grouping for taxa used in FWSpecies database.
- tsn
Accepted/valid Taxonomic Serial Number from ITIS, if available.
- note
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 FWSpecies.
General overview
The basic process is to query GBIF, 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) 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)
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 U.S. Fish and Wildlife Service as part of their FWSpecies database
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 USFWS, 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/USFWS/fwspp/issues.
Examples
## 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 Oct. 16, 2023, 3:43 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| fws_occ | R Documentation |
Species occurrence records on U.S. Fish and Wildlife properties
Description
Geographic query of biodiversity databases based on U.S. Fish and Wildlife Service (USFWS) property boundaries
Usage
fws_occ(
fws = NULL,
bnd = c("admin", "acq"),
buffer = 0,
scrub = c("strict", "moderate", "none"),
taxonomy = TRUE,
verbose = TRUE,
timeout = NULL
)
Arguments
fws |
|
bnd |
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. |
buffer |
numeric scalar; distance (km) from the |
scrub |
character; one of "strict" (default), "moderate", or "none",
indicating the extent to which to reduce the number of records returned for
a given |
taxonomy |
logical (default TRUE); attempt to link occurrence records to standardized taxon information? See details. |
verbose |
logical (default TRUE); print messages during species occurrence queries? |
timeout |
numeric; if specified, serves as a multiplier for the timeout
value calculated internally (e.g., |
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.
Value
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.
- org_name
official organizational name of USFWS property
- sci_name
Scientific name associated with the observation.
- lon
Longitude (WGS84) of observation.
- lat
Latitude (WGS84) of observation.
- loc_unc_m
Locational uncertainty (m) of observation coordinates; typically unavailable.
- year
Year of observation, if available.
- month
Month of observation, if available.
- day
Day of month of observation, if available.
- evidence
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.
- bio_repo
Biodiversity database source of the observation, currently one of GBIF, BISON, iDigBio, VertNet, EcoEngine, or AntWeb.
- acc_sci_name
Accepted/valid scientific name from ITIS, if available.
- com_name
Regularly used vernacular names, if available.
- taxon_rank
Taxonomic rank of observation.
- category
Generic taxonomic grouping for taxa used in FWSpecies database.
- tsn
Accepted/valid Taxonomic Serial Number from ITIS, if available.
- note
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 FWSpecies.
General overview
The basic process is to query GBIF, 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) 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)
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 U.S. Fish and Wildlife Service as part of their FWSpecies database
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 USFWS, 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/USFWS/fwspp/issues.
Examples
## 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)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.