molsysmt.basic.get_label#

molsysmt.basic.get_label(molecular_system, element='atom', selection='all', string='{name}-{id}@{index}', syntax='MolSysMT', skip_digestion=False)[source]#

Generating label strings for selected elements of a molecular system.

This function builds one or more human-readable labels for elements of a molecular system, based on the requested element level and an f-string-like string pattern. Generic placeholders ({name}, {id}, {index}) are automatically mapped to the appropriate attribute names for the chosen element (e.g., atom_name, group_id). Explicit attribute names (e.g., molecule_name) are also allowed regardless of element.

Parameters:

  • molecular_system (molecular system) – Molecular system to analyze, in any of the supported forms.

  • element ({'atom', 'group', 'component', 'molecule', 'chain', 'entity', 'system'}, default 'atom') – Level of the molecular hierarchy for which labels are generated.

  • selection (int, tuple, list, numpy.ndarray or str, default 'all') – Selection of elements of the specified type. It can be a 0-based index collection or a selection string parsed according to Selection syntaxes. The selection is interpreted at the level given by element.

  • string (str, default ‘{name}-{id}@{index}’) – Pattern template used to construct the labels. It must be a valid str.format() template. Supported generic placeholders are {name}, {id}, {index} (mapped to the element’s attribute names). Additionally, explicit attribute names such as atom_name, group_id, molecule_id, etc., can be used directly.

  • syntax (str, default 'MolSysMT') – Selection syntax used when selection is a string. See Selection syntaxes.

  • skip_digestion (bool, default False) –

    Whether to skip MolSysMT’s internal argument digestion mechanism.

    MolSysMT includes a built-in digestion system that validates and normalizes function arguments. This process checks types, shapes, and values, and automatically adjusts them when possible to meet expected formats.

    Setting skip_digestion=True disables this process, which may improve performance in workflows where inputs are already validated. Use with caution: only set this to True if you are certain all input arguments are correct and consistent.

Returns:

A single label string if only one element is selected; otherwise, a list of label strings in the order of the selection.

Return type:

str or list of str

Raises:

  • NotSupportedFormError – If the input molecular system has an unsupported form.

  • ArgumentError – If input arguments are invalid or inconsistent.

Notes

  • Supported molecular-system forms are summarized in Forms.

  • Selection strings must follow one of the syntaxes described in Selection syntaxes.

See also

molsysmt.basic.select()

Select elements from a molecular system.

molsysmt.basic.get()

Retrieve values of attributes for selected elements.

Examples

>>> import molsysmt as msm
>>> molsys = msm.convert(msm.systems['T4 lysozyme L99A']['181l.h5msm'])
>>> msm.get_label(molsys, element='group', selection=[10, 12, 14],
...               string='{group_name}{group_id}/{entity_name}')
['GLU11/T4 LYSOZYME', 'LEU13/T4 LYSOZYME', 'LEU15/T4 LYSOZYME']

Tutorial with more examples

See the following tutorial for a practical demonstration of how to use this function, along with additional examples: Get label.

Added in version 1.0.0.

On this page