Installing fwsinat

The fwsinat package requires you to have R (>= 3.3) installed on your computer as well as Rtools. Both will require administrative priveleges but the installation of packages after this initial install will not.

With R and Rtools installed, it’s simple to install and load the fwsinat package to access its functionality.

NOTE: If you receive a SSL or CA Certificate error, you may need to take the extra step documented below.

# If devtools package is not installed
install.packages("devtools", dependencies = TRUE)

# Now install and load fwsinat
devtools::install_github("adamdsmith/fwsinat")
library("fwsinat")

# If you receive a SSL or CA Certificate error
install.packages("httr")
library("httr")
set_config(config(ssl_verifypeer = 0L))
devtools::install_github("adamdsmith/fwsinat")
library("fwsinat")

The fwsinat package

This packages currently contains functions to:

1. retrieve iNaturalist observations for any number of available USFWS properties (inat_retrieve), the valid names of which can be obtained with the find_refuges function;
2. update previous retrievals of observations (inat_update);
3. export the observations to separate spreadsheets by USFWS property for distribution (inat_export); and
4. harvest observations on USFWS properties into the USFWS NWRS iNaturalist project (inat_harvest)

Using fwsinat

The first step to using fwsinat is to generate a list of USFWS properties from which you’d like to retrieve observations. This can be done using the find_refuges function, which accepts as input a vector of strings you expect will return your desired refuge(s). The find_refuges function is case-insensitive and works with partial matches. For example, if we’re interested in retrieving observations on Harris Neck, Loxahatchee, and Chassahowitzka NWRs, we can input a vector of strings we think are adequate to return those refuges:

refs <- c("merritt", "lox", "chass")
(refs <- find_refuges(refs))

Success! Note that some searches will return multiple matches that you may not be seeking. If we’re interested in Hatchie NWR, for example:

(hatchie <- find_refuges("hatchie"))

Three matches! No worries! We can either select the one we want ad hoc or use regular expressions to narrow the matches:

## Narrow the search after the fact
(hatchie <- hatchie[1])

# Narrow the search with regular expressions
# In this case, require the property to start with "Hatchie"
(hatchie <- find_refuges("^hatchie"))

There are a couple more options to the find_refuges function to help you narrow your search; use ?find_refuges for more information. By default, find_refuges returns ALL available USFWS properties.

Now let’s pick a refuge and retrieve the observations from iNaturalist… inat_retrieve is our friend. Before we do so, however, we need to decide on a few options:

1. Do we want all iNaturalist observations on the property or only those from a specific project?

   By default, inat_retrieve returns only observations associated with the USFWS National Wildlife Refuge System iNaturalist project. If you want a different project, you’ll need to specify which one with the inat_proj argument (see ?inat_retrieve for guidance on what’s expected). If you want ALL observations, use inat_proj = NULL (see below).

2. Do we want to limit the dates of those observations?

   By default, inat_retrieve does not limit retrievals by date range. See ?inat_retrieve for guidance if this is of interest.

3. Do we want helpful messages during the retrieval?

   Generally these are useful to track progress, so the default is to print these messages. If they annoy you, you can reduce them to a minimum by passing verbose = FALSE to inat_retrieve.

Example: Harris Neck NWR

hn <- find_refuges("harris neck")
# Harris Neck records ONLY on USFWS NWRS iNaturalist Project
hn_recs <- inat_retrieve(hn)

Processing Harris Neck National Wildlife Refuge within the
usfws-national-wildlife-refuge-system project.
Retrieving 32 records.

Records retrieved: 
  0-32

# Harris Neck records across ALL iNaturalist Projects
hn_all <- inat_retrieve(hn, inat_proj = NULL)

Processing Harris Neck National Wildlife Refuge across all iNaturalist projects.
Retrieving 55 records.

Records retrieved: 
  0-55

Notice there were 23 observations on the refuge that do not belong to the USFWS NWRS project. We want those observations! We can try and harvest them with inat_harvest.

This will require you to have an iNaturalist account and to pass your username and password. I illustrate it here while keeping my credentials hidden, but you can pass your username and password as character strings to the user and pw arguments of the function…

hn_harvest <- inat_harvest(hn, user = Sys.getenv("user"), pw = Sys.getenv("pw"), interactive = FALSE)

23 observations available for harvest on Harris Neck National Wildlife Refuge.

   |                                                  | 0 % ~calculating  
   |+++                                               | 4 % ~28s          
   |+++++                                             | 9 % ~29s          
   |+++++++                                           | 13% ~26s          
   |+++++++++                                         | 17% ~25s          
   |+++++++++++                                       | 22% ~23s          
   |++++++++++++++                                    | 26% ~22s          
   |++++++++++++++++                                  | 30% ~21s          
   |++++++++++++++++++                                | 35% ~20s          
   |++++++++++++++++++++                              | 39% ~18s          
   |++++++++++++++++++++++                            | 43% ~17s          
   |++++++++++++++++++++++++                          | 48% ~15s          
   |+++++++++++++++++++++++++++                       | 52% ~14s          
   |+++++++++++++++++++++++++++++                     | 57% ~13s          
   |+++++++++++++++++++++++++++++++                   | 61% ~11s          
   |+++++++++++++++++++++++++++++++++                 | 65% ~10s          
   |+++++++++++++++++++++++++++++++++++               | 70% ~09s          
   |+++++++++++++++++++++++++++++++++++++             | 74% ~08s          
   |++++++++++++++++++++++++++++++++++++++++          | 78% ~06s          
   |++++++++++++++++++++++++++++++++++++++++++        | 83% ~05s          
   |++++++++++++++++++++++++++++++++++++++++++++      | 87% ~04s          
   |++++++++++++++++++++++++++++++++++++++++++++++    | 91% ~03s          
   |++++++++++++++++++++++++++++++++++++++++++++++++  | 96% ~01s          
   |++++++++++++++++++++++++++++++++++++++++++++++++++| 100% elapsed = 29s

Occasionally observations cannot be harvested because the user restricts their observations. If this happens, you will receive a message indicating how many records could not be harvested. In the case of Harris Neck, we do not receive such a message because all records were successfully harvested.

If some records cannot be harvested, however, you can explore the reasons for these failures by ‘tabling’ the error message column of the object you just created.

# This doesn't make sense for Harris Neck, but here's how you'd look at reasons any records
# were not harvested to the USFWS NWRS project...
# table(hn_harvest$error_msg)
# USFWS NWRS project now contains all currently harvestable observations
hn_recs <- inat_retrieve(hn)

Processing Harris Neck National Wildlife Refuge within the
usfws-national-wildlife-refuge-system project.
Retrieving 55 records.

Records retrieved: 
  0-55

Notice that all 55 records on Harris Neck are now in the USFWS NWRS project…

Try it yourself for Savannah NWR (126 records available for harvest when I last checked) or some other refuge… Note that record harvesting takes between 1-2 seconds per record, so plan accordingly for large harvests.

sav <- find_refuges("savannah")