/ 
BioX-Tax-Kraken-0.001001-TRIAL
/ BioX::Tax::Kraken

NAME

BioX::Tax::Kraken - simple access to Kraken-style taxDB taxonomy database

SYNOPSIS

use BioX::Tax::Kraken;

use constant CHICKEN => 9031; use constant HUMAN => 9606; use constant VERTEBRATA => 7742; use constant WHITE_OAK => 3513; use constant HSV1 => 10298;

my $tax = BioX::Tax::Kraken->new($ARGV[0]);

say $tax->name(CHICKEN); # 'Gallus gallus' say $tax->rank(CHICKEN); # 'species' say $tax->name( $tax->parent(CHICKEN) ); # 'Gallus'

say $tax->is_ancestor(CHICKEN, VERTEBRATA) ? 'Y' : 'N'; # 'Y' say $tax->is_ancestor(CHICKEN, WHITE_OAK) ? 'Y' : 'N'; # 'N' say $tax->name( $tax->lca(CHICKEN, HUMAN) ); # 'Amniota' say $tax->name( $tax->lca(CHICKEN, WHITE_OAK) ); # 'Eukaryota' say join ' > ', map {$tax->name($_)} $tax->lineage(HSV1); # 'root > Viruses > Duplodnaviria > Heunggongvirae > Peploviricota > # Herviviricetes > Herpesvirales > Orthoherpesviridae > Alphaherpesvirinae > # Simplexvirus > Simplexvirus humanalpha1' say join ' > ', map {$tax->rank($_)} $tax->lineage(HSV1); # 'no rank > domain > clade > kingdom > phylum > class > order > family > # subfamily > genus > species'

DESCRIPTION

NOTE:: This distribution is currently in alpha stage. The API may change without notice. You have been warned.

BioX::Tax::Kraken is a simple interface to a Kraken-style flatfile taxonomic database, typically using the filename 'taxDB'. This file format is a four-column tab-delimited text file, where the columns contain:

taxonomic ID
parent ID
name (typically scientific)
rank

This distribution has a single class with methods to look up and compare entries in a Kraken-style taxonomic database based on one or more taxonomic IDs. It is designed to be simple and correct, and it is written to balance speed and memory consumption. It is neither blazing fast nor ultra memory efficient; there are better options for taxonomic data storage formats and interfaces if you have one of these requirements. This software's only purpose is to facilitate easy access to the information stored in a Kraken-style database if you are already using that format for other reasons.

NOTE: The author typically utilizes the NCBI taxonomic database, where taxonomic IDs are positive integers. Because this is Perl, all of the class methods can be given either integers or strings as inputs; all inputs will be treated as strings internally for purposes of comparison.

A NOTE ON ERROR HANDLING

The methods in this module are intentionally designed to be forgiving by default. All methods take one or more taxonomic IDs as arguments; if an ID is not found in the database, undefined is returned but no errors are thrown. Because most taxonomic databases are constantly changing, this design choice allows for the possibility of graceful failure if an ID has been removed from the database without wrapping every method call in a try/catch block.

If you wish to treat these cases as errors, you must check for the definedness of return values and throw your own errors accordingly.

METHODS

new filename
my $tax = BioX::Tax::Kraken->new('/path/to/taxDB');

Create a new BioX::Tax::Kraken object and load the database from file. The input filename is required, and uncompressed or xz-compressed inputs are supported (xz has significantly better compression ratios than gzip, bzip2, or zstd on taxDB files).

Returns a new BioX::Tax::Kraken object.

name tax ID
rank tax ID
parent tax ID
say $tax->name(9031); # 'Gallus gallus'
say $tax->rank(9031); # 'species'
say $tax->parent(9031); # '9030'

Given a valid taxonomic ID, fetch the associated property from the database.

Returns a scalar string, or undefined if no entry was found for the input ID.

is_ancestor child ID parent ID
say "That explains a lot!"
    if $tax->is_ancestor(9606, 9443);

Given two valid taxonomic IDs, queries to database to check if the second ID is an ancestor (not necessarily direct) of the first.

Returns a boolean value, or undefined if either ID was not found in the database.

lineage tax ID
for my $id ( $tax->lineage(9031) ) {
    say sprintf "%s: %s",
        $tax->rank($id),
        $tax->name($id);
}

Given a valid taxonomic ID, calculates the taxonomic lineage from the tree root to the given node, inclusive.

Returns a list of IDs, or undefined if the given ID was not found in the database.

lca tax ID 1 tax ID 2 ...
my $oldun = $tax->lca(9031, 9606);

Given two or more tax IDs, calculates the last common ancestor (LCA, aka MRCA) in common to all given nodes.

Returns a taxonomic ID, or undefined if one or more given IDs were not found in the database.

children tax ID
my @descendents = $tax->children(9031);

Given a valid tax ID, traverses the taxonomic tree to collect all intermediate and leaf nodes that descend from that ID. BEWARE: The class does not currently store any back-references when parsing the input database. Thus, unlike all other instance methods, this method currently must traverse the *entire* database each time it is called, and it therefore will be a significant bottleneck if called over thousands or millions of inputs.

Returns an unsorted list of IDs, or undefined if the given ID was not found in the database.

CAVEATS AND BUGS

Please reports bugs or feature requests through the issue tracker at https://github.com/jvolkening/p5-BioX-Tax-Kraken/issues.

AUTHOR

Jeremy Volkening <jeremy.volkening *at* base2bio.com>

COPYRIGHT AND LICENSE

Copyright 2026 Jeremy Volkening

This software is licensed under the same terms as Perl 5 itself. See LICENSE file for full details.