Module 15: Semantic Labeling#

Welcome back, Apprentice Master. In Module 14: System Comparison and Validation, you mastered system validation and attribute comparison using msm.compare(). Now we explore human-readable nomenclature: Semantic Labeling using msm.get_label().

While computational algorithms operate efficiently on numeric indices (0, 1, 2…), scientific reporting, visualization legends, and publications require unambiguous biological names (such as “Alpha-Carbon of MET-1 in Chain A”). msm.get_label() provides a semantic template engine that converts any selection into standardized or custom string representations.

Learning Outcomes

By the end of this module, you will be able to:

Generate standard biological labels for atoms and groups using msm.get_label().
Construct custom nomenclature templates using attribute placeholder tokens in the string argument.
Perform batch labeling for selections of atoms or groups.

1. Default Labeling#

Let’s begin by importing MolSysMT and loading our T4 Lysozyme demonstration system.

import molsysmt as msm
from molsysmt import systems

# Load T4 Lysozyme file
lysozyme = systems['T4 lysozyme L99A']['181l.bcif.gz']

msm.get_label() returns a standardized nomenclature string for any atom or group selection:

# Default label for atom index 0
atom_lbl = msm.get_label(lysozyme, selection='atom_index == 0')
print(f"Default label for atom 0: {atom_lbl}")

# Default label for group index 10
group_lbl = msm.get_label(lysozyme, element='group', selection='group_index == 10')
print(f"Default label for group 10: {group_lbl}")

Default label for atom 0: N-1@0

Default label for group 10: GLU-11@10

Hint

msm.get_label(): Converts selections into standardized or custom human-readable nomenclature strings based on attribute templates. See API doc: molsysmt.basic.get_label().

2. Custom Formatting Templates#

You can define custom label templates using {attribute_name} placeholders in the string argument. Placeholders are dynamically populated from system attributes:

# Custom template for group name and group ID
custom_fmt1 = msm.get_label(lysozyme, element='group', selection=10, string='{group_name}:{group_id}')
print(f"Custom group label: {custom_fmt1}")

# Custom template incorporating atom name, group name, group ID, and chain ID
template = '{atom_name} from {group_name}{group_id} (Chain {chain_id})'
custom_fmt2 = msm.get_label(lysozyme, selection=0, string=template)
print(f"Custom atom label: {custom_fmt2}")

Custom group label: GLU:11

Custom atom label: N from MET1 (Chain A)

3. Batch Labeling#

You can apply label templates across multiple items simultaneously to build lists for dataframes, plot legends, or CSV export:

# Batch label Alpha-Carbons of the first 5 groups
ca_labels = msm.get_label(
    lysozyme,
    selection='atom_name == "CA" and group_index == [0, 1, 2, 3, 4]',
    string='CA of {group_name}-{group_id}'
)

for lbl in ca_labels:
    print(f"- {lbl}")

- CA of MET-1
- CA of ASN-2
- CA of ILE-3
- CA of PHE-4
- CA of GLU-5

🏆 Challenge 15: The Semantic Labeler#

Load the T4 Lysozyme system (systems['T4 lysozyme L99A']['181l.bcif.gz']).
Select all Nitrogen atoms (selection='atom_name == "N" and group_index == [0, 1, 2]').
Generate a custom label list using the template string='Backbone N of {group_name} (ID: {group_id})'.
Print each generated label string.

Semantic labeling turns raw indices into clear scientific reporting. In Module 16: Merging and Growing Systems, we will explore how to combine separate molecular systems into unified complexes.