Module 10: Modifying Molecular Attributes#

Welcome back, Apprentice Master. In Module 8: Extracting Molecular Attributes, you learned how to retrieve system attributes using msm.get(). Now we explore the direct counterpart operation: Modifying Molecular Attributes using msm.set().

Molecular modelling and trajectory analysis frequently require editing a system’s state: adjusting 3D atomic coordinates, standardizing chain identifiers, or renaming chemical groups.

1. Modifiable Forms#

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

Important

Crucial Concept: Modifiable Forms
Not all molecular data forms are modifiable. Static disk files (such as a read-only PDB or BCIF file) cannot be edited directly in place. To modify attributes or coordinates, you must first convert the system into an in-memory modifiable form, such as molsysmt.MolSys.

# Convert system into an in-memory modifiable native object
molsys = msm.convert(lysozyme, to_form='molsysmt.MolSys')

Hint

msm.set(): Form-agnostic attribute mutator engine. Updates coordinates, topology identifiers, or physical properties on modifiable molecular systems. See API doc: molsysmt.basic.set().

2. Modifying Coordinates#

You can update the 3D position of any atom or group using msm.set(). As established in Module 9, input quantities are quantity-agnostic and accept explicit unit strings:

# Move atom index 0 to the spatial origin
msm.set(molsys, element='atom', selection=0, coordinates='[0.0, 0.0, 0.0] nm')

# Verify updated position using msm.get()
updated_pos = msm.get(molsys, element='atom', selection=0, coordinates=True)
print(f"Updated position for atom 0: {updated_pos}")

Updated position for atom 0: [[[0.0 0.0 0.0]]] nanometer

3. Modifying Attributes#

Structural files retrieved from public databases often contain non-standard or ambiguous chain or group identifiers. You can standardize these properties programmatically:

# Rename Chain 'A' to 'X'
msm.set(molsys, element='chain', selection='chain_id == "A"', chain_id='X')

# Verify updated chain topology with msm.info()
msm.info(molsys, element='chain')
index id name n atoms n groups n components molecule index molecule type entity index entity name
0 X A 1289 162 1 [0] ['protein'] [0] ['T4 LYSOZYME']
1 B A 1 1 1 [1] ['ion'] [1] ['CHLORIDE ION']
2 C A 1 1 1 [2] ['ion'] [1] ['CHLORIDE ION']
3 D A 8 1 1 [3] ['small molecule'] [2] ['2-HYDROXYETHYL DISULFIDE']
4 E A 6 1 1 [4] ['small molecule'] [3] ['BENZENE']
5 F A 136 136 136 [5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, 56, 57, 58, 59, 60, 61, 62, 63, 64, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 100, 101, 102, 103, 104, 105, 106, 107, 108, 109, 110, 111, 112, 113, 114, 115, 116, 117, 118, 119, 120, 121, 122, 123, 124, 125, 126, 127, 128, 129, 130, 131, 132, 133, 134, 135, 136, 137, 138, 139, 140] ['water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water', 'water'] [4] ['water']

4. Duplicating Systems Before Modification#

In Python, variable assignment (sys_b = sys_a) creates a shared reference alias rather than a new object. Modifying sys_b will alter sys_a. To preserve an unmodified original state before calling msm.set(), create a deep independent copy with msm.copy():

# Create an independent copy of the system
molsys_backup = msm.copy(molsys)

# Modify the backup copy independently
msm.set(molsys_backup, element='chain', selection='chain_id == "X"', chain_id='Z')

# Verify that original molsys retains chain_id 'X'
orig_chain = msm.get(molsys, element='chain', selection=0, chain_id=True)
copy_chain = msm.get(molsys_backup, element='chain', selection=0, chain_id=True)
print(f"Original chain ID: {orig_chain} | Backup chain ID: {copy_chain}")

Original chain ID: ['X'] | Backup chain ID: ['Z']

Hint

msm.copy(): Creates an independent deep copy of a molecular system object in memory. See API doc: molsysmt.basic.copy().

🏆 Challenge 10: The Molecular Editor#

  1. Load the T4 Lysozyme system (systems['T4 lysozyme L99A']['181l.bcif.gz']) and convert it to a native MolSys object.

  2. Make a deep copy using msm.copy().

  3. Use msm.set() to rename the water chain (selection='molecule_type == "water"') in the copy to 'W'.

  4. Set the coordinates of atom index 10 to '[1.0, 1.0, 1.0] nm' in the copy.

  5. Verify your modifications using msm.get() and check that the original object remains unchanged.

System modification is a key step in preparing systems for simulation or building virtual complexes. In Module 11: Iterating Systems, we will learn how to stream heavy systems iteratively.