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")
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"])
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"])
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"]})
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"]})
totalRecords
0 189
>>> galah.atlas_occurrences(scientific_name={"kingdom": ["Fungi"],"scientificName": ["Morganella"]})
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")
totalRecords
0 177293
>>> aus_petroica = ["Petroica boodang", "Petroica goodenovii",
... "Petroica phoenicea", "Petroica rosea",
... "Petroica rodinogaster", "Petroica multicolor"]
>>> galah.atlas_counts(
... taxa=aus_petroica,
... group_by=["species","vernacularName"]
... )
species vernacularName count
0 Petroica boodang Eastern Scarlet Robin 29223
1 Petroica boodang Scarlet Robin 114250
2 Petroica boodang South-western Scarlet Robin 13290
3 Petroica boodang Tasmanian Scarlet Robin 20530
4 Petroica goodenovii Red-capped Robin 153082
5 Petroica multicolor Pacific Robin 6871
6 Petroica phoenicea Flame Robin 103923
7 Petroica rodinogaster Mainland Pink Robin 1105
8 Petroica rodinogaster Pink Robin 16935
9 Petroica rodinogaster Tasmanian Pink Robin 3877
10 Petroica rosea Rose Robin 78737
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()
phylum count
0 Acanthocephala 486
1 Annelida 363788
2 Arthropoda 12296970
3 Brachiopoda 3153
4 Bryozoa 36455
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
scientificName taxonRank count
0 Pitta genus 236
1 Pitta (Erythropitta) subgenus 6
2 Pitta (Erythropitta) erythrogaster species 139
3 Pitta (Erythropitta) erythrogaster digglesi subspecies 1045
4 Pitta (Pitta) iris species 7322
5 Pitta (Pitta) iris iris subspecies 858
6 Pitta (Pitta) iris johnstoneiana subspecies 50
7 Pitta (Pitta) versicolor species 32832
8 Pitta (Pitta) versicolor intermedia subspecies 2293
9 Pitta (Pitta) versicolor simillima subspecies 504
10 Pitta (Pitta) versicolor versicolor subspecies 4199
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)
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
... )
scientificName count
0 Aquila (Uroaetus) audax fleayi 9465
1 Bettongia gaimardi 2452
2 Bettongia gaimardi cuniculus 54
3 Bettongia gaimardi gaimardi 9
4 Melanodryas (Amaurodryas) vittata 13757
5 Melanodryas (Amaurodryas) vittata kingi 729
6 Melanodryas (Amaurodryas) vittata vittata 7499
7 Platycercus (Platycercus) caledonicus 50504
8 Platycercus (Platycercus) caledonicus brownii 447
9 Platycercus (Platycercus) caledonicus caledonicus 30104
10 Sarcophilus 112
11 Sarcophilus harrisii 36879
12 Tyto novaehollandiae castanops 322