Tutorial 2: Taxa¶
This notebook will give a quick introduction to searching taxa.
[1]:
import altair as alt
import ipyplot
import pandas as pd
from IPython.display import Image
from pyinaturalist import (
Taxon,
enable_logging,
get_taxa,
get_taxa_autocomplete,
get_taxa_by_id,
pprint,
)
from rich import print
enable_logging()
Basic taxon search¶
The taxa endpoint can be used to search by name, rank, and several other criteria. Let’s say you partially remember either a genus or family name that started with ‘vespi’-something. Use the q parameter to search by name:
[2]:
response = get_taxa(q='vespi', rank=['genus', 'family'])
taxa = Taxon.from_json_list(response)
Taxon data¶
As with observations, there is a lot of information in the response:
[3]:
print(taxa[0])
Taxon( id=52747, ancestor_ids=[ 48460, 1, 47120, 372739, 47158, 184884, 47201, 124417, 326777, 48740, 52747 ], complete_rank=None, complete_species_count=None, created_at=None, current_synonymous_taxon_ids=[], extinct=False, iconic_taxon_id=47158, iconic_taxon_name='Insecta', is_active=True, listed_taxa_count=None, matched_term='Vespidae', name='Vespidae', names=[], observations_count=314925, parent_id=48740, preferred_common_name='Hornets, Paper Wasps, Potter Wasps, and Allies', preferred_establishment_means=None, rank_level=30, rank='family', taxon_changes_count=0, taxon_schemes_count=2, vision=None, wikipedia_summary=None, wikipedia_url='http://en.wikipedia.org/wiki/Vespidae', ancestors=[], children=[], conservation_status=None, conservation_statuses=[], default_photo=[13765] https://inaturalist-open-data.s3.amazonaws.com/photos/13765/original.jpg?1545358964 (CC-BY-NC-SA, 1024x679), establishment_means=None, listed_taxa=[], taxon_photos=[] )
Previewing data¶
And we can get a condensed preview with pprint():
[4]:
pprint(taxa)
ID Rank Scientific name Common name ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 52747 family 🐝 Vespidae Hornets, Paper Wasps, Potter Wasps, and Allies 92786 genus 🐟 Vespicula 84737 genus 🦋 Vespina 250566 genus 🐝 Vespita 646195 genus 🪰 Vespiodes 1007575 genus 🦋 Vespitinea
Searching by parent ID¶
Oh, that’s right, it was ‘Vespidae’! Now let’s find all of its subfamilies. We can run another search by parent ID, using the taxon ID from the results above:
[5]:
response = get_taxa(parent_id=52747)
pprint(response)
ID Rank Scientific name Common name ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 343248 subfamily 🐝 Polistinae Paper Wasps 84738 subfamily 🐝 Vespinae Hornets and Yellowjackets 119344 subfamily 🐝 Eumeninae Potter and Mason Wasps 121511 subfamily 🐝 Masarinae Pollen Wasps 522215 subfamily 🐝 Stenogastrinae Hover Wasps 343388 subfamily 🐝 Euparagiinae
Autocomplete search¶
There is a taxon autocomplete text search endpoint, which is intended for autocomplete interfaces like the one on iNaturalist.org:
But it also provides an easy way to search the iNaturalist taxonomy database by taxon name. Here is a quick example that will run searches from console input. Try a few different searches:
[6]:
while True:
query = input("> ")
if query == 'exit':
break
response = get_taxa_autocomplete(q=query)
pprint(response)
> opilio
ID Rank Scientific name Common name ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 527573 genus 🕷️ Opilio 47367 order 🕷️ Opiliones Harvestmen 84644 species 🕷️ Phalangium opilio European Harvestman 527419 subfamily 🕷️ Opilioninae 527576 species 🕷️ Opilio canestrinii Canestrini's Harvestman 488349 species 🕷️ Rilaena triangularis Spring Harvestman 324310 species 🕷️ Mitopus morio Saddleback Harvestman 527483 species 🕷️ Paroligolophus agrestis 57325 family 🕷️ Sclerosomatidae Sclerosomatid Harvestmen 527479 species 🕷️ Oligolophus tridens
> coleo
ID Rank Scientific name Common name ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 372759 subclass 🐙 Coleoidea Octopuses, Squids, and Cuttlefishes 47208 order 🪲 Coleoptera Beetles 359229 species 🦋 Coleotechnites florae Coleotechnites Flower Moth 126268 genus 🐞 Coleomegilla 126267 species 🐞 Coleomegilla maculata Spotted Pink Ladybeetle 53502 genus 🌼 Brickellia brickellbushes 85704 family 🦋 Coleophoridae Casebearing Moths 479709 subfamily 🦋 Coleophorinae 87566 genus 🦋 Coleophora Casebearers 321675 species 🦋 Coleophora mayrella Metallic Coleophora Moth
> exit