Taxonomic Classification and Database Queries

gambit.classify

Classify queries based on distance to reference sequences.

class gambit.classify.ClassifierResult

Bases: object

Result of applying the classifier to a single query genome.

success

Whether the classification process ran successfully with no fatal errors. If True it is still possible no prediction was made.

Type:

bool

predicted_taxon

Taxon predicted by classifier.

Type:

gambit.db.models.Taxon | None

primary_match

Match to closest reference genome which produced a predicted taxon equal to or a descendant of predicted_taxon. None if no prediction was made.

Type:

gambit.classify.GenomeMatch | None

closest_match

Match to closest reference genome overall. This should almost always be identical to primary_match.

Type:

gambit.classify.GenomeMatch

next_taxon

Next most specific taxon for which the threshold was not met. Currently this just taken from the ancestry of closest_match.genome.taxon.

Type:

gambit.db.models.Taxon | None

warnings

List of non-fatal warning messages to report.

Type:

list[str]

error

Message describing a fatal error which occurred, if any.

Type:

str | None

__init__(success, predicted_taxon, primary_match, closest_match, next_taxon=NOTHING, warnings=NOTHING, error=None)

Method generated by attrs for class ClassifierResult.

Parameters:
Return type:

None

class gambit.classify.GenomeMatch

Bases: object

Match between a query and a single reference genome.

This is just used to report the distance from a query to some significant reference genome, it does not imply that this distance was close enough to actually make a taxonomy prediction or that the prediction was the primary prediction overall.

genome

Reference genome matched to.

Type:

gambit.db.models.AnnotatedGenome

distance

Distance between query and reference genome.

Type:

float

matched_taxon

Taxon prediction based off of this match alone. Will always be genome.taxon or one of its ancestors.

Type:

gambit.db.models.Taxon | None

__init__(genome, distance, matched_taxon=NOTHING)

Method generated by attrs for class GenomeMatch.

Parameters:
Return type:

None

next_taxon()

Get next most specific taxon in lineage of genome for which the threshold was not met.

Return type:

Taxon | None

gambit.classify.classify(ref_genomes, dists, *, strict=False)

Predict the taxonomy of a query genome based on its distances to a set of reference genomes.

Parameters:

  • ref_genomes (Sequence[AnnotatedGenome]) – List of reference genomes from database.

  • dists (ndarray) – Array of distances to each reference genome.

  • strict (bool) – If true find all significant matches to reference genomes and attempt to reconcile them if they result in different taxa. If False just consider the top (closest) match. Defaults to False.

Return type:

ClassifierResult

gambit.classify.consensus_taxon(taxa)

Take a set of taxa matching a query and find a single consensus taxon for classification.

If a query matches a given taxon, it is expected that there may be matches to some of that taxon’s ancestors as well. In this case all matched taxa lie in a single lineage and the most specific will be the consensus.

It may also be possible for a query to match multiple taxa which are “inconsistent” with each other in the sense that one is not a descendant of another. In that case the consensus will be the lowest taxon which is either a descendant or ancestor of all taxa in the argument. It’s also possible in pathological cases (depending on reference database design) that the taxa may be within entirely different trees, in which case the consensus will be None. The second element of the returned tuple is the set of taxa in the argument which are strict descendants of the consensus. This set will contain at least two taxa in the case of such an inconsistency and be empty otherwise.

Parameters:

taxa (Iterable[Taxon])

Returns:

Consensus taxon along with the set of any taxa in the argument which are descended from it.

Return type:

tuple[Optional[Taxon], set[Taxon]]

gambit.classify.find_matches(itr)

Find taxonomy matches given distances from a query to a set of reference genomes.

Parameters:

itr (Iterable[tuple[AnnotatedGenome, float]]) – Iterable over (genome, distance) pairs.

Returns:

Mapping from taxa to indices of genomes matched to them.

Return type:

dict[Taxon, list[int]]

gambit.classify.matching_taxon(taxon, d)

Find first taxon in linage for which distance d is within its classification threshold.

Parameters:

  • taxon (Taxon) – Taxon to start searching from.

  • d (float) – Distance value.

Returns:

Most specific taxon in ancestry with threshold_distance >= d.

Return type:

Optional[Taxon]

gambit.query

Run queries against a GAMBIT database to predict taxonomy of genome sequences.

class gambit.query.QueryParams

Bases: object

Parameters for running a query.

classify_strict

strict parameter to gambit.classify.classify(). Defaults to False.

Type:

bool

chunksize

Number of reference signatures to process at a time. None means no chunking is performed. Defaults to 1000.

Type:

int

report_closest

Number of closest genomes to report in results. Does not affect classification.

Type:

int

__init__(classify_strict=False, chunksize=1000, report_closest=10)

Method generated by attrs for class QueryParams.

Parameters:

  • classify_strict (bool)

  • chunksize (int)

  • report_closest (int)

Return type:

None

class gambit.query.QueryResultItem

Bases: object

Result for a single query sequence.

label

Unique label describing query.

Type:

str

classifier_result

Result of running classifier.

Type:

gambit.classify.ClassifierResult

report_taxon

Final taxonomy prediction to be reported to the user.

Type:

gambit.db.models.Taxon | None

closest_genomes

List of closest reference genomes to query. Length determined by QueryParams.report_closest.

Type:

list[gambit.classify.GenomeMatch]

file

Path to file containing query genome (optional).

Type:

pathlib.Path | None

__init__(label, classifier_result, report_taxon=None, closest_genomes=NOTHING, file=None)

Method generated by attrs for class QueryResultItem.

Parameters:
Return type:

None

class gambit.query.QueryResults

Bases: object

Results for a set of queries, as well as information on database and parameters used.

items

Results for each query sequence.

Type:

list[gambit.query.QueryResultItem]

params

Parameters used to run query.

Type:

gambit.query.QueryParams | None

genomeset

Genome set used.

Type:

gambit.db.models.ReferenceGenomeSet | None

signaturesmeta

Metadata for signatures set used.

Type:

gambit.sigs.base.SignaturesMeta | None

gambit_version

Version of GAMBIT command/library used to generate the results.

Type:

str

timestamp

Time query was completed.

Type:

datetime.datetime

extra

JSON-able dict containing additional arbitrary metadata.

Type:

dict[str, Any]

__init__(items, params=None, genomeset=None, signaturesmeta=None, gambit_version='1.1.0', timestamp=NOTHING, extra=NOTHING)

Method generated by attrs for class QueryResults.

Parameters:
Return type:

None

gambit.query.get_result_item(db, params, dists, label)

Perform classification and create result item object for single query input.

Parameters:
Return type:

QueryResultItem

gambit.query.query(db, queries, params=None, *, labels=None, progress=None, **kw)

Predict the taxonomy of one or more query genomes using a GAMBIT reference database.

Parameters:

  • db (ReferenceDatabase) – Database to query.

  • queries (Sequence[KmerSignature]) – Sequence of k-mer signatures for query genomes.

  • params (QueryParams | None) – QueryParams instance defining parameter values. If None take values from additional keyword arguments or use defaults.

  • labels (Sequence[str] | None) – Optional list of string labels for each query. Only used for reporting (sets label attribute of QueryResultItem in results object), does not any other aspect of results.

  • progress – Report progress for distance matrix calculation and classification. See gambit.util.progress.get_progress() for description of allowed values.

  • **kw – Passed to QueryParams.

Return type:

QueryResults

gambit.query.query_parse(db, files, params=None, *, labels=None, parse_kw=None, **kw)

Query a database with signatures derived by parsing a set of genome sequence files.

Parameters:
Return type:

QueryResults