Tutorial 1: Observations¶
This notebook will give a quick introduction to things you can do using data from your own iNaturalist observations.
[1]:
from datetime import datetime, timedelta
import ipyplot
from dateutil.relativedelta import relativedelta
from IPython.display import Image
from pyinaturalist import (
ICONIC_TAXA,
Observation,
TaxonCount,
UserCount,
enable_logging,
get_observation_histogram,
get_observation_identifiers,
get_observation_observers,
get_observation_species_counts,
get_observations,
pprint,
)
from rich import print
enable_logging()
Basic observation search¶
We’ll start with the observation search page. get_observations() supports all the same search filters as the ones you see on iNaturalist.org:
Let’s start by searching for all of your own observations:
[2]:
# Replace with your own username
USERNAME = 'jkcook'
response = get_observations(user_id=USERNAME, page='all')
my_observations = Observation.from_json_list(response)
Observation data¶
Take a look at one of the observations to see what information it contains:
[3]:
print(my_observations[0])
Observation( id=30688807, created_at=datetime.datetime(2019, 8, 12, 15, 22, 47, tzinfo=tzlocal()), captive=False, community_taxon_id=78444, description='Located in Green Meadows West Prairie\n\nSpecies IDs:\nhttps://sites.google.com/site/gmwprairie/gmw-prairie-flora', faves=[], geoprivacy=None, identifications_count=1, identifications_most_agree=True, identifications_most_disagree=False, identifications_some_agree=True, license_code='CC-BY-NC', location=(41.67206561, -93.72957587), mappable=True, num_identification_agreements=1, num_identification_disagreements=0, oauth_application_id=2, obscured=False, observed_on=datetime.datetime(2019, 8, 12, 10, 16, tzinfo=tzoffset('Etc/UTC', 0)), outlinks=[{'source': 'GBIF', 'url': 'http://www.gbif.org/occurrence/2429228652'}], out_of_range=None, owners_identification_from_vision=False, place_guess='Johnston, IA, USA', place_ids=[ 1, 24, 1582, 9853, 59613, 64422, 64423, 66741, 82256, 97394, 116535, 129109, 137509, 154492, 155074 ], positional_accuracy=12, preferences={'prefers_community_taxon': None}, project_ids=[48611], project_ids_with_curator_id=[], project_ids_without_curator_id=[48611], public_positional_accuracy=12, quality_grade='research', quality_metrics=[], reviewed_by=[1436999, 2115051], site_id=1, sounds=[], species_guess='Rocky Mountain bee plant', tags=[], updated_at=datetime.datetime(2019, 10, 16, 3, 43, 4, tzinfo=tzlocal()), uri='https://www.inaturalist.org/observations/30688807', uuid='aea799e1-4754-4eaf-adca-84720cdeaeb2', votes=[], annotations=[ [12] 12|13 (0 votes) ], comments=[], identifications=[ [66501609] 🌱 Species: Peritoma serrulata (Rocky Mountain beeplant) (improving) added on Aug 12, 2019 by jkcook, [74656703] 🌱 Species: Peritoma serrulata (Rocky Mountain beeplant) (supporting) added on Oct 16, 2019 by colincroft ], ofvs=[], photos=[ [47956314] https://inaturalist-open-data.s3.amazonaws.com/photos/47956314/original.jpeg?1565623377 (CC-BY-NC, 1365x2048) ], project_observations=[ ProjectObservation(id=33209242, preferences={'allows_curator_coordinate_access': True}, project={'id': 48611}, user_id=2115051, uuid='0ae36f62-59e8-4b90-affd-eb1ddb437262') ], taxon=[78444] 🌱 Species: Peritoma serrulata (Rocky Mountain beeplant), user=[2115051] jkcook (Jordan Cook) )
Observation data compared to the web UI¶
Here is how some of those fields correspond to what you see on an observation page on iNaturalist.org: 
You’ll notice that there are many more fields available; see the Observation docs for a complete list.
Previewing data¶
In many cases, you will want to quickly preview API results without looking through the full details for each result. pyinaturalist.pprint() can be used to show a condensed table of almost all response types. Here’s an example with just the first 30 results:
[4]:
pprint(my_observations[:30])
ID Taxon ID Taxon Observed on User Location ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 30688807 78444 🌱 Species: Peritom… Aug 12, 2019 jkcook Johnston, IA, USA serrulata (Rocky Mountain beeplant) 30688955 47912 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Asclepias tuberosa (butterfly milkweed) 30689111 60251 🌱 Species: Verbena Aug 12, 2019 jkcook Johnston, IA, USA hastata (blue vervain) 30689221 121968 🌽 Species: Aug 12, 2019 jkcook Johnston, IA, USA Andropogon gerardi (big bluestem) 30689306 121968 🌽 Species: Aug 12, 2019 jkcook Johnston, IA, USA Andropogon gerardi (big bluestem) 30689425 128701 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Desmanthus illinoensis (Illinois bundleflower) 30689463 121976 🌻 Species: Silphiu… Aug 12, 2019 jkcook Johnston, IA, USA laciniatum (compass plant) 30689506 136376 🌻 Species: Aug 12, 2019 jkcook Johnston, IA, USA Rudbeckia triloba (Brown-eyed Susan) 30689603 121976 🌻 Species: Silphiu… Aug 12, 2019 jkcook Johnston, IA, USA laciniatum (compass plant) 30689780 81594 🌾 Species: Elymus Aug 12, 2019 jkcook Johnston, IA, USA hystrix (bottlebrush grass) 30690105 127907 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Chamaecrista fasciculata (partridge pea) 30690175 141767 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Veronicastrum virginicum (Culver's root) 30690204 48678 🌼 Genus: Solidago Aug 12, 2019 jkcook Johnston, IA, USA (goldenrods) 30690327 128701 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Desmanthus illinoensis (Illinois bundleflower) 30726806 127186 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Securigera varia (purple crownvetch) 30727162 128695 🥕 Species: Eryngiu… Aug 12, 2019 jkcook Johnston, IA, USA yuccifolium (rattlesnake master) 30727377 136561 🌾 Form: Elymus Aug 12, 2019 jkcook Johnston, IA, USA canadensis glaucifolius 30727961 48662 🦋 Species: Danaus Aug 12, 2019 jkcook Green Meadows West plexippus (Monarch) Prairie 30728796 120215 🐝 Species: Bombus Aug 12, 2019 jkcook Green Meadows West griseocollis Prairie (Brown-belted Bumble Bee) 30728902 55556 🐛 Species: Aug 12, 2019 jkcook Green Meadows West Oncopeltus fasciatus Prairie (Large Milkweed Bug) 30729015 81599 🌻 Species: Silphiu… Aug 12, 2019 jkcook Green Meadows West perfoliatum (cup Prairie plant) 30729970 47911 🌱 Species: Aug 12, 2019 jkcook Johnston, IA, USA Asclepias syriaca (common milkweed) 30729981 130382 🌻 Species: Aug 12, 2019 jkcook Johnston, IA, USA Heliopsis helianthoides (false sunflower) 30730005 204330 🌱 Species: Iris Aug 12, 2019 jkcook Johnston, IA, USA domestica (Blackberry Lily) 30730009 128695 🥕 Species: Eryngiu… Aug 12, 2019 jkcook Johnston, IA, USA yuccifolium (rattlesnake master) 30730021 54781 🌳 Species: Quercus Aug 12, 2019 jkcook Johnston, IA, USA macrocarpa (bur oak) 30730033 127907 🌱 Species: Aug 12, 2019 jkcook Green Meadows West Chamaecrista Prairie fasciculata (partridge pea) 30730042 48627 🌻 Species: Aug 12, 2019 jkcook Johnston, IA, USA Echinacea purpurea (purple coneflower) 30730087 62741 🌻 Species: Aug 12, 2019 jkcook Johnston, IA, USA Rudbeckia hirta (black-eyed Susan) 30730133 56031 🌱 Genus: Calystegi… Aug 12, 2019 jkcook Green Meadows West (false bindweeds) Prairie
Observation species¶
On iNaturalist.org, the next tab of the observation search page is Species. You can get this information with get_observation_species_counts().
For example, all the frogs and toads observed in Mexico:
Here is how to get that same information from the API:
[5]:
# Note: 6793 is the place ID for Mexico, and 20979 is the taxon ID for the Order Anura
response = get_observation_species_counts(place_id=6793, taxon_id=20979)
Then we can see a preview of the top 10 results:
[6]:
taxa = TaxonCount.from_json_list(response['results'][:10])
pprint(taxa)
ID Rank Scientific name Count ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 24277 species 🐸 Smilisca baudinii 2241 517119 species 🐸 Rhinella horribilis 2005 23933 species 🐸 Hyla arenicolor 1839 65551 species 🐸 Hyla eximia 1764 65860 species 🐸 Incilius valliceps 1553 65849 species 🐸 Incilius nebulifer 877 65975 species 🐸 Lithobates berlandieri 854 135027 species 🐸 Agalychnis dacnicolor 798 554652 species 🐸 Rheohyla miotympanum 797 1148187 species 🐸 Trachycephalus vermiculatus 753
Observation identifiers¶
get_observation identifiers() gets us information shown on the next tab: Identifiers:
[7]:
response = get_observation_identifiers(place_id=6793, taxon_id=20979)
users = UserCount.from_json_list(response['results'][:10])
pprint(users)
ID Username Display name Count ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 22707 coatzin_tutor M. Domínguez-Laso 5392 46681 cris-tzabcan Cristian Olvera 4852 1051916 pedro_nahuat Pedro E. Nahuat-Cervera 2655 17327 yamaneko Rafael Paredes Montesinos 2245 3656 eligarcia-padilla Elí García-Padilla 1894 523033 opuntia24 Miguel A. Chavez Caballero 1726 1315 escalante-pasos Jorge Armín Escalante Pasos 1611 8489 josecamx José Carlos Arenas Monroy 1596 36855 sonoran Chris Grünwald Herp.mx 1534 23647 jhvaldez_tutor Jorge H. Valdez 1454
Observation observers¶
And get_observation observers() gets us information from the Observers tab:
[8]:
response = get_observation_observers(place_id=6793, taxon_id=20979)
users = UserCount.from_json_list(response['results'][:10])
pprint(users)
ID Username Display name Count ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 1051916 pedro_nahuat Pedro E. Nahuat-Cervera 424 28799 luis_diaz-gamboa Luis Díaz-Gamboa 336 71758 andrea_navarro20 Andrea Navarro 332 23647 jhvaldez_tutor Jorge H. Valdez 322 46555 magazhu Cheryl Harleston López Espino 318 5772 juancruzado Juan Cruzado Cortés 311 54220 aplomadobirdy Big Birdy 282 21626 francisco3_ Francisco Farriols Sarabia 201 376395 emmguevara Emmanuel Guevara Lazcano 187 4095390 eric_centenero-alcala Eric Centenero Alcalá 173
Observation photos¶
When you’re working in Jupyter, there are a number of ways to preview observation photos. For these examples, we’ll use your own observation data from the first step in this tutorial.
Viewing individual observation photos¶
Use Photo.show() to see a photo from a single observation:
[9]:
my_observations[-4].photos[0].show()
Observation photo grid¶
We can use ipyplot to preview observation images. Observation.photos contains a list of Photo objects, and we can use those to get a thumnail URL for first photo from each observation. For image labels, just call str(observation) to get a summary of the observation (who/what/when/where).
[10]:
images = [obs.photos[0].thumbnail_url for obs in my_observations[:15]]
labels = [str(obs) for obs in my_observations[:15]]
ipyplot.plot_images(images, labels)
Observation photo grid grouped by iconic taxon¶
We can organize this a bit more by grouping these photos by iconic taxon. Use ipyplot.plot_class_tabs to group by label, and use Observation.taxon.iconic_taxon_name as the image labels:
[11]:
images = [obs.photos[0].thumbnail_url for obs in my_observations]
labels = [obs.taxon.iconic_taxon_name for obs in my_observations]
ipyplot.plot_class_tabs(images, labels, max_imgs_per_tab=15)
Observation histogram¶
Another useful format is the observation histogram, which shows the number of observations over a given interval.
The default is month_of_year, which will show counts of all your observations by month, for all years combined:
[12]:
histogram = get_observation_histogram(user_id=USERNAME)
print(histogram)
{1: 8, 2: 1, 3: 19, 4: 26, 5: 32, 6: 59, 7: 14, 8: 402, 9: 92, 10: 65, 11: 23, 12: 6}
Another option is week:
[13]:
histogram = get_observation_histogram(user_id=USERNAME, interval='week')
# Print just the most recent 10 weeks
for date, count in list(histogram.items())[-10:]:
print(f'{date}: {count}')
2021-04-19 00:00:00: 5
2021-04-26 00:00:00: 0
2021-05-03 00:00:00: 0
2021-05-10 00:00:00: 1
2021-05-17 00:00:00: 0
2021-05-24 00:00:00: 0
2021-05-31 00:00:00: 0
2021-06-07 00:00:00: 1
2021-06-14 00:00:00: 7
2021-06-21 00:00:00: 12
Or month:
[14]:
histogram = get_observation_histogram(user_id=USERNAME, interval='month')
# Print just the most recent 12 months
for date, count in list(histogram.items())[-12:]:
print(f'{date}: {count}')
2020-07-01 00:00:00: 12
2020-08-01 00:00:00: 8
2020-09-01 00:00:00: 8
2020-10-01 00:00:00: 1
2020-11-01 00:00:00: 1
2020-12-01 00:00:00: 0
2021-01-01 00:00:00: 1
2021-02-01 00:00:00: 0
2021-03-01 00:00:00: 3
2021-04-01 00:00:00: 17
2021-05-01 00:00:00: 1
2021-06-01 00:00:00: 20