Repository files navigation

Edmund Hart, Stéphane Guillou

R wrapper for iNaturalist APIs for accessing the observations. Thedetailed documentation of the API is available on theiNaturalistwebsite and is part ofour larger species occurrence searching packagesSPOCC.

You can install the latest version available on CRAN with:

install.packages("rinat")

Alternatively, you can install the development version from Github with:

remotes::install_github("ropensci/rinat")

get_inat_obs() is the primary function that retrieves observationsfrom iNaturalist. The text or taxon search can be refined by observationdate, record quality and location.

It is recommended to set thequality argument to"research" inorder to get more reliable data that has been validated by severalcontributors.

To return only records of a specific species or taxonomic group, use thetaxon_name argument. For example, to return observations of anythingfrom the Nymphalidae family, and restricting the search to the year2015:

library(rinat)nymphalidae<- get_inat_obs(taxon_name="Nymphalidae",year=2015)# how many unique taxa?length(unique(nymphalidae$scientific_name))

## [1] 80

Note thatget_inat_obs() will return 100 observations by default.This can be controlled with themaxresults argument.

You can also search observations with any string. It will search theentire iNaturalist database, so the search below will return all entriesthatmention Monarch butterflies, not just Monarch observations.

monarchs<- get_inat_obs(query="Monarch Butterfly",year=2021)# which taxa were returned?unique(monarchs$scientific_name)

## [1] "Danaus plexippus"           "Danaus plexippus plexippus"## [3] "Danaina"

You can combine the fuzzy search with the precise taxon search. Forexample, to get Monarch butterfly observations that also mention theterm “chrysalis”:

monarch_chrysalis<- get_inat_obs(taxon_name="Danaus plexippus",query="chrysalis")

You can also search within a bounding box by giving a simple set ofcoordinates.

## Search by areabounds<- c(38.44047,-125,40.86652,-121.837)deer<- get_inat_obs(query="Mule Deer",bounds=bounds)plot(deer$longitude,deer$latitude)

More functions are available, notably to access:

• observations in a project withget_inat_obs_project()
• details of a single observation withget_inat_obs_id()
• observations from a single user withget_inat_obs_user()
• taxa statistics withget_inat_taxon_stats()
• user statistics withget_inat_user_stats()

More detailed examples are included in the vignette:

vignette("rinat-intro",package="rinat")

Basic maps can be created with theinat_map() function to quicklyvisualize search results. Theplot = FALSE option can be used to avoiddisplaying the initial plot when further customising it with ggplot2functions.

library(ggplot2)## Map 100 spotted salamandersa_mac<- get_inat_obs(taxon_name="Ambystoma maculatum",year=2021)salamander_map<- inat_map(a_mac,plot=FALSE)### Further customise the returned ggplot objectsalamander_map+ borders("state")+ theme_bw()

inat_map() is useful for quickly mapping single-species data obtainedwith rinat. However, more complicated plots are best made from scratch.Here is an example of customised map that does not make use of it. (Notethe use ofquality = "research" to restrict the search to the morereliable observations.)

## A more elaborate map of Colibri sp.colibri<- get_inat_obs(taxon_name="Colibri",quality="research",maxresults=500)ggplot(data=colibri, aes(x=longitude,y=latitude,colour=scientific_name))+  geom_polygon(data= map_data("world"),                   aes(x=long,y=lat,group=group),fill="grey95",color="gray40",size=0.1)+  geom_point(size=0.7,alpha=0.5)+  coord_fixed(xlim= range(colibri$longitude,na.rm=TRUE),ylim= range(colibri$latitude,na.rm=TRUE))+  theme_bw()