Module 2: Molecular Attributes#

Welcome back, Apprentice Master. In Module 1, you learned that MolSysMT treats every data container as a Form.

Now we arrive at the second foundational pillar of MolSysMT: the Attribute. If the Form is how molecular data is stored, the Attribute is what data a molecular system actually contains.

Whether your system is stored in a PDB file, an OpenMM topology, or a native object, it holds data points such as atom names, group IDs, 3D spatial coordinates, periodic box dimensions, or partial charges. In MolSysMT, all of these data points are unified as Attributes.

Glossary: Attribute

An Attribute is any standardized property (topological, structural, chemical, or mechanical) associated with a molecular system that can be queried using msm.get() or modified using msm.set(). See the user-foundations guide for a complete reference list of molecular attributes.

1. What is a Molecular Attribute?#

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']

Attributes in MolSysMT are organized into four main semantic categories:

  1. Topological Attributes: Data defining atom and group identity and biological hierarchy (atom_name, atom_type, group_name, chain_id).

  2. Structural Attributes: Geometric state data (coordinates, velocities, box).

  3. Chemical-State Attributes: Covalent bonds, formal charges, stereochemistry, and implicit hydrogens.

  4. Mechanical Attributes: Forcefield parameters, non-bonded terms, and potential energy.

Note

Terminology Note: “Group” vs. “Residue”
Many traditional tools use residue as a catch-all term for any molecular fragment. However, in chemistry, a residue specifically refers to a monomer unit remaining after polymerization (such as an amino acid in a protein or a nucleotide in nucleic acids). It is chemically inaccurate to label a water molecule, a sodium ion, a lipid, or a small-molecule drug as a “residue”.
MolSysMT introduces the universal term group to encompass amino acid residues, nucleotides, water molecules, ions, lipids, and small ligands under a single consistent topological level (group_name, group_id, group_index, n_groups).

You can inspect if a specific attribute is present using msm.has_attribute(), or retrieve a list of all available attributes in a system using msm.get_attributes():

# Check presence of specific attributes
print(f"Has coordinates? {msm.has_attribute(lysozyme, 'coordinates')}")
print(f"Has box? {msm.has_attribute(lysozyme, 'box')}")

# List all available attributes in the system
available_atts = msm.get_attributes(lysozyme)
print(f"\nTotal attributes available: {len(available_atts)}")
print(f"Sample attributes: {available_atts[:8]}")

Has coordinates? True
Has box? True

Total attributes available: 67
Sample attributes: ['atom_index', 'atom_name', 'atom_id', 'atom_type', 'group_index', 'group_name', 'group_id', 'group_type']

Hint

msm.has_attribute() & msm.get_attributes(): Functions for auditing attribute presence and discovering all supported data fields in a molecular system. See API docs: molsysmt.basic.has_attribute() and molsysmt.basic.get_attributes().

2. Extracting Attributes: msm.get()#

To extract data from any molecular system regardless of its underlying form, use msm.get().

For example, let’s extract the atom_name, group_name, and coordinates for the first three atoms in our system.

In MolSysMT, spatial coordinates are always returned as a 3D NumPy array with the shape:
(n_structures, n_atoms, 3) (where 3 represents the X, Y, Z spatial dimensions).

This 3D shape is an inviolable invariant preserved across single-structure PDBs and multi-structure trajectories alike.

# Extract atom names, group names, and coordinates for the first 3 atoms
atom_names, group_names, coords = msm.get(
    lysozyme, 
    selection=[0, 1, 2], 
    atom_name=True, 
    group_name=True, 
    coordinates=True
)

print(f"Atom names : {atom_names}")
print(f"Group names: {group_names}")
print(f"Coords shape: {coords.shape} (n_structures, n_atoms, spatial:x,y,z)")

Atom names : ['N', 'CA', 'C']
Group names: ['MET', 'MET', 'MET']
Coords shape: (1, 3, 3) (n_structures, n_atoms, spatial:x,y,z)

Hint

msm.get(): Queries topological, structural, or physical attributes from a molecular system using selection queries. See API doc: molsysmt.basic.get().

3. Modifying Attributes: msm.set()#

Just as msm.get() extracts information, msm.set() allows you to update or modify attributes in mutable molecular systems (such as molsysmt.MolSys or in-memory structures).

Let’s convert our file to a native MolSys object and update its atom names:

# Convert to native object to allow in-memory attribute modification
molsys = msm.convert(lysozyme, to_form='molsysmt.MolSys')

# Check original name of atom 0
print(f"Original name of atom 0: {msm.get(molsys, selection=0, atom_name=True)[0]}")

# Update name of atom 0 using msm.set()
msm.set(molsys, selection=0, atom_name='N1')
print(f"Modified name of atom 0: {msm.get(molsys, selection=0, atom_name=True)[0]}")

Original name of atom 0: N
Modified name of atom 0: N1

Hint

msm.set(): Modifies or updates specific attributes or coordinates in a molecular system. See API doc: molsysmt.basic.set().

🏆 Challenge 2: The Attribute Master#

  1. Load the SARS-CoV-2 Protease using strictly its PDB ID: 'pdb_id:6LU7'.

  2. Use msm.has_attribute() to check if it contains 'b_factor' and 'coordinates'.

  3. Use msm.get() to extract the total number of atoms (n_atoms) and groups (n_groups).

  4. Extract the coordinates of the first 10 atoms and print the shape of the coordinate array.

Mastering attributes is the key to unlocking MolSysMT’s analytical power. In Module 3: Native Forms, we will explore MolSysMT’s high-performance native objects.