ehitk 1.2.0

Earth Hologenome Initiative Toolkit

EHItk

The Earth Hologenome Initiative ToolKit (EHItk) is a Python package and command-line tool for finding, summarizing, exporting, and downloading EHI specimens, hologenomes, and metagenome-assembled genomes.

Installation

pip install ehitk

Example

ehitk specimens query --host-species "Podarcis muralis" --limit 5
ehitk hologenomes query --biome ENVO:01000175 --limit 5
ehitk hologenomes fields
ehitk hologenomes values --field country --limit 10
ehitk mags stats --quality high --species "Escherichia coli"
ehitk mags query --quality high --csv | head
ehitk specimens values --field sex --csv --output-file specimen-sex-values.csv

Python API:

import ehitk

with ehitk.Database() as ehidb:
    mags = ehidb.mags.query(quality="high", host_taxid=40674, limit=5)

for mag in mags:
    print(
        mag.mag_id,
        mag.quality,
        mag.host_taxid,
        mag.host_species,
        mag.mag_family,
        mag.mag_genus,
    )

Documentation

Full installation instructions, command reference, examples, output formats, identifier namespaces, download guidance, and Python API examples are available at:

https://ehitk.readthedocs.io/

Use the built-in help for local command details:

ehitk --help
ehitk specimens --help
ehitk hologenomes fetch --help
ehitk mags query --help

Bundled database and versioning

EHItk ships with a bundled SQLite EHI database, which is the default database used by the command-line interface and Python API. Updating the Python package may therefore also update the default EHI database.

Use ehitk database to inspect the catalog currently in use, including its path, source, size, and SHA256 checksum.

Database updates are paired with documented EHI data releases. Each release produces a standalone ehitk-database-<version>.sqlite artifact and checksum file for GitHub Releases and Zenodo, while the same SQLite file remains bundled inside the matching Python package for convenience. The citable Zenodo database record is available at https://doi.org/10.5281/zenodo.20430293. Older database files can be used to rerun analyses against the same database version by passing the file with --db or by opening it with ehitk.Database("/path/to/ehitk.sqlite").

The public package does not currently rebuild the full curated EHI metadata catalog from upstream sources. Fresh catalogs are obtained by upgrading EHItk or by downloading the versioned database artifact for a specific release.

EHItk package versions follow Semantic Versioning for the software interface. Database updates that change the SQLite schema, remove or rename fields, or otherwise alter command-line or Python API output compatibility are treated as breaking changes and require a major version bump. Non-breaking database additions or metadata corrections are released as minor or patch versions and are documented in the changelog and associated data release notes.

Testing and continuous integration

EHItk includes a pytest-based unit test suite in the tests/ directory. The repository also uses GitHub Actions continuous integration to run the test suite, build source and wheel distributions, and perform CLI smoke tests across Python 3.10, 3.11, 3.12, 3.13, and 3.14.