Skip to main content

Tools for taxonomic naming and annotation

Project description

Taxtastic is a python package used to build and maintain reference packages, i.e. collections of reference trees, reference alignments, profiles, and associated taxonomic information.

A script named taxit provides a command line interface:

% taxit -h
usage: taxit [-h] [-V] [-v] [-q]

Creation, validation, and modification of reference packages for use with
`pplacer` and related software.

positional arguments:
    help                Detailed help for actions using `help <action>`
    add_nodes           Add nodes and names to a database
    add_to_taxtable     Add nodes to an existing taxtable csv
    check               Validate a reference package
    composition         Show taxonomic composition of a reference package
    create              Create a reference package
    extract_nodes       Extract nodes from a given source in yaml format
    findcompany         Find company for lonely nodes
    get_descendants     Returns given taxids including descendant taxids
    get_lineage         Calculate the taxonomic lineage of a taxid
    info                Show information about reference packages.
    lineage_table       Create a table of lineages as taxonimic names for a
                        collection of sequences
    lonelynodes         Extracts tax ids of all lonely nodes in a taxtable
    namelookup          Find primary name and tax_id from taxonomic names
    new_database        Download NCBI taxonomy and create a database
                        Find the intersection of a taxtable and a refpkg's
    reroot              Taxonomically reroots a reference package
    rollback            Undo an operation performed on a refpkg
    rollforward         Restore a change to a refpkg immediately after being
    rp                  Resolve path; get the path to a file in the reference
    strip               Remove rollback and rollforward information from a
    taxids              Convert a list of taxonomic names into a recursive
                        list of species
    taxtable            Create a tabular representation of taxonomic lineages
    update              Add or modify files or metadata in a refpkg
    update_taxids       Update obsolete tax_ids

  -h, --help            show this help message and exit
  -V, --version         Print the version number and exit
  -v, --verbose         Increase verbosity of screen output (eg, -v is
                        verbose, -vv more so)
  -q, --quiet           Suppress output


taxtastic requires Python 3.8+. The simplest method of installing is using pip:

pip install taxtastic

We strongly recommend installation into a virtualenv. Instructions for installing the taxtastic package and the taxit command line entry point in a virtualenv are as follows:

python3 -m venv taxtastic-env
source taxtastic-env/bin/activate
pip install -U pip
pip install taxtastic

If you prefer to install from the git repository:

git clone
cd taxtastic
python3 -m venv taxtastic-env
source taxtastic-env/bin/activate
pip install .

Finally, taxit can be run from a Docker image hosted in the GitHub Container Registry. For example, to create a new sqlite database:

docker run --rm -it -v $(pwd):/opt/run --platform=linux/amd64 taxit new_database ncbi_taxonomy.db

Note that initial database creation (at least on MacOS using amd64 emulation) is very slow using Docker and is not recommended.

A note on databases

This project supports both sqlite3 and postgresql as database backends. For most applications, we recommend sqlite3: some operations (particularly initial database creation) are much faster using sqlite3.


Taxtastic uses recursive common table expressions to query the taxonomy database, which requires that the Python sqlite3 module is built against sqlite3 library version of 3.8.3 or higher ( You can check the version like this:

python3 -c 'import sqlite3; print(sqlite3.sqlite_version)'


Despite some recent optimizations as of version v0.10 (in which indexes and constraints are dropped before creating the taxonomy database), operations in Postgres are somewhat slower. Note that the default Postgres configuration on MacOS is likely to be quite resource constrained; consider tuning your database configuration by consulting a site such as PGTune (

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

taxtastic-0.10.0.tar.gz (85.8 kB view hashes)

Uploaded Source

Built Distribution

taxtastic-0.10.0-py3-none-any.whl (91.3 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page