Base Classes

Base classes used across multiple modules.

OBO Entity

Shared base class and helpers for ontology entries (UNIMOD, PSI-MOD, RESID, XLMOD, GNOme, amino acids, elements, …). Every *Info dataclass in this package (UnimodInfo, PsimodInfo, ElementInfo, …) subclasses OboEntity and inherits its fields, serialization, and mass/composition helpers.

class tacular.obo_entity.OboEntity(id, name, formula, monoisotopic_mass, average_mass, dict_composition)

Bases: object

Base class for OBO file entities.

Subclasses (one per ontology/data type) add no fields of their own beyond what’s declared here; they exist to give each ontology’s entries a distinct type and, where needed, override id_tag for that ontology’s id format.

Parameters:

• id (str)

• name (str)

• formula (str | None)

• monoisotopic_mass (float | None)

• average_mass (float | None)

• dict_composition (Mapping[str, int] | None)

average_mass: float | None

Average (isotope-abundance-weighted) mass delta in Da, or None if not available.

property composition: dict[ElementInfo, int] | None

dict_composition with keys resolved to ElementInfo objects instead of plain symbol strings; None if no composition is set.

dict_composition: Mapping[str, int] | None

Elemental composition as {symbol: count} (isotope keys like "13C" are supported), or None if not available. Use composition for a version keyed by ElementInfo instead of plain strings.

formula: str | None

Chemical formula string (e.g. "C2H2O"), or None if not available.

classmethod from_dict(data)

Reconstruct an OboEntity from its to_dict representation.

The inverse of to_dict(); note to_dict serialises dict_composition under the "composition" key.

Return type:

Self

Parameters:

data (Mapping[str, Any])

id: str

The entry’s id, in whatever format its source ontology uses (e.g. "536" for UNIMOD, "AA0001" for RESID). Use id_tag for a normalized form.

property id_tag: str

id with leading zeros stripped (e.g. "00042" -> "42").

Subclasses whose ids carry a non-numeric prefix (RESID’s "AA0001", for example) override this to strip that prefix too.

mass(monoisotopic=True)

Get the mass of the entity

Return type:

float | None

Parameters:

monoisotopic (bool)

monoisotopic_mass: float | None

Monoisotopic mass delta in Da, or None if not available.

name: str

The entry’s human-readable name, as given by the source ontology.

to_dict(float_precision=6)

Convert the OboEntity to a dictionary.

float_precision rounds the masses (default 6, as used for the bundled jsons/*.json). Pass None to preserve full float precision, e.g. when round-tripping through the runtime cache so an updated install matches the precision of the bundled data.py.

Return type:

dict[str, object]

Parameters:

float_precision (int | None)

update(**kwargs)

Return a new instance with updated fields

Return type:

Self

Parameters:

kwargs (Any)

tacular.obo_entity.filter_infos(infos, has_monoisotopic_mass=None, has_composition=None, **criteria)

Filter a list of OboEntity or its subclasses based on criteria.

Return type:

list[TypeVar(T, bound= OboEntity)]

Parameters:

• infos (list[T])

• has_monoisotopic_mass (bool | None)

• has_composition (bool | None)

• criteria (Any)

OBO Lookup

Shared lookup base class (OntologyLookup) used by every per-ontology *_LOOKUP singleton in this package (UNIMOD_LOOKUP, PSIMOD_LOOKUP, …). Handles id/name normalization, query-by-id/name/mass, iteration, and random sampling; each ontology’s *Lookup subclass just supplies its data, name, and optional id prefix (see e.g. unimod/lookup.py).

class tacular.obo_lookup.OntologyLookup(data, ontology_name, _version='', _id_prefix=None)

Bases: Generic

Id/name/mass lookup over a dict of OboEntity subclass instances.

Lookup dictionaries are built lazily on first access (see _ensure_initialized()), not in __init__, so constructing a lookup with cache-resolved data (see tacular._cache) is cheap even before any query is made.

Parameters:

• data (dict[str, T])

• ontology_name (str)

• _version (str)

• _id_prefix (str | None)

choice(require_monoisotopic_mass=True, require_composition=True)

Get a random entry from the lookup.

Return type:

TypeVar(T, bound= OboEntity)

Parameters:

• require_monoisotopic_mass (bool)

• require_composition (bool)

get(key, default=None)

Like lookup[key], but return default instead of raising KeyError.

Return type:

Optional[TypeVar(T, bound= OboEntity)]

Parameters:

• key (str | int)

• default (T | None)

keys()

Get all keys (names) in the lookup.

Return type:

list[str]

query_id(mod_id)

Query by ID, stripping known prefixes.

Return type:

Optional[TypeVar(T, bound= OboEntity)]

Parameters:

mod_id (str | int)

query_mass(mass, tolerance=0.01, monoisotopic=True)

Query by mass within a given tolerance.

Return type:

list[TypeVar(T, bound= OboEntity)]

Parameters:

• mass (float)

• tolerance (float)

• monoisotopic (bool)

query_name(name)

Query by name, stripping known prefixes.

Return type:

Optional[TypeVar(T, bound= OboEntity)]

Parameters:

name (str)

values()

Get all entries in the lookup.

Return type:

list[TypeVar(T, bound= OboEntity)]

property version: str

Get the version of the ontology data.

tacular.obo_lookup.convert_key(key, prefix=None)

strip_id then parse as int, or None if the result isn’t numeric (e.g. RESID’s "AA0001" ids, whose non-numeric suffix can’t convert).

Return type:

int | None

Parameters:

• key (str)

• prefix (str | None)

tacular.obo_lookup.strip_id(key, prefix=None)

Lowercase key, strip a leading prefix (if present) and leading zeros.

E.g. strip_id("UNIMOD:00042", "unimod:") -> "42".

Return type:

str

Parameters:

• key (str)

• prefix (str | None)