molsysmt.basic.get_label#

molsysmt.basic.get_label(molecular_system, element='atom', selection='all', string='{name}-{id}@{index}', syntax='MolSysMT', skip_digestion=False, **kwargs)[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 in any supported MolSysMT format.

  • element (str, default='atom') – Structural element level to query (‘atom’, ‘group’, ‘component’, ‘molecule’, ‘chain’, ‘entity’).

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

  • string (str, default=’{name}-{id}@{index}’) – Format template built from element attributes such as name, ID, and index.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

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

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