-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
171 lines (108 loc) · 9.69 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
---
output: rmarkdown::github_document
---
```{r, echo = FALSE, eval = TRUE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-",
message = FALSE,
warning = FALSE)
```
``` {r, echo = FALSE, eval = TRUE}
library(fwspp)
```
<!-- badges: start -->
<!-- For more info: https://usethis.r-lib.org/reference/badges.html -->
[](https://lifecycle.r-lib.org/articles/stages.html#stable)
<!-- badges: end -->
# The `fwspp` package
## Overview
This packages contains functions to perform geographic query of several biodiversity databases based on U.S. Fish and Wildlife Service (USFWS) administrative or acquisition property boundaries (plus optional buffers). At present, the package queries the [Global Biodiversity Information Facility (GBIF)](http://www.gbif.org/), [Biodiversity Information Serving Our Nation (BISON)](https://bison.usgs.gov/#home), [Integrated Digitized Biocollections (iDigBio)](https://www.idigbio.org/), and [VertNet](http://vertnet.org/). It draws heavily from the outstanding work by the [ROpenScience group](https://ropensci.org/) and their suite of species occurrence packages.
We provide options to:
* scrub records to reduce the number of returned records for each refuge (see scrubbing details below);
* update scientific names to their current accepted or valid form based on the [Integrated Taxonomic Information System (ITIS)](http://www.itis.gov) (see taxonomic details below).
## Installation
The `fwspp` package requires [R](https://www.r-project.org/) (>= 3.4) and [Rtools](https://cran.r-project.org/bin/windows/Rtools/). Both will require administrative privileges but the subsequent installation of packages will not.
With R and Rtools installed, it's relatively painless to install and load the `fwspp` package. If you receive an SSL or CA Certificate error, take the extra steps documented below.
```
# If devtools package is not installed
install.packages("devtools", dependencies = TRUE)
# Now install fwspp
devtools::install_github("git@github.com:USFWS/fwspp.git", ref = "main")
# Now load the functionality
library("fwspp")
```
Prior to your first use of `fwspp`, you'll need to install the USFWS Cadastral Geodatabase. You can do this now, using the `install_fws_cadastral` function:
```
install_fws_cadastral()
```
or later, when you'll be prompted by the `fws_occ` function. The process takes 10 minutes or so to complete.
# Usage
## Important usage limitations/notes
The `fwspp` package exists strictly to extract occurrence data on USFWS properties, usually National Wildlife Refuges. Attempts to estimate or infer relative abundance are **most strongly discouraged** and **almost certainly meaningless**.
## Using `fwspp`
Extracting species observation data is essentially a three-step process:
1. Decide on the USFWS properties to query
1. Decide on the boundary, scrubbing, and output parameters of that query
1. Run the query
Okay, four steps:
1. Wait... probably a long while...
### Step 1 - Find USFWS properties to query
The easiest way to generate a list (actually a `data.frame`) of USFWS properties to query is to use the `find_fws` function. With `find_fws` you can restrict your search of USFWS properties to a particular [USFWS region](https://www.fws.gov/where/), particular USFWS property types (see below), and use regular expressions to make the string matching as strict as necessary. Here are a few examples:
```{r}
# Get all National Wildlife Refuges (527 as of 2017-11-10)
# Issues a warning because of two identically-named, but distinct, refuges
all_refs <- find_fws()
# Search across all refuges with a partial name match
# Only 1 refuge contains 'longleaf'; Mountain Longleaf NWR
(ml <- find_fws("longleaf"))
# Search across all refuges matching multiple strings
(multi <- find_fws(c("longleaf", "romain")))
# Could also have used regular expression
(multi <- find_fws("longleaf|romain"))
# Here's a tricky one - Hatchie NWR
# Simple search returns three refuges with 'hatchie' in name
(hatch <- find_fws("hatchie"))
# Option 1: select the one you need ad hoc
(hatch <- hatch[1, ])
# Option 2: regular expressions
(hatch <- find_fws("^hatchie")) # Make name start with 'hatchie'
# Return all southeast (region 4) refuges
r4_refs <- find_fws(region = 4)
nrow(r4_refs)
# Return all mountain-prairie (region 6) refuges and waterfowl production areas
r6_all <- find_fws(ptype = c("NWR", "WPA"), region = 6)
```
#### USFWS property types
The `find_fws` function gives you a `ptype` argument to search for several USFWS property types. The most common and default property type is the National Wildlife Refuge (NWR), but other options include Waterfowl Production Areas (WPA), Wildlife Management Areas (WMA), National Fish Hatcheries (NFH), Wildlife Management Areas (WMA), and Farm Service Agency indices (FSA). You can specify multiple options as illustrated in the last example above.
### Step 2 - Boundary, scrubbing, and taxonomic decisions
#### Boundary options
We offer two options for querying the boundaries of refuges and other USFWS properties via the `bnd` argument to the `fws_occ` function. The default `bnd = "admin"` queries 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/82894 for more information. Using `bnd = "acq"` queries the external boundaries of lands and waters that are **approved for acquisition** by the USFWS in North America, U.S. Trust Territories and Possessions. See https://ecos.fws.gov/ServCat/Reference/Profile/82893 for more information.
#### Scrubbing options
By default, we scrub **a lot** of records (`scrub = "strict"`). Specifically, we endeavor to retain, for a given geometry, a single record for each species. We attempt to preferentially retain observations with a URL that best substantiates the observation (i.e., the "best" evidence). We rank evidence 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. We do not retain any records for which evidence was not available (i.e., no associated collection or catalog number). We optionally offer a less restrictive scrubbing option (`scrub = "moderate"`) that attempts only to eliminate records sharing the same catalog number and redundant observations (i.e., multiple individuals of the same species recorded on the same date at a single location). Users can also disable scrubbing altogether (`scrub = "none"`).
#### Taxonomy
By default (`taxonomy = TRUE`), we attempt to validate scientific names against the [Integrated Taxonomic Information System (ITIS)](http://www.itis.gov). It does this not by connecting to ITIS directly, but by requesting information from a REST web service maintained by the National Park Service (NPS) 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 (if it wasn't already), and the corresponding ITIS Taxonomic Serial Number, common names, NPS-specific taxon code, and a general taxa "category" (e.g., Mammals, Birds, Fungi) designated by the NPS are returned. Modifications to observation taxonomy can be suppressed with `taxonomy = FALSE`.
#### Other options
By default, the `fws_occ` function makes the query using the actual property boundary, either administrative or acquisition. However, the `buffer` argument provides the option to expand the query of occurrence records beyond the property boundary into a user-specified buffer (in kilometers). This may be useful for very small properties in which species observations in the adjacent areas may provide a good indication of what is present, or expected to be present, within the boundary. By design, `fws_occ` generates a lot of messaging as properties are processed; we like to see that things are moving along. If this annoys you, specify `verbose = FALSE` and enjoy a very slowly updating progress bar and limited messaging.
### Step 3 - Run the query
With USFWS properties and query options identified, all that's left is to run the `fws_occ` function, passing the object containing the properties to query generated by `find_fws` and specifying any changes from the defaults to the `bnd`, `buffer`, `scrub`, `taxonomy`, and `verbose` options.
Some examples:
```
# Query all southeast refuges (NWR only), using defaults
r4 <- find_fws(region = 4)
r4_occ <- fws_occ(r4)
# Query mountain-prairie refuges and waterfowl production areas
# Suppress most messaging & replace with progress bar
r6 <- find_fws(region = 6, ptype = c("NWR", "WPA"))
r6_occ <- fws_occ(r6, verbose = FALSE)
# Query Key West NWR with 10 km buffer; suppressing taxonomy changes
kw <- find_fws("key west")
kw_occ <- fws_occ(kw, buffer = 10, taxonomy = FALSE)
```
### Step 4 - Wait...
Querying many properties can take hours, particularly if they are relatively large or contain hundreds of thousands of records. Typically the best option is to set `fws_occ` off and running in the background (or overnight) and do something more productive with yourself...
## Getting help
Contact the project maintainer for help with this repository.
## Contribute
Contact the project maintainer for information about contributing to this repository. Submit a [GitHub Issue](https://github.com/USFWS/fwspp/issues/new) to report a bug or request a feature or enhancement.