{"id":37639904,"url":"https://github.com/imageomics/taxonopy","last_synced_at":"2026-02-12T23:01:30.588Z","repository":{"id":295136934,"uuid":"789041700","full_name":"Imageomics/TaxonoPy","owner":"Imageomics","description":"A Python package for efficiently aligning organismal taxonomic hierarchies using the Global Names Verifier","archived":false,"fork":false,"pushed_at":"2026-02-04T20:10:29.000Z","size":1077,"stargazers_count":10,"open_issues_count":12,"forks_count":0,"subscribers_count":5,"default_branch":"main","last_synced_at":"2026-02-05T08:25:39.504Z","etag":null,"topics":["alignment","hierarchy","taxonomic-resolution","taxonomy","tree-of-life"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Imageomics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2024-04-19T15:37:30.000Z","updated_at":"2026-01-16T17:26:18.000Z","dependencies_parsed_at":"2026-02-12T23:00:48.022Z","dependency_job_id":null,"html_url":"https://github.com/Imageomics/TaxonoPy","commit_stats":null,"previous_names":["imageomics/taxonopy"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/Imageomics/TaxonoPy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imageomics%2FTaxonoPy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imageomics%2FTaxonoPy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imageomics%2FTaxonoPy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imageomics%2FTaxonoPy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Imageomics","download_url":"https://codeload.github.com/Imageomics/TaxonoPy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Imageomics%2FTaxonoPy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29385001,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-12T22:07:52.078Z","status":"ssl_error","status_checked_at":"2026-02-12T22:07:49.026Z","response_time":55,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alignment","hierarchy","taxonomic-resolution","taxonomy","tree-of-life"],"created_at":"2026-01-16T11:15:39.880Z","updated_at":"2026-02-12T23:01:30.583Z","avatar_url":"https://github.com/Imageomics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TaxonoPy\n\n[![DOI](https://zenodo.org/badge/789041700.svg)](https://doi.org/10.5281/zenodo.15499454)\n\n[![PyPI - Version](https://img.shields.io/pypi/v/taxonopy.svg)](https://pypi.org/project/taxonopy)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/taxonopy.svg)](https://pypi.org/project/taxonopy)\n\n`TaxonoPy` (taxon-o-py) is a command-line tool for creating an internally consistent taxonomic hierarchy using the [Global Names Verifier (gnverifier)](https://github.com/gnames/gnverifier). See below for the structure of inputs and outputs.\n\n## Purpose\nThe motivation for this package is to create an internally consistent and standardized classification set for organisms in a large biodiversity dataset composed from different data providers that may use very similar and overlapping but not identical taxonomic hierarchies.\n\nIts development has been driven by its application in the TreeOfLife-200M (TOL) dataset. This dataset contains over 200 million samples of organisms from four core data providers:\n\n- [The Global Biodiversity Information Facility (GBIF)](https://www.gbif.org/)\n- [BIOSCAN-5M](https://biodiversitygenomics.net/projects/5m-insects/)\n- [FathomNet](https://www.fathomnet.org/)\n- [The Encyclopedia of Life (EOL)](https://eol.org/)\n\nThe names (and classification) of taxa may be (and often are) inconsistent across these resources. This package addresses this problem by creating an internally consistent classification set for such taxa. \n\n### Input\n\nA directory containing Parquet partitions of the seven-rank Linnaean taxonomic metadata for organisms in the dataset. Labels should include:\n- `uuid`: a unique identifier for each sample (required).\n- `kingdom`, `phylum`, `class`, `order`, `family`, `genus`, `species`: the taxonomic ranks of the organism (required, may have sparsity).\n- `scientific_name`: the scientific name of the organism, to the most specific rank available (optional).\n- `common_name`: the common (i.e. vernacular) name of the organism (optional).\n\nSee the example data in \n- `examples/input/sample.parquet`\n- `examples/resolved/sample.resolved.parquet` (generated with [`taxonopy resolve`](#command-resolve))\n- `examples/resolved_with_common_names/sample.resolved.parquet` (generated with [`taxonopy common-names`](#command-common-names))\n\n### Challenges\nThis taxonomy information is provided by each data provider and the original sources, but the classification can be...\n\n- **Inconsistent**: both between and within sources (e.g. kingdom Metazoa vs. Animalia).\n- **Incomplete**: many samples are missing one or more ranks. Some have 'holes' where higher and lower ranks are present, but intermediate ranks are missing.\n- **Incorrect**: some samples have incorrect classifications. This can come in the form of spelling errors, nonstandard ideosyncratic terms, or outdated classifications.\n- **Ambiguous**: homonyms, synonyms, and other terms that can be interpreted in multiple ways unless handled systematically.\n\nTaxonomic authorities exist to standardize classification, but ...\n- There are many authorities.\n- They may disagree.\n- A given organism may be missing from some.\n\n### Solution\n`TaxonoPy` uses the taxonomic hierarchies provided by the TOL core data providers to query GNVerifier and create a standardized classification for each sample in the TOL dataset. It prioritizes the [GBIF Backbone Taxonomy](https://verifier.globalnames.org/data_sources/11), since this represents the largest part of the TOL dataset. Where GBIF misses, backup sources such as the [Catalogue of Life](https://verifier.globalnames.org/data_sources/1) and [Open Tree of Life (OTOL) Reference Taxonomy](https://verifier.globalnames.org/data_sources/179) are used.\n\n## Installation\n\n`TaxonoPy` can be installed with `pip` after setting up a virtual environment.\n\n### User Installation with `pip`\n\nTo install the latest version of `TaxonoPy`, run:\n```console\npip install taxonopy\n```\n\n### Usage\nYou may view the help for the command line interface by running:\n```console\ntaxonopy --help\n```\nThis will show you the available commands and options:\n```console\nusage: taxonopy [-h] [--cache-dir CACHE_DIR] [--cache-input CACHE_INPUT]\n                [--show-cache-path] [--cache-stats] [--clear-cache]\n                [--show-config] [--version]\n                {resolve,trace,common-names} ...\n\nTaxonoPy: Resolve taxonomic names using GNVerifier and trace data provenance.\n\npositional arguments:\n  {resolve,trace,common-names}\n    resolve             Run the taxonomic resolution workflow\n    trace               Trace data provenance of TaxonoPy objects\n    common-names        Merge vernacular names (post-process) into resolved outputs\n\noptions:\n  -h, --help            show this help message and exit\n  --cache-dir CACHE_DIR\n                        Directory for TaxonoPy cache (can also be set with TAXONOPY_CACHE_DIR environment variable) (default: None)\n  --cache-input CACHE_INPUT\n                        Input dataset path to compute cache stats for when no command is provided (default: None)\n  --show-cache-path     Display the current cache directory path and exit (default: False)\n  --cache-stats         Display statistics about the cache and exit (default: False)\n  --clear-cache         Clear the TaxonoPy object cache. May be used in isolation. (default: False)\n  --show-config         Show current configuration and exit (default: False)\n  --version             Show version number and exit\n```\n\n### Cache behavior\n\n`taxonopy resolve` caches parsed entries, entry groups, and every resolution attempt chain using [`diskcache`](https://grantjenks.com/docs/diskcache/) as a stable provenance artifact tied to the TaxonoPy version and input dataset. By default the cache root is `~/.cache/taxonopy`, but you can override it by setting the environment variable `TAXONOPY_CACHE_DIR` or specifying `--cache-dir`. Its primary purpose is to support the `trace` command, which allows you to trace the provenance of any taxonomic entry resolved by TaxonoPy.\n\n- Each resolve run writes into `resolve_v\u003cversion\u003e_\u003cfingerprint\u003e` where the fingerprint is a SHA-256 hash of the input files’ metadata, so namespaces stay stable per combination of dataset and package version.\n- Inspect a namespace without rerunning by invoking `taxonopy --cache-dir \u003croot\u003e --cache-input \u003cinput\u003e --cache-stats`, which reports total size, entry counts, and key-prefix breakdowns. Passing `--cache-stats` after `resolve` or `trace` performs the same check and exits.\n- If both the namespace and the output directory already contain data, `taxonopy resolve` warns and exits unless you pass `--full-rerun`, which clears the cache namespace and output before proceeding. Use `--clear-cache` to wipe only the namespace.\n\n#### Command: `resolve`\nThe `resolve` command is used to perform taxonomic resolution on a dataset. It takes a directory of Parquet partitions as input and outputs a directory of resolved Parquet partitions.\n```\nusage: taxonopy resolve [-h] -i INPUT -o OUTPUT_DIR\n                        [--output-format {csv,parquet}]\n                        [--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}]\n                        [--log-file LOG_FILE] [--force-input] [--full-rerun]\n                        [--batch-size BATCH_SIZE] [--all-matches]\n                        [--capitalize] [--fuzzy-uninomial] [--fuzzy-relaxed]\n                        [--species-group] [--refresh-cache] [--cache-stats]\n\noptions:\n  -h, --help            show this help message and exit\n  -i, --input INPUT     Path to input Parquet or CSV file/directory\n  -o, --output-dir OUTPUT_DIR\n                        Directory to save resolved and unsolved output files\n  --output-format {csv,parquet}\n                        Output file format\n  --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}\n                        Set logging level\n  --log-file LOG_FILE   Optional file to write logs to\n  --force-input         Force use of input metadata without resolution\n  --full-rerun          Replace existing cache/output if detected for this input\n\nGNVerifier Settings:\n  --batch-size BATCH_SIZE\n                        Max number of name queries per GNVerifier API/subprocess call\n  --all-matches         Return all matches instead of just the best one\n  --capitalize          Capitalize the first letter of each name\n  --fuzzy-uninomial     Enable fuzzy matching for uninomial names\n  --fuzzy-relaxed       Relax fuzzy matching criteria\n  --species-group       Enable group species matching\n\nCache Management:\n  --refresh-cache       Force refresh of cached objects (input parsing, grouping) before running.\n  --cache-stats         Display cache statistics for this input and exit.\n  ```\nIt is recommended to keep GNVerifier settings at their defaults.\n\n#### Command: `trace`\nThe `trace` command is used to trace the provenance of a taxonomic entry. It takes a UUID and an input path as arguments and outputs the full path of the entry through TaxonoPy.\n```console\nusage: taxonopy trace [-h] {entry} ...\n\npositional arguments:\n  {entry}\n    entry     Trace an individual taxonomic entry by UUID\n\noptions:\n  -h, --help  show this help message and exit\n\nusage: taxonopy trace entry [-h] --uuid UUID --from-input FROM_INPUT [--format {json,text}] [--verbose]\n\noptions:\n  -h, --help            show this help message and exit\n  --uuid UUID           UUID of the taxonomic entry\n  --from-input FROM_INPUT\n                        Path to the original input dataset\n  --format {json,text}  Output format\n  --verbose             Show full details including all UUIDs in group\n```\n\n#### Command: `common-names`\nThe `common-names` command is used to merge vernacular names into the resolved output. It takes a directory of resolved Parquet partitions as input and outputs a directory of resolved Parquet partitions with common names.\n```console\nusage: taxonopy common-names [-h] --resolved-dir ANNOTATION_DIR --output-dir OUTPUT_DIR\n\noptions:\n  -h, --help            show this help message and exit\n  --resolved-dir ANNOTATION_DIR\n                        Directory containing your *.resolved.parquet files\n  --output-dir OUTPUT_DIR\n                        Directory to write annotated .parquet files\n```\nNote that the `common-names` command is a post-processing step and should be run after the `resolve` command.\n\n### Example Usage\n\nTo perform taxonomic resolution on a dataset with subsequent common name annotation, run:\n```console\ntaxonopy resolve \\\n    --input /path/to/formatted/input \\\n    --output-dir /path/to/resolved/output\n```\n```console\ntaxonopy common-names \\\n    --resolved-dir /path/to/resolved/output \\\n    --output-dir /path/to/resolved_with_common-names/output\n```\n\n## Development\nSee the [Wiki Development Page](https://github.com/Imageomics/TaxonoPy/wiki/Development) for development instructions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimageomics%2Ftaxonopy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fimageomics%2Ftaxonopy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fimageomics%2Ftaxonopy/lists"}