Module 3: Molecular Elements#

Welcome back, Apprentice Master. In Module 1 and Module 2, you mastered the first two foundational pillars of MolSysMT: the Form (how molecular data is stored) and the Attribute (what data a system contains).

Now we complete the trinity with the third foundational pillar of MolSysMT: the Element.

When analyzing a complex biomolecular system, you rarely work with raw unorganized atoms. A system is structured into a biological and topological hierarchy. In MolSysMT, every level of this hierarchy is called an Element: atom ➔ group ➔ component ➔ molecule ➔ chain ➔ entity (and system).

Functions you have already encountered—such as msm.info() and msm.get()—accept an element parameter that specifies which structural level your operation targets.

Glossary: Element

An Element is any structural or topological level of a molecular system (atom, group, component, molecule, chain, entity, or system). The element parameter defines the granular level at which functions inspect or query data. See the user-foundations guide for a detailed reference on biological elements.

1. The 6 Hierarchical Elements#

Let’s begin by 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']

MolSysMT organizes molecular systems into 6 distinct structural Elements:

  1. atom: The fundamental physical particles with 3D coordinates and element symbols.

  2. group: The fundamental topological building blocks (amino acid residues, nucleotides, water molecules, ions, lipids, or small ligands).

  3. component: Covalently connected molecular graphs (a single contiguous polypeptide chain, a single water molecule, or a bound inhibitor).

  4. molecule: Functional molecular units (e.g., a protein monomer, a solvent molecule, or a co-crystallized ligand).

  5. chain: Structural segment identifiers assigned by structural databases (e.g., Chain A, Chain B).

  6. entity: Distinct chemical species inventory (e.g., Protein entity, Water entity, Benzamidine entity).

Every element level has corresponding attributes in MolSysMT (such as atom_name, group_name, molecule_type, chain_id, entity_name).

2. Auditing Hierarchies: msm.info(element=...)#

By default, msm.info() reports a high-level summary of a molecular system. By specifying the element parameter, you can inspect the biological inventory at any element level:

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

We can also inspect the inventory at the chain or entity level:

# Summary grouped at the entity level
msm.info(lysozyme, element='entity')
index name type n atoms n groups n components n chains n molecules
0 T4 LYSOZYME protein 1289 162 1 1 1
1 CHLORIDE ION ion 2 2 2 2 2
2 2-HYDROXYETHYL DISULFIDE small molecule 8 1 1 1 1
3 BENZENE small molecule 6 1 1 1 1
4 water water 136 136 136 1 136

Hint

msm.info(): Displays a human-readable summary of a molecular system scoped to a specific element level (atom, group, component, molecule, chain, entity). See API doc: molsysmt.basic.info().

3. Extracting Element Counts & Attributes: msm.get(element=...)#

When using msm.get(), setting the element parameter defines what items are queried or counted.

Let’s query the number of groups, molecules, chains, and entities in T4 Lysozyme:

# Query counts at different element levels
n_atoms = msm.get(lysozyme, element='atom', n_atoms=True)
n_groups = msm.get(lysozyme, element='group', n_groups=True)
n_molecules = msm.get(lysozyme, element='molecule', n_molecules=True)
n_entities = msm.get(lysozyme, element='entity', n_entities=True)

print(f"Total Atoms    : {n_atoms}")
print(f"Total Groups   : {n_groups}")
print(f"Total Molecules: {n_molecules}")
print(f"Total Entities : {n_entities}")

Total Atoms    : 1441
Total Groups   : 302
Total Molecules: 141
Total Entities : 5

We can also query element-specific attribute arrays. For example, let’s query the names and types of all molecules in the system:

# Query names and types at the molecule level
mol_names, mol_types = msm.get(lysozyme, element='molecule', molecule_name=True, molecule_type=True)

print(f"First 5 molecule names: {mol_names[:5]}")
print(f"First 5 molecule types: {mol_types[:5]}")

First 5 molecule names: ['T4 LYSOZYME', 'CHLORIDE ION', 'CHLORIDE ION', '2-HYDROXYETHYL DISULFIDE', 'BENZENE']
First 5 molecule types: ['protein', 'ion', 'ion', 'small molecule', 'small molecule']

Hint

msm.get(): Scopes attribute extraction and item counting to a specified element level (atom, group, component, molecule, chain, entity). See API doc: molsysmt.basic.get().

🏆 Challenge 3: The Hierarchy Architect#

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

  2. Use msm.info() at element='molecule' to identify all non-water molecules.

  3. Use msm.get() to count total groups, molecules, and chains.

  4. Use msm.get() at element='chain' to query all chain_id and chain_type values.

With Form, Attribute, and Element mastered, you possess the core conceptual triad of MolSysMT. In Module 4: Native Forms, we will explore MolSysMT’s high-performance native objects.