Nomenclature Helper

GitHub Link to Code.

NomenclatureHelper utilities for molecular dynamics trajectory labeling.

This module provides utilities to create consensus labels for MD trajectories using different nomenclature systems (GPCR, CGN, KLIFS) via mdciao labelers.

Notes

This module uses mdciao consensus nomenclature systems:

https://proteinformatics.uni-leipzig.de/mdciao/api/generated/mdciao.nomenclature.html # noqa: E501

Supported fragment types:

class mdxplain.trajectory.helper.metadata_helper.nomenclature_helper.NomenclatureHelper(topology: Topology, fragment_definition: str | Dict[str, Tuple[int, int]] | None = None, fragment_type: str | Dict[str, str] | None = None, fragment_molecule_name: str | Dict[str, str] | None = None, consensus: bool = False, aa_short: bool = False, verbose: bool = False, try_web_lookup: bool = True, write_to_disk: bool = False, cache_folder: str = './cache', **labeler_kwargs)

A utility class for creating consensus labels from MD trajectories.

This class provides a unified interface to use different mdciao labelers (GPCR, CGN, KLIFS) and generate label lists for molecular dynamics analysis.

Uses mdciao nomenclature systems: https://proteinformatics.uni-leipzig.de/mdciao/api/generated/mdciao.nomenclature.html

__init__(topology: Topology, fragment_definition: str | Dict[str, Tuple[int, int]] | None = None, fragment_type: str | Dict[str, str] | None = None, fragment_molecule_name: str | Dict[str, str] | None = None, consensus: bool = False, aa_short: bool = False, verbose: bool = False, try_web_lookup: bool = True, write_to_disk: bool = False, cache_folder: str = './cache', **labeler_kwargs)

Initialize the NomenclatureHelper labeler.

This class provides a unified interface to create consensus labels for MD trajectories using different mdciao nomenclature systems.

Parameters

topologymd.Topology: MDTraj topology object to label
fragment_definitionstr or dict, default None: If string, uses that as fragment name for entire topology. If dict, maps fragment names to residue ranges: {“cgn_a”: (0, 348), “beta2”: (400, 684)} Only required when consensus=True.
fragment_typestr or dict, default None: If string, uses that nomenclature type for all fragments. If dict, maps fragment names to nomenclature types: {“cgn_a”: “cgn”, “beta2”: “gpcr”} Use mdciao nomenclature types. Allowed types: gpcr, cgn, klifs Only required when consensus=True.
fragment_molecule_namestr or dict, default None: If string, uses that molecule name for all fragments. If dict, maps fragment names to molecule names: {“cgn_a”: “gnas2_bovin”, “beta2”: “adrb2_human”} Use the UniProt entry name (not accession ID) for GPCR/CGN labelers, or KLIFS string for KLIFS labelers. See https://www.uniprot.org/help/difference_accession_entryname for UniProt naming conventions. # noqa: E501 See https://proteinformatics.uni-leipzig.de/mdciao/api/generated/generated/mdciao.nomenclature.LabelerKLIFS.html#mdciao.nomenclature.LabelerKLIFS for KLIFS naming conventions. # noqa: E501 Only required when consensus=True.
consensusbool, default False: Whether to use consensus labeling (combines AA codes with nomenclature labels). If False, only returns amino acid labels without nomenclature.
aa_shortbool, default False: Whether to use short amino acid names (T vs THR)
verbosebool, default False: Whether to enable verbose output from labelers
try_web_lookupbool, default True: Whether to try web lookup for molecule data
write_to_diskbool, default False: Whether to write cache files to disk
cache_folderstr, default “./cache”: Folder for cache files
labeler_kwargs: Additional keyword arguments passed to the mdciao labelers

Returns

None: Initializes the NomenclatureHelper object

Raises

ValueError: If fragment_definition is required when consensus=True
ValueError: If fragment_type is required when consensus=True
ValueError: If fragment_molecule_name is required when consensus=True

Notes

This class uses mdciao consensus nomenclature systems: https://proteinformatics.uni-leipzig.de/mdciao/api/generated/mdciao.nomenclature.html

Supported fragment types:

Examples

Amino acid labels only (no nomenclature):

>>> nomenclature = NomenclatureHelper(
...     topology=traj.top,
...     consensus=False,
...     aa_short=True  # Use single-letter codes: A, C, D, ...
... )
>>> labels = nomenclature.create_labels()

Simple single fragment labeling:

>>> nomenclature = NomenclatureHelper(
...     topology=traj.top,
...     fragment_definition="receptor",
...     fragment_type="gpcr",
...     fragment_molecule_name="adrb2_human",
...     consensus=True
... )
>>> labels = nomenclature.create_labels()

Complex multi-fragment labeling:

>>> nomenclature = NomenclatureHelper(
...     topology=traj.top,
...     fragment_definition={"gpcr": (0, 300), "g_protein": (300, 600)},
...     fragment_type={"gpcr": "gpcr", "g_protein": "cgn"},
...     fragment_molecule_name={"gpcr": "adrb2_human", "g_protein": "gnas_human"},
...     consensus=True
... )
>>> labels = nomenclature.create_labels()

create_trajectory_label_dicts() → List[Dict]

Create structured label dictionaries for the trajectory.

Parameters

None

Returns

List[Dict]: List of label dictionaries for each residue in the topology. Each dict contains: aaa_code, a_code, index, seqid, consensus, full_name