kg_microbe.transform_utils.gtdb package

Submodules

kg_microbe.transform_utils.gtdb.gtdb module

Transform GTDB taxonomy and genome data into KGX format.

class kg_microbe.transform_utils.gtdb.gtdb.GTDBTransform(input_dir=None, output_dir=None)

Bases: Transform

Transform GTDB taxonomy and genome data into KGX format.

DATA_INPUTS: tuple = ('data/raw/taxdump.tar.gz',)

Repo-relative curation files this transform reads, beyond its own data/raw/ download.

Declared so freshness tooling can tell that an output is stale against its data rather than only its code. Without it a mapping correction lands, every consumer keeps reporting FRESH, and a re-merge silently ships the old groundings: #778 corrected 16 isolation-source ids and #786 rewrote the unified chemical SSSOM, and the merged KG built afterwards still asserted 75 organisms isolated from a “Cell Line”, because nothing re-ran the transforms that read those files (#812).

Paths are relative to the repo root. Keep them tracked in git — the freshness check uses commit time, not mtime, because git checkout rewrites mtimes without changing content (#797).

List every curation file read, not a representative one. A partial declaration fails silently and looks identical to a complete one: ontologies_stubs declared 1 of the 11 files it read and was reported fresh after changes to the other ten (#839). Where the set comes from a constant, derive this from it rather than restating it.

run(data_file=None, show_status=True)

Run the GTDB transform.

Process: 1. Load and parse taxonomy files 2. Extract unique taxa and build hierarchy 3. Load metadata for NCBI mappings 4. Create genome nodes 5. Write output files

kg_microbe.transform_utils.gtdb.utils module

Helper functions for parsing GTDB data.

kg_microbe.transform_utils.gtdb.utils.assembly_archive(accession)

Return the archive an assembly accession belongs to.

Args:

accession: “RS_GCF_000005845.2” or “GCA_000008865.2”

Returns:

str: “RefSeq”, “GenBank”, or “NCBI Assembly” when the accession is neither shape.

kg_microbe.transform_utils.gtdb.utils.assembly_curie(accession)

Return the ncbi.assembly: CURIE for a GTDB accession.

The version suffix is kept: GCA_000005845.1 and .2 are different assemblies of the same genome, and no NCBI resolver accepts a version-less accession, so dropping it made the identifier both ambiguous and unresolvable (#882). GTDB’s own RS_/GB_ prefix is not part of the NCBI identifier and is dropped; GCF_ vs GCA_ already says which archive the accession belongs to.

Args:

accession: “RS_GCF_000005845.2” or “GCA_000008865.2”

Returns:

str: “ncbi.assembly:GCF_000005845.2”

kg_microbe.transform_utils.gtdb.utils.clean_taxon_name(taxon_name)

Clean taxon name into the canonical GTDB local identifier form.

Replaces spaces with underscores. The output is also the local ID for the GTDB: CURIE (e.g. GTDB:s__Escherichia_coli), matching the Bioregistry-registered format for GTDB (regex ^[cdfgops]__\w+\S+$, URI pattern https://gtdb.ecogenomic.org/tree?r={id}).

Note: GTDB taxon names are only “best effort” stable across releases (per GTDB’s own FAQ), so consumers should pair the CURIE with a release label (e.g. via provided_by or release-tagged provenance).

Args:

taxon_name: “s__Escherichia coli”

Returns:

“s__Escherichia_coli”

kg_microbe.transform_utils.gtdb.utils.extract_accession_type(accession)

Extract accession type (GCF or GCA) from accession string.

Args:

accession: “RS_GCF_000005845.2” or “GB_GCA_000008865.2” or “GCF_000005845.2”

Returns:

tuple: (“GCF_000005845”, “2”) or (“GCA_000008865”, “2”)

kg_microbe.transform_utils.gtdb.utils.parse_taxonomy_string(taxonomy_str)

Parse GTDB taxonomy string into list of taxa.

Args:

taxonomy_str: “d__Bacteria;p__Proteobacteria;c__Gammaproteobacteria;…”

Returns:

List of taxon names: [“d__Bacteria”, “p__Proteobacteria”, …]

kg_microbe.transform_utils.gtdb.utils.strip_gtdb_prefix(accession)

Return a GTDB accession without its archive prefix, version intact.

Args:

accession: “RS_GCF_000005845.2”, “GB_GCA_000008865.2” or “GCF_000005845.2”

Returns:

str: “GCF_000005845.2” / “GCA_000008865.2” / “GCF_000005845.2”

Module contents

GTDB taxonomy transform.

class kg_microbe.transform_utils.gtdb.GTDBTransform(input_dir=None, output_dir=None)

Bases: Transform

Transform GTDB taxonomy and genome data into KGX format.

DATA_INPUTS: tuple = ('data/raw/taxdump.tar.gz',)

Repo-relative curation files this transform reads, beyond its own data/raw/ download.

Declared so freshness tooling can tell that an output is stale against its data rather than only its code. Without it a mapping correction lands, every consumer keeps reporting FRESH, and a re-merge silently ships the old groundings: #778 corrected 16 isolation-source ids and #786 rewrote the unified chemical SSSOM, and the merged KG built afterwards still asserted 75 organisms isolated from a “Cell Line”, because nothing re-ran the transforms that read those files (#812).

Paths are relative to the repo root. Keep them tracked in git — the freshness check uses commit time, not mtime, because git checkout rewrites mtimes without changing content (#797).

List every curation file read, not a representative one. A partial declaration fails silently and looks identical to a complete one: ontologies_stubs declared 1 of the 11 files it read and was reported fresh after changes to the other ten (#839). Where the set comes from a constant, derive this from it rather than restating it.

run(data_file=None, show_status=True)

Run the GTDB transform.

Process: 1. Load and parse taxonomy files 2. Extract unique taxa and build hierarchy 3. Load metadata for NCBI mappings 4. Create genome nodes 5. Write output files