rinat tutorial

for v0.1.4

rinat is an R wrapper for iNaturalist APIs for accessing the observations. Detailed documentation of the API is available on iNaturlaist website and is part of our larger species occurence searching package SPOCC

Installation

Stable version from CRAN

install.packages("rinat")

Or development version from CRAN

install.packages("devtools")
devtools::install_github("rinat", "ropensci")

Load the package

library("rinat")

Usage

Get observations

Searching

Fuzzy search

You can search for observations either by common or latin name. It will search the entire iNaturalist entry, so the search below will return all entries that mention Monarch butterflies, not just entries for Monarchs.

butterflies <- get_inat_obs(query = "Monarch Butterfly")
head(butterflies[,c(4:6)])
library("ggplot2")

Another use for a fuzzy search is searching for a common name or habitat, e.g. searching for all observations that might occur in a vernal pool. We can then see all the species names found.

vp_obs <- get_inat_obs(query = "vernal pool")
head(vp_obs$species_guess)
#> [1] "Lasthenia glaberrima" "Mitrula elegans"      "green frog"          
#> [4] "Pickerel Frog"        "Pickerel Frog"        "green frog"

Taxon query To return only records for a specific species or taxonomic group, use the taxon option.

## Return just observations in the family Plecoptera
stone_flies <- get_inat_obs(taxon = "Plecoptera")

## Return just Monarch Butterfly records
just_butterflies <- get_inat_obs(taxon = "Danaus plexippus")

Bounding box search

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

Search by area

bounds <- c(38.44047,-125,40.86652, -121.837)
deer <- get_inat_obs(query = "Mule Deer", bounds = bounds)

Other functions

Get information and observations by project

You can get all the observations for a project if you know its ID or name as an intaturalist slug

Just get info about a project

vt_crows <- get_inat_obs_project("crows-in-vermont", type = "info", raw = FALSE)
#> 25  Records
#> 0

Now get all the observations for that project

vt_crows_obs <- get_inat_obs_project(vt_crows$id, type="observations")
#> 25  Records
#> 0-100
head(vt_crows_obs[,c(1:4)])
#>       Id Species.guess       Scientific.name   Common.name
#> 1 192132 American Crow Corvus brachyrhynchos American Crow
#> 2 192169 American Crow Corvus brachyrhynchos American Crow
#> 3 192191 American Crow Corvus brachyrhynchos American Crow
#> 4 183154 American Crow Corvus brachyrhynchos American Crow
#> 5 183364 American Crow Corvus brachyrhynchos American Crow
#> 6 183130 American Crow Corvus brachyrhynchos American Crow

Get observation details

Detailed information about a specific observation can be retrieved by observation ID. The easiest way to get the ID is from a more general search.

m_obs <- get_inat_obs(query = "Monarch Butterfly")
head(get_inat_obs_id(m_obs$id[1]))
#> $id
#> [1] 1265521
#> 
#> $taxon_id
#> [1] 48662
#> 
#> $user_id
#> [1] 5327
#> 
#> $observed_on
#> [1] "2007-09-03"
#> 
#> $description
#> [1] ""
#> 
#> $latitude
#> [1] "38.332463"

Get all observations by user

If you just want all the observations by a user you can download them with a user ID. A word of warning though, this can be quite large (easily into the 1000s)

m_obs <- get_inat_obs(query="Monarch Butterfly")
head(get_inat_obs_user(as.character(m_obs$user_login[1]),maxresults=20))[,1:5]
#>        scientific_name                  datetime          description
#> 1   Hericium erinaceus 2015-02-03 00:00:00 -0800                     
#> 2            Pleurotus 2015-01-22 00:00:00 -0800                     
#> 3 Sarcoscypha coccinea 2015-01-10 00:00:00 -0800                     
#> 4              Ramaria 2015-01-10 00:00:00 -0800                     
#> 5   Hygrocybe coccinea 2015-01-10 00:00:00 -0800                     
#> 6              Amanita 2015-01-10 00:00:00 -0800 Maybe yellow-veiled.
#>                     place_guess latitude
#> 1        Jack London State Park 38.34700
#> 2   Hood Mountain Regional Park 38.48759
#> 3 Point Reyes National Seashore 38.05419
#> 4         Salt Point State Park 38.58397
#> 5         Salt Point State Park 38.58397
#> 6         Salt Point State Park 38.58397

Stats by taxa

Basic statistics are available for taxa counts by date, date range, place ID (numeric ID), or user ID (string)

By date

(counts <- get_inat_taxon_stats(date = "2010-06-14"))
#> $total
#> [1] 65
#> 
#> $species_counts
#>   count taxon.id           taxon.name taxon.rank taxon.rank_level
#> 1     2    17008      Sayornis phoebe    species               10
#> 2     1    11935  Tachycineta bicolor    species               10
#> 3     1    51752     Brodiaea elegans    species               10
#> 4     1    52851     Arnica discoidea    species               10
#> 5     1    81746 Necrophila americana    species               10
#>   taxon.default_name.taxon_id taxon.default_name.lexicon
#> 1                       17008                    English
#> 2                       11935                    English
#> 3                       51752                    English
#> 4                       52851                    English
#> 5                       81746                    English
#>   taxon.default_name.is_valid taxon.default_name.id
#> 1                        TRUE                 20369
#> 2                        TRUE                 14831
#> 3                        TRUE                 82256
#> 4                        TRUE                148530
#> 5                        TRUE                211685
#>   taxon.default_name.position taxon.default_name.name
#> 1                           0          Eastern Phoebe
#> 2                           0            Tree Swallow
#> 3                           0        harvest brodiaea
#> 4                           0          rayless arnica
#> 5                           0 American Carrion Beetle
#>   taxon.default_name.created_at taxon.default_name.updated_at
#> 1 2008-03-12T20:33:20.000-07:00 2008-03-12T20:33:20.000-07:00
#> 2 2008-03-12T20:10:45.000-07:00 2008-03-12T20:10:45.000-07:00
#> 3 2009-06-08T00:00:11.000-07:00 2009-06-08T00:00:11.000-07:00
#> 4 2011-05-17T20:21:12.000-07:00 2011-05-17T20:21:12.000-07:00
#> 5 2011-10-22T04:37:44.842-07:00 2011-10-22T04:37:44.842-07:00
#>                                                  taxon.image_url
#> 1 http://farm6.staticflickr.com/5009/5346970195_d0eac9966b_s.jpg
#> 2   http://farm1.staticflickr.com/177/435466650_1ea6cb197e_s.jpg
#> 3 http://farm4.staticflickr.com/3269/2709963753_b800de8900_s.jpg
#> 4         http://static.inaturalist.org/photos/122558/square.jpg
#> 5 http://farm5.staticflickr.com/4013/4658689710_1a534b47ef_s.jpg
#>   taxon.iconic_taxon_name taxon.conservation_status_name
#> 1                    Aves                  least_concern
#> 2                    Aves                  least_concern
#> 3                 Plantae                           <NA>
#> 4                 Plantae                           <NA>
#> 5                 Insecta                           <NA>
#> 
#> $rank_counts
#> $rank_counts$subspecies
#> [1] 2
#> 
#> $rank_counts$variety
#> [1] 1
#> 
#> $rank_counts$genus
#> [1] 4
#> 
#> $rank_counts$species
#> [1] 58

By place_ID

vt_crows <- get_inat_obs_project("crows-in-vermont", type="info", raw = FALSE)
#> 25  Records
#> 0
place_counts <- get_inat_taxon_stats(place = vt_crows$place_id)
place_counts$total
#> [1] 4730

Stats by user

Similar statistics can be retrived for users. The same input parameters can be used, but results returned are the top five users by species count and observation count.

By date

counts <- get_inat_user_stats(date = "2010-06-14")
counts$most_observations$user[,c(1:3)]
#>       id                    login
#> 1   9706               greglasley
#> 2    357                annetanne
#> 3  10285                  finatic
#> 4  10946                cgcbosque
#> 5  64596 juancarlosgarciamorales1
#> 6  18056                 plantman
#> 7  38530              kevinhintsa
#> 8    382                  tsoleau
#> 9    873                 tapbirds
#> 10  3403                   davidr
#> 11 70352                wonder_al
#> 12  2619                 asnyder5
#> 13  1000                     muir
#> 14 12158            erikamitchell
#> 15 57533      banks_peninsula_tui
#> 16 31399               sacagewea2
#> 17  9560       dianaterryhibbitts
#> 18 11831                  halbyte
#> 19  5239                 marcellc
#> 20 10612                    zieak
#> 21 20727                ciovarnat
#> 22 16823                 jnstuart
#> 23   129               field_daze
#> 24 38442             robertgeorge
#> 25  2048                   josiah
#> 26    10                      jam
#> 27 48178                 asemerdj
#> 28  3926                pmikejack
#> 29  4857          c_michael_hogan
#> 30 65504                scottking
#> 31   206                lfelliott
#> 32 13467           paulalongshore
#> 33 10299               summermule
#> 34 13167                  arleigh
#> 35  2839                    hari2
#>                                                                     user_icon_url
#> 1    http://www.inaturalist.org/attachments/users/icons/9706-thumb.jpg?1412292583
#> 2     http://www.inaturalist.org/attachments/users/icons/357-thumb.jpg?1362061338
#> 3   http://www.inaturalist.org/attachments/users/icons/10285-thumb.jpg?1350000458
#> 4                                                                            <NA>
#> 5   http://www.inaturalist.org/attachments/users/icons/64596-thumb.jpg?1416786295
#> 6                                                                            <NA>
#> 7   http://www.inaturalist.org/attachments/users/icons/38530-thumb.jpg?1400990725
#> 8                http://www.inaturalist.org/attachments/users/icons/382-thumb.jpg
#> 9                http://www.inaturalist.org/attachments/users/icons/873-thumb.jpg
#> 10   http://www.inaturalist.org/attachments/users/icons/3403-thumb.jpg?1394954695
#> 11  http://www.inaturalist.org/attachments/users/icons/70352-thumb.jpg?1421399985
#> 12                                                                           <NA>
#> 13              http://www.inaturalist.org/attachments/users/icons/1000-thumb.jpg
#> 14 http://www.inaturalist.org/attachments/users/icons/12158-thumb.jpeg?1357418870
#> 15 http://www.inaturalist.org/attachments/users/icons/57533-thumb.jpeg?1413332307
#> 16  http://www.inaturalist.org/attachments/users/icons/31399-thumb.jpg?1398521627
#> 17  http://www.inaturalist.org/attachments/users/icons/9560-thumb.jpeg?1351261191
#> 18                                                                           <NA>
#> 19              http://www.inaturalist.org/attachments/users/icons/5239-thumb.jpg
#> 20  http://www.inaturalist.org/attachments/users/icons/10612-thumb.jpg?1375105310
#> 21  http://www.inaturalist.org/attachments/users/icons/20727-thumb.jpg?1398894069
#> 22  http://www.inaturalist.org/attachments/users/icons/16823-thumb.jpg?1383090510
#> 23               http://www.inaturalist.org/attachments/users/icons/129-thumb.jpg
#> 24  http://www.inaturalist.org/attachments/users/icons/38442-thumb.jpg?1400160213
#> 25              http://www.inaturalist.org/attachments/users/icons/2048-thumb.jpg
#> 26                                                                           <NA>
#> 27  http://www.inaturalist.org/attachments/users/icons/48178-thumb.jpg?1416364944
#> 28              http://www.inaturalist.org/attachments/users/icons/3926-thumb.jpg
#> 29              http://www.inaturalist.org/attachments/users/icons/4857-thumb.jpg
#> 30  http://www.inaturalist.org/attachments/users/icons/65504-thumb.jpg?1417720839
#> 31               http://www.inaturalist.org/attachments/users/icons/206-thumb.jpg
#> 32 http://www.inaturalist.org/attachments/users/icons/13467-thumb.jpeg?1361747141
#> 33  http://www.inaturalist.org/attachments/users/icons/10299-thumb.jpg?1350591832
#> 34  http://www.inaturalist.org/attachments/users/icons/13167-thumb.jpg?1361106538
#> 35   http://www.inaturalist.org/attachments/users/icons/2839-thumb.jpg?1398943785

By place_ID

vt_crows <- get_inat_obs_project("crows-in-vermont", type = "info",raw = FALSE)
#> 25  Records
#> 0
place_counts <- get_inat_user_stats(place = vt_crows$place_id)
head(place_counts$most_species$user[,c(1:3)])
#>      id         login
#> 1 12610  susanelliott
#> 2 11792     kylejones
#> 3 12158 erikamitchell
#> 4 12045      larry522
#> 5   317   kpmcfarland
#> 6  2179       charlie
#>                                                                    user_icon_url
#> 1  http://www.inaturalist.org/attachments/users/icons/12610-thumb.jpg?1390441055
#> 2  http://www.inaturalist.org/attachments/users/icons/11792-thumb.jpg?1394793142
#> 3 http://www.inaturalist.org/attachments/users/icons/12158-thumb.jpeg?1357418870
#> 4  http://www.inaturalist.org/attachments/users/icons/12045-thumb.jpg?1357252118
#> 5    http://www.inaturalist.org/attachments/users/icons/317-thumb.jpg?1373935791
#> 6   http://www.inaturalist.org/attachments/users/icons/2179-thumb.jpg?1416962625

Citing

To cite rinat in publications use:


Vijay Barve and Edmund Hart (2014). rinat: Access iNaturalist data through APIs. R package version 0.1.4.

License and bugs

Back to top

comments powered by Disqus