tidyms.chem.EnvelopeScorer

class EnvelopeScorer(bounds: Dict[str, Tuple[int, int]], max_M: float | None = None, max_length: int = 10, scorer: Callable | None = None, custom_abundances: dict | None = None, **kwargs)

Ranks formula candidates by comparing a measured isotopic envelope against the theoretical envelopes of candidates.

Methods

score(M, p, tol)	Scores the isotopic envelope.
get_top_results([n])	Return the top ranked formula candidates and their score.

Constructor method.

Parameters:

formula_generatorFormulaGenerator

scorerCallable or None, default=None

Function used to score formula candidate envelopes. If None, the function score_envelope() is used. A custom scoring function can be passed with the following signature:

def score(M, p, Mq, pq, **kwargs):
    pass

where M and p are arrays of the formula candidates exact mass and abundances and Mq and pq are the query mass and query abundance.

max_lengthint, 10

Length of the generated envelopes.

custom_abundancesdict, optional

Overrides natural abundances of elements.A mapping from element symbols str to an abundance array. The abundance array must have the same size that the natural abundance and its sum must be equal to one. For example, for “C”, an alternative abundance can be array([0.15, 0.85]) for isotopes with nominal mass 12 and 13.

Other Parameters:

kwargs

Optional parameter to pass into the scoring function.

get_top_results(n: int | None = 10)

Return the top ranked formula candidates and their score.

Parameters:

n: int or None, default=10

number of first n results to return. If None, return all formula candidates.

Returns:

coefficientsarray

Formula coefficients. Each row is a formula candidate, each column is an element.

elementsarray

The corresponding element to each column of coefficients.

scoresarray

The corresponding score to each row of coefficients.

score(M: ndarray, p: ndarray, tol: float)

Scores the isotopic envelope. The results can be recovered using the get_top_results method.

Formulas are generated assuming that the first element in the envelope is the minimum mass isotopologue.

Parameters:

Marray

Exact mass of the envelope.

parray

Abundance of the envelope.

tolfloat

Mass tolerance used in formula generation.