Taxonomic Filtering#
Callum Waite, Shandiya Balasubramaniam
Taxonomic complexity can confound the process of searching, filtering, and downloading records using galah, but there are a few
ways to ensure records are not missed by using [functions] in galah. Let’s start by configuring galah to the ALA.
>>> import galah
>>> galah.galah_config(atlas="Australia",email="your-email-here")
search_taxa()#
search_taxa() enables users to look up taxonomic names before downloading data, which allows for
disambiguating homonyms and checking that the search term matches the taxon name in the ALA . search_taxa()
returns the scientific name, authorship, rank, and full classification for the taxon matched to the provided
search term.
>>> galah.search_taxa(taxa="Petroica boodang")
atlas in galah_config: Australia
atlas in galah_config again: Australia
[17]
scientificName scientificNameAuthorship taxonConceptID rank matchType kingdom phylum classs order family genus species issues vernacularName
0 Petroica (Petroica) boodang (Lesson, 1838) https://biodiversity.org.au/afd/taxa/a3e5376b-f9e6-4bdf-adae-1e7add9f5c29 species exactMatch Animalia Chordata Aves Passeriformes Petroicidae Petroica Petroica boodang [noIssue] Scarlet Robin
It can also return taxonomic information for multiple species, including synonyms and Indigneous names.
>>> # Muscicapa chrysoptera is a synonym for the Flame Robin, Petroica phoenicea
>>> # Guniibuu is the Yuwaalaraay Indigenous name for the Red-Capped Robin, Petroica goodenovii
>>> galah.search_taxa(taxa = ["Muscicapa chrysoptera", "Guniibuu"])
atlas in galah_config: Australia
atlas in galah_config again: Australia
[17]
[17]
scientificName scientificNameAuthorship taxonConceptID rank matchType kingdom phylum classs order family genus species issues vernacularName
0 Petroica (Littlera) phoenicea Gould, 1837 https://biodiversity.org.au/afd/taxa/fe74e658-4848-437a-a23d-f1001a198552 species exactMatch Animalia Chordata Aves Passeriformes Petroicidae Petroica Petroica phoenicea [noIssue] Flame Robin
1 Petroica (Petroica) goodenovii (Vigors & Horsfield, 1827) https://biodiversity.org.au/afd/taxa/10dbd908-00f3-4ec2-9a9c-a2fd4782eaf1 species vernacularMatch Animalia Chordata Aves Passeriformes Petroicidae Petroica Petroica goodenovii [noIssue] Red-capped Robin
Where homonyms exist, search_taxa() will prompt users to clarify the search term by providing one or more taxonomic
ranks using the search_taxa() argument scientific_name. This example differentiates among the genus Morganella
in three kingdoms:
>>> galah.search_taxa(taxa = ["Morganella"])
atlas in galah_config: Australia
atlas in galah_config again: Australia
[17]
scientificName scientificNameAuthorship taxonConceptID rank matchType kingdom phylum classs order family genus species issues vernacularName
0 Morganella [homonym]
>>> galah.search_taxa(scientific_name={"kingdom": ["Fungi"],"scientificName": ["Morganella"]})
atlas in galah_config: Australia
atlas in galah_config again: Australia
[16]
scientificName scientificNameAuthorship taxonConceptID rank matchType kingdom phylum classs order family genus species issues vernacularName
0 Morganella Zeller https://id.biodiversity.org.au/name/fungi/60015036 genus exactMatch Fungi Basidiomycota Agaricomycetes Agaricales Agaricaceae Morganella noIssue
This disambiguation of the Morganella taxa can then be used by atlas_counts, atlas_occurrences,
atlas_species or atlas_media by providing the keyword scientific_name to any of these functions.
>>> galah.atlas_counts(scientific_name={"kingdom": ["Fungi"],"scientificName": ["Morganella"]})
atlas in galah_config: Australia
atlas in galah_config again: Australia
[19]
[16]
totalRecords
0 189
>>> galah.atlas_occurrences(scientific_name={"kingdom": ["Fungi"],"scientificName": ["Morganella"]})
atlas in galah_config: Australia
atlas in galah_config again: Australia
[23]
[16]
recordID scientificName taxonConceptID decimalLatitude decimalLongitude eventDate dataResourceName occurrenceStatus
0 001ec30d-3376-4f63-ba32-b48bc3dd137d Morganella purpurascens https://id.biodiversity.org.au/name/fungi/60022638 -33.662180 150.270831 2021-04-10T00:00:00Z NSW BioNet Atlas PRESENT
1 005ef5cf-aae1-411c-8476-8ac01dc80e9b Morganella compacta NZOR-6-128055 -36.823429 175.073057 NaN New Zealand Fungal and Plant Disease Collection PRESENT
2 0084789b-e04d-4742-95b5-2e3761d9fd9c Morganella compacta NZOR-6-128055 -38.031754 176.486964 2019-05-14T00:00:00Z New Zealand Fungal and Plant Disease Collection PRESENT
3 00efd1aa-ebf2-4afb-bd4d-b76af6ff0207 Morganella compacta NZOR-6-128055 -41.097594 172.934641 2014-05-01T00:00:00Z New Zealand Fungal and Plant Disease Collection PRESENT
4 05defe84-dc0b-4018-8b25-448ad7d5d33d Morganella purpurascens https://id.biodiversity.org.au/name/fungi/60022638 NaN NaN 1910-04-01T00:00:00Z Royal Botanic Gardens, Kew - Fungarium Specimens PRESENT
.. ... ... ... ... ... ... ... ...
184 f95e41b4-bff3-47e3-bcc3-83662dc500d0 Morganella compacta NZOR-6-128055 -41.271692 173.135924 2004-05-10T00:00:00Z New Zealand Fungal and Plant Disease Collection PRESENT
185 fc2816fd-4b65-4af1-b0a2-1b086c26d97f Morganella purpurascens https://id.biodiversity.org.au/name/fungi/60022638 -26.405958 153.026140 2018-03-16T01:01:09Z ALA species sightings and OzAtlas PRESENT
186 fe8355bf-df6d-47b4-ab8a-33974e4828b5 Morganella purpurascens https://id.biodiversity.org.au/name/fungi/60022638 -33.662180 150.270831 2015-04-09T00:00:00Z NSW BioNet Atlas PRESENT
187 fefa2961-f077-40c1-becb-7fe21a8296ef Morganella compacta NZOR-6-128055 -36.905438 174.562352 1975-07-01T00:00:00Z New Zealand Fungal and Plant Disease Collection PRESENT
188 ff8c59c8-b486-4c9f-ac6b-0e5efc97df22 Morganella purpurascens https://id.biodiversity.org.au/name/fungi/60022638 -27.933286 153.175133 2024-11-26T11:50:00Z iNaturalist Australia PRESENT
[189 rows x 8 columns]
filters=#
filters= subsets records by searching for exact matches to an expression, and may also be used for taxonomic
filtering. for example, if we want to search for multiple species of robins in Australia, we can do this for
single or multiple species. We can also group the multiple species by their species names so we can compare the
number of records for each robin.
>>> galah.atlas_counts(taxa="Petroica boodang")
atlas in galah_config: Australia
atlas in galah_config again: Australia
[19]
[17]
totalRecords
0 175828
>>> aus_petroica = ["Petroica boodang", "Petroica goodenovii",
... "Petroica phoenicea", "Petroica rosea",
... "Petroica rodinogaster", "Petroica multicolor"]
>>> galah.atlas_counts(
... taxa=aus_petroica,
... group_by=["species","vernacularName"]
... )
atlas in galah_config: Australia
atlas in galah_config again: Australia
[19]
[17]
[17]
[17]
[17]
[17]
[17]
species vernacularName count
0 Petroica boodang Eastern Scarlet Robin 28558
1 Petroica boodang Scarlet Robin 111323
2 Petroica boodang South-western Scarlet Robin 14822
3 Petroica boodang Tasmanian Scarlet Robin 21125
4 Petroica goodenovii Red-capped Robin 152622
5 Petroica multicolor Pacific Robin 6873
6 Petroica phoenicea Flame Robin 102367
7 Petroica rodinogaster Mainland Pink Robin 1116
8 Petroica rodinogaster Pink Robin 16806
9 Petroica rodinogaster Tasmanian Pink Robin 4219
10 Petroica rosea Rose Robin 78905
This can be useful in searching for paraphyletic or polyphyletic groups. For example, to get counts of non-chordates:
>>> non_chordates = galah.atlas_counts(
... filters=["kingdom=Animalia","phylum!=Chordata"],
... group_by=["phylum"],
... expand=False
... )
>>> non_chordates.head()
atlas in galah_config: Australia
atlas in galah_config again: Australia
[19]
phylum count
0 Acanthocephala 483
1 Annelida 365284
2 Arthropoda 12525788
3 Brachiopoda 3159
4 Bryozoa 36661
filters=, search_taxa(), and taxonomic ranks#
Deciding between using filters= and search_taxa() in a query comes down to how a record has been classified,
and whether or not you have the correct unique name and classification of the taxa of interest.
The ALA has fields for the primary taxonomic ranks (kingdom, phylum, class, order, family, genus, species) and some
secondary ranks (e.g. subfamily, subgenus), all of which may be used with filters= and search_taxa().
Additionally, there is a field named scientificName, which refers to the lowest taxonomic rank to which a record
has been identified e.g.
>>> import numpy as np
>>> pitta_ranks = galah.atlas_counts(
... taxa="Pitta",
... group_by=["scientificName","taxonRank"]
... )
>>> pitta_ranks = pitta_ranks.loc[pitta_ranks["scientificName"].notnull()]
>>> pitta_ranks
atlas in galah_config: Australia
atlas in galah_config again: Australia
[19]
[17]
scientificName taxonRank count
0 Pitta genus 237
1 Pitta (Erythropitta) subgenus 6
2 Pitta (Erythropitta) erythrogaster species 139
3 Pitta (Erythropitta) erythrogaster digglesi subspecies 1045
4 Pitta (Pitta) iris species 7335
5 Pitta (Pitta) iris iris subspecies 876
6 Pitta (Pitta) iris johnstoneiana subspecies 51
7 Pitta (Pitta) versicolor species 32923
8 Pitta (Pitta) versicolor intermedia subspecies 2418
9 Pitta (Pitta) versicolor simillima subspecies 509
10 Pitta (Pitta) versicolor versicolor subspecies 4418
If, for instance, you have the correct species or subspecies name, then searching for matches against the species
and subspecies fields, respectively, will provide more precise results. This is because the field scientificName
may include subgenera. If you’ve used search_taxa() to get the ALA-matched name of a taxon and only want records
identified to a particular level of classification, searching for matches against scientificName is recommended.
Paraphyletic or polyphyletic groups may contain taxa identified to different taxonomic levels. In this case, it is
simpler to use search_taxa(). In the example below, search_taxa() matches terms to one genus, three species,
and two subspecies. This can then be used in atlas_counts() to get counts for each scientific name.
>>> tas_endemic = ["Sarcophilus", # Tasmanian Devil
... "Bettongia gaimardi", # Tasmanian Bettong
... "Melanodryas vittata", # Dusky Robin
... "Platycercus caledonicus",# Green Rosella
... "Aquila audax fleayi", # Tasmanian Wedge-Tailed Eagle
... "Tyto novaehollandiae castanops" # Tasmanian Masked Owl
... ]
>>> galah.search_taxa(taxa=tas_endemic)
atlas in galah_config: Australia
atlas in galah_config again: Australia
[17]
[17]
[17]
[17]
[17]
[17]
scientificName scientificNameAuthorship taxonConceptID rank matchType kingdom phylum classs order family genus species issues vernacularName
0 Sarcophilus Cuvier, 1837 https://biodiversity.org.au/afd/taxa/aa40a75d-d499-4339-8a5d-c333a29cea1c genus exactMatch Animalia Chordata Mammalia Dasyuromorphia Dasyuridae Sarcophilus [noIssue]
1 Bettongia gaimardi (Desmarest, 1822) https://biodiversity.org.au/afd/taxa/8f7da937-6338-4c39-8b11-4f83807afe11 species exactMatch Animalia Chordata Mammalia Diprotodontia Potoroidae Bettongia Bettongia gaimardi [noIssue] Tasmanian Bettong
2 Melanodryas (Amaurodryas) vittata (Quoy & Gaimard, 1830) https://biodiversity.org.au/afd/taxa/0f04889f-5489-4369-a545-8a041fba9f6d species exactMatch Animalia Chordata Aves Passeriformes Petroicidae Melanodryas Melanodryas vittata [noIssue] Dusky Robin
3 Platycercus (Platycercus) caledonicus (Gmelin, 1788) https://biodiversity.org.au/afd/taxa/c6e478fe-f199-463f-8576-a77108fd73e2 species exactMatch Animalia Chordata Aves Psittaciformes Psittacidae Platycercus Platycercus caledonicus [noIssue] Green Rosella
4 Aquila (Uroaetus) audax fleayi Condon & Amadon, 1954 https://biodiversity.org.au/afd/taxa/ac93f7f0-0686-4589-801a-5832378cb7c1 subspecies exactMatch Animalia Chordata Aves Accipitriformes Accipitridae Aquila Aquila audax [noIssue] Tasmanian Wedge-tailed Eagle
5 Tyto novaehollandiae castanops (Gould, 1837) https://biodiversity.org.au/afd/taxa/2c30d58b-572b-4dab-8644-b222c28eb0ec subspecies exactMatch Animalia Chordata Aves Strigiformes Tytonidae Tyto Tyto novaehollandiae [noIssue] Tasmanian Masked Owl
>>> galah.atlas_counts(
... taxa=tas_endemic,
... group_by=["scientificName"],
... expand=False
... )
atlas in galah_config: Australia
atlas in galah_config again: Australia
[19]
[17]
[17]
[17]
[17]
[17]
[17]
scientificName count
0 Aquila (Uroaetus) audax fleayi 9767
1 Bettongia gaimardi 2457
2 Bettongia gaimardi cuniculus 54
3 Bettongia gaimardi gaimardi 7
4 Melanodryas (Amaurodryas) vittata 13773
5 Melanodryas (Amaurodryas) vittata kingi 752
6 Melanodryas (Amaurodryas) vittata vittata 7799
7 Platycercus (Platycercus) caledonicus 50600
8 Platycercus (Platycercus) caledonicus brownii 478
9 Platycercus (Platycercus) caledonicus caledonicus 32214
10 Sarcophilus 112
11 Sarcophilus harrisii 36904
12 Tyto novaehollandiae castanops 335