BirdVoxClassify taxonomy¶
Introduction¶
In the context of the BirdVox project, we limit the taxonomical scope
to a subset of bird species. This subset is formalized via a taxonomy file which is used to both specify
what species we are interested in as well as describing the output of a particular model using the
taxonomy. In fact, model names refer to the taxonomy they use (as well as the MD5 checksum of the
taxonomy file) in their filenames. For example, the model with ID
birdvoxclassify-flat-multitask-convnet_tv1hierarchical-3c6d869456b2705ea5805b6b7d08f870
uses the taxonomy
tv1hierarchical
, which has an MD5 checksum of 3c6d869456b2705ea5805b6b7d08f870
. Generally, a model name
is in the format <model identifier>_<taxonomy name>-<taxonomy md5 checksum>
.
v0.3.1 UPDATE: model names with taxonomy md5sum ``2e7e1bbd434a35b3961e315cfe3832fc`` or ``beb9234f0e13a34c7ac41db72e85addd`` are not available in this version but are restored in v0.3.1 for backwards compatibility. They will no longer be supported starting with v0.4. Please use model names with taxonomy md5 checksums ``3c6d869456b2705ea5805b6b7d08f870`` and ``2f6efd9017669ef5198e48d8ec7dce4c`` (respectively) instead.
Overview¶
The primary taxonomy currently used (v1hierarchical
) is as such:
- [0] Other - Coarse (Non-passerine)
- [1] Passerines
- [1.0] Other - Medium (Other Passerine)
- [1.1] American Sparrow
- [1.1.0] Other - Fine (Other American Sparrow)
- [1.1.1] ATSP (American Tree Sparrow)
- [1.1.2] CHSP (Chipping Sparrow)
- [1.1.3] SAVS (Savannah Sparrow)
- [1.1.4] WTSP (White-throated Sparrow)
- [1.1.X] Unknown - Fine (Unknown American Sparrow)
- [1.2] Cardinal
- [1.2.0] Other - Fine (Other Cardinal)
- [1.2.1] RBGR (Rose-breasted Grosbeak)
- [1.2.X] Unknown - Fine (Unknown Cardinal)
- [1.3] Thrush
- [1.3.0] Other - Fine (Other Thrush)
- [1.3.1] GCTH (Gray-cheeked Thrush)
- [1.3.2] SWTH (Swainson’s Thrush)
- [1.3.X] Unknown - Fine (Unknown Thrush)
- [1.4] Warbler
- [1.4.0] Other - Fine (Other Warbler)
- [1.4.1] AMRE (American Redstart)
- [1.4.2] BBWA (Bay-breasted Warbler)
- [1.4.3] BTBW (Black-throated Blue Warbler)
- [1.4.4] CAWA (Canada Warbler)
- [1.4.5] COYE (Common Yellowthroat)
- [1.4.6] MOWA (Mourning Warbler)
- [1.4.7] OVEN (Ovenbird)
- [1.4.X] Unknown - Fine (Unknown Warbler)
- [1.X] Unknown - Medium (Unknown Passerine)
- [X] Unknown - Coarse (Unknown bird)
Note that all species have a fully qualified three-digit taxonomy code. Each digit corresponds to
the respective values of each species within our three level taxonomy, corresponding roughly to the standard
taxonomical groupings “order”, “family”, and “species”. N-digit taxonomy codes (e.g. for N < 3) correspond to
higher level concepts in the taxonomy (such as family). Any N-digit taxonomy code ending in a 0
corresponds to
an “other” class, simply meaning it is outside our scope of interest. For example, 1.0
corresponds to an
“other Passerine” meaning a Passerine that is not a member of the families of interest. Similarly, any N-digit taxonomy
code ending in an X
corresponds to an “unknown” class, meaning that the annotator could not determine the
identity of a particular bird at that level of the taxonomy. For example, 1.1.X
corresponds to an American
Sparrow for which the annotator was unsure of the particular species.
Taxonomy format¶
The taxonomy is specified in JSON format. The taxonomy files can be found in
<BirdVoxClassify dir>/resources/taxonomy/
.
{
"taxonomy": [
{
"id": <str>, // Numeric taxonomic ID
"common_name": <str>, // Common name
"scientific_name": <str>, // Latin name
"taxonomy_level_names": <str>, // Level of taxonomy
"taxonomy_level_aliases": {
},
"child_ids": [
<str>, // Child taxonomic IDs
...
]
},
...
],
"output_encoding": {
<str>: [ // Name of level of taxonomy
// Ordered list of outputs
{
"ids": [
<str>, // List of taxonomic IDs encapsulated in this output
...
]
},
...
{
"ids": [
<str>, // Last output should encompass all "other" classes
...
]
}
],
}
The taxonomy
field contains nodes of the tree of the taxonomy. each of which contain the N-digit taxonomy reference
ID, identifying information and aliases about the node, and the IDs of children nodes in the taxonomy.
output_encoding
specifies the taxonomy IDs associated with each element of an output probability vector produced
by a classifier using this taxonomy. The order of the list associated with each level of the taxonomy
corresponds to the position in an output vector.
Output format¶
Model output is given as JSON:
{
<prediction level> : {
<taxonomy id> : {
"probability": <float>,
"common_name": <str>,
"scientific_name": <str>,
"taxonomy_level_names": <str>,
"taxonomy_level_aliases": <dict of aliases>,
"child_ids": []
},
...
"other" : {
"common_name": "other",
"scientific_name": "other",
"taxonomy_level_names": level,
"taxonomy_level_aliases": {},
"child_ids": <list of children IDs>
}
},
...
}
The probabilities at each prediction level. For a summary file, containing predictions for multiple files the output is given as:
{
<filename> : {
<output node>
},
...
}