Get#

Retrieving attribute values from a molecular system.

A molecular system is defined by its attributes and the attributes of its elements — such as the number of atoms, group names, bonded atoms, coordinates, box dimensions, and more. However, not all attributes are available in every representation (form) of a system. Molecular systems can take different forms, such as string identifiers, file paths, or Python objects. Each form includes a specific set of attributes and omits others. Regardless of the form, retrieving attribute values is a key operation in any workflow involving molecular models.

Hint

Visit the section The Molecular System in case you are not familiar with the concepts of “form” or “attribute” in MolSysMT.

The list of attributes defined in MolSysMT for a molecular system can be checked in the section Attributes. And the function molsysmt.basic.get() is the tool to get the attribute values of a molecular system in any supported form.

Added in version 1.0.0.

API documentation

Follow this link for a detailed description of the input arguments, raised errors, and returned objects of this function: molsysmt.basic.get().

Basic usage#

Let’s show how this function works using a PDB system (1TCD):

A valid native topology can have atoms and bonds but zero groups, for example an RDKit molecule without residue metadata. In that case, atom-level group_id, group_name, and group_type queries return None; n_groups remains zero. MolSysMT does not invent residue groups or a ligand label. Check msm.has_attribute(molsys, "group_name") before requiring that hierarchy.

import molsysmt as msm

molsys = msm.convert('1TCD', to_form='molsysmt.MolSys')

msm.info(molsys)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_waters	n_proteins	n_structures
molsysmt.MolSys	3983	662	167	4	167	2	165	2	1

Let’s retrieve the names of atoms with indices 32, 33, and 34 (0-based). The function molsysmt.basic.get() uses the element argument to specify the type of element being queried (e.g., ‘atom’, ‘group’, ‘molecule’, etc.). To filter which elements to include, use the selection argument, which accepts a list of indices or a query string.

names = msm.get(molsys, element='atom', selection=[32,33,34], name=True)
print('Atom names:',names)

Atom names: ['N', 'CA', 'C']

Tip

All methods defined in the molsysmt.basic module can be invoked also from the main level of the library. Hence, molsysmt.get() is the same method as molsysmt.basic.get().

We are not limited to retrieving just one attribute. Multiple attributes can be requested in a single call:

names, group_indices, group_names = msm.get(molsys, element='atom', selection=[32,33,34],
                                            name=True, group_index=True, group_name=True)
print('Atom names:', names)
print('Group indices:', group_indices)
print('Group names:', group_names)

Atom names: ['N', 'CA', 'C']
Group indices: [4, 4, 4]
Group names: ['ILE', 'ILE', 'ILE']

Let’s illustrate now how things can work with other elements:

n_atoms = msm.get(molsys, element='group', selection=[10,11,12], n_atoms=True)
print('Number of atoms:', n_atoms)

Number of atoms: [9, 6, 8]

msm.get(molsys, element='group', selection=[10,11,12], n_atoms=True)

[9, 6, 8]

names, atom_indices, atom_names = msm.get(molsys, element='group', selection=[10,11,12],
                                            name=True, atom_index=True, atom_name=True)
print('Group names:', names)
print('Atom indices:', atom_indices)
print('Atom names:', atom_names)

Group names: ['LYS', 'CYS', 'ASN']
Atom indices: [[77, 78, 79, 80, 81, 82, 83, 84, 85], [86, 87, 88, 89, 90, 91], [92, 93, 94, 95, 96, 97, 98, 99]]
Atom names: [['N', 'CA', 'C', 'O', 'CB', 'CG', 'CD', 'CE', 'NZ'], ['N', 'CA', 'C', 'O', 'CB', 'SG'], ['N', 'CA', 'C', 'O', 'CB', 'CG', 'OD1', 'ND2']]

indices, component_indices = msm.get(molsys, element='component', selection=[55, 56, 57],
                                    index=True, group_index=True)
print('Indices:', indices)
print('Component indices:', component_indices)

Indices: [55, 56, 57]
Component indices: [[550], [551], [552]]

If no selection is specified, the function applies to all elements of the chosen type by default. See for example:

msm.get(molsys, element='atom', n_atoms=True)

The function msm.basic.get() also supports selection strings using logical or spatial queries. If you’re not familiar with selection syntax, visit User guide > Tools > Basic > Select. Let’s see how selection works beyond indices lists with some examples:

msm.get(molsys, element='atom', selection='group_index==20', name=True, index=True)

[['N', 'CA', 'C', 'O', 'CB', 'CG', 'CD'], [148, 149, 150, 151, 152, 153, 154]]

msm.get(molsys, element='atom', selection='molecule_type=="protein"', n_groups=True)

msm.get(molsys, element='molecule', selection='molecule_type=="water"', n_molecules=True)

msm.get(molsys, element='atom', selection='all within 7.0 angstroms of atom_index==0', n_atoms=True)

Finally, not all molecular system forms include all attributes. For example, an openmm.Topology object has no atom coordinates, and a file:inpcrd system may not contain chain names. When an attribute is unavailable, the function returns None.

inpcrd_file = msm.systems['pentalanine']['pentalanine.inpcrd']
msm.get(inpcrd_file, n_groups=True) is None

True

Note

Demo Systems Catalog

This tutorial uses demonstration datasets provided by MolSysMT. To explore the full catalog of bundled systems, forms, and file paths, visit the Demo Systems guide.

Examples with topological attributes#

Here you can find some additional examples where msm.basic.get() works over atoms, groups, components, chains, molecules, entities, bonds or system.

With atoms#

# Group id of atoms with index 0, 1 or 2
msm.get(molsys, element='atom', selection='atom_index in [0,1,2]', group_id=True)

['4', '4', '4']

# Number of groups in atoms with index 0, 1 or 2
msm.get(molsys, element='atom', selection='atom_index in [0,1,2]', n_groups=True)

# Index of groups in atoms with index 0 to 15
msm.get(molsys, element='atom', selection=range(5,10), group_index=True)

[0, 0, 0, 0, 1]

With groups#

# Id of groups with index 0, 1 or 2
msm.get(molsys, element='group', selection=[0,1,2], id=True)

['4', '5', '6']

# Index of atoms in groups with index 0 or 1
msm.get(molsys, element='group', selection=[0,1], atom_index=True)

[[0, 1, 2, 3, 4, 5, 6, 7, 8], [9, 10, 11, 12, 13, 14, 15]]

# Number of groups in molecules of type water
msm.get(molsys, element='group', selection='molecule_type=="water"', n_groups=True)

# Number of groups of type aminoacid
msm.get(molsys, element='group', selection='group_type=="amino acid"', n_groups=True)

With components#

msm.get(molsys, element='component', selection='molecule_type=="water"', index=True)

msm.get(molsys, element='component', selection=[0,1,2,3], n_waters=True)

[0, 0, 1, 1]

With molecules#

# Names of groups in molecule of index 0
msm.get(molsys, element='molecule', selection=[0,1], group_name=True)

[['LYS',
  'PRO',
  'GLN',
  'PRO',
  'ILE',
  'ALA',
  'ALA',
  'ALA',
  'ASN',
  'TRP',
  'LYS',
  'CYS',
  'ASN',
  'GLY',
  'SER',
  'GLU',
  'SER',
  'LEU',
  'LEU',
  'VAL',
  'PRO',
  'LEU',
  'ILE',
  'GLU',
  'THR',
  'LEU',
  'ASN',
  'ALA',
  'ALA',
  'THR',
  'PHE',
  'ASP',
  'HIS',
  'ASP',
  'VAL',
  'GLN',
  'CYS',
  'VAL',
  'VAL',
  'ALA',
  'PRO',
  'THR',
  'PHE',
  'LEU',
  'HIS',
  'ILE',
  'PRO',
  'MET',
  'THR',
  'LYS',
  'ALA',
  'ARG',
  'LEU',
  'THR',
  'ASN',
  'PRO',
  'LYS',
  'PHE',
  'GLN',
  'ILE',
  'ALA',
  'ALA',
  'GLN',
  'ASN',
  'ALA',
  'ILE',
  'THR',
  'ARG',
  'SER',
  'GLY',
  'ALA',
  'PHE',
  'THR',
  'GLY',
  'GLU',
  'VAL',
  'SER',
  'LEU',
  'GLN',
  'ILE',
  'LEU',
  'LYS',
  'ASP',
  'TYR',
  'GLY',
  'ILE',
  'SER',
  'TRP',
  'VAL',
  'VAL',
  'LEU',
  'GLY',
  'HIS',
  'SER',
  'GLU',
  'ARG',
  'ARG',
  'LEU',
  'TYR',
  'TYR',
  'GLY',
  'GLU',
  'THR',
  'ASN',
  'GLU',
  'ILE',
  'VAL',
  'ALA',
  'GLU',
  'LYS',
  'VAL',
  'ALA',
  'GLN',
  'ALA',
  'CYS',
  'ALA',
  'ALA',
  'GLY',
  'PHE',
  'HIS',
  'VAL',
  'ILE',
  'VAL',
  'CYS',
  'VAL',
  'GLY',
  'GLU',
  'THR',
  'ASN',
  'GLU',
  'GLU',
  'ARG',
  'GLU',
  'ALA',
  'GLY',
  'ARG',
  'THR',
  'ALA',
  'ALA',
  'VAL',
  'VAL',
  'LEU',
  'THR',
  'GLN',
  'LEU',
  'ALA',
  'ALA',
  'VAL',
  'ALA',
  'GLN',
  'LYS',
  'LEU',
  'SER',
  'LYS',
  'GLU',
  'ALA',
  'TRP',
  'SER',
  'ARG',
  'VAL',
  'VAL',
  'ILE',
  'ALA',
  'TYR',
  'GLU',
  'PRO',
  'VAL',
  'TRP',
  'ALA',
  'ILE',
  'GLY',
  'THR',
  'GLY',
  'LYS',
  'VAL',
  'ALA',
  'THR',
  'PRO',
  'GLN',
  'GLN',
  'ALA',
  'GLN',
  'GLU',
  'VAL',
  'HIS',
  'GLU',
  'LEU',
  'LEU',
  'ARG',
  'ARG',
  'TRP',
  'VAL',
  'ARG',
  'SER',
  'LYS',
  'LEU',
  'GLY',
  'THR',
  'ASP',
  'ILE',
  'ALA',
  'ALA',
  'GLN',
  'LEU',
  'ARG',
  'ILE',
  'LEU',
  'TYR',
  'GLY',
  'GLY',
  'SER',
  'VAL',
  'THR',
  'ALA',
  'LYS',
  'ASN',
  'ALA',
  'ARG',
  'THR',
  'LEU',
  'TYR',
  'GLN',
  'MET',
  'ARG',
  'ASP',
  'ILE',
  'ASN',
  'GLY',
  'PHE',
  'LEU',
  'VAL',
  'GLY',
  'GLY',
  'ALA',
  'SER',
  'LEU',
  'LYS',
  'PRO',
  'GLU',
  'PHE',
  'VAL',
  'GLU',
  'ILE',
  'ILE',
  'GLU',
  'ALA',
  'THR',
  'LYS'],
 ['SER',
  'LYS',
  'PRO',
  'GLN',
  'PRO',
  'ILE',
  'ALA',
  'ALA',
  'ALA',
  'ASN',
  'TRP',
  'LYS',
  'CYS',
  'ASN',
  'GLY',
  'SER',
  'GLU',
  'SER',
  'LEU',
  'LEU',
  'VAL',
  'PRO',
  'LEU',
  'ILE',
  'GLU',
  'THR',
  'LEU',
  'ASN',
  'ALA',
  'ALA',
  'THR',
  'PHE',
  'ASP',
  'HIS',
  'ASP',
  'VAL',
  'GLN',
  'CYS',
  'VAL',
  'VAL',
  'ALA',
  'PRO',
  'THR',
  'PHE',
  'LEU',
  'HIS',
  'ILE',
  'PRO',
  'MET',
  'THR',
  'LYS',
  'ALA',
  'ARG',
  'LEU',
  'THR',
  'ASN',
  'PRO',
  'LYS',
  'PHE',
  'GLN',
  'ILE',
  'ALA',
  'ALA',
  'GLN',
  'ASN',
  'ALA',
  'ILE',
  'THR',
  'ARG',
  'SER',
  'GLY',
  'ALA',
  'PHE',
  'THR',
  'GLY',
  'GLU',
  'VAL',
  'SER',
  'LEU',
  'GLN',
  'ILE',
  'LEU',
  'LYS',
  'ASP',
  'TYR',
  'GLY',
  'ILE',
  'SER',
  'TRP',
  'VAL',
  'VAL',
  'LEU',
  'GLY',
  'HIS',
  'SER',
  'GLU',
  'ARG',
  'ARG',
  'LEU',
  'TYR',
  'TYR',
  'GLY',
  'GLU',
  'THR',
  'ASN',
  'GLU',
  'ILE',
  'VAL',
  'ALA',
  'GLU',
  'LYS',
  'VAL',
  'ALA',
  'GLN',
  'ALA',
  'CYS',
  'ALA',
  'ALA',
  'GLY',
  'PHE',
  'HIS',
  'VAL',
  'ILE',
  'VAL',
  'CYS',
  'VAL',
  'GLY',
  'GLU',
  'THR',
  'ASN',
  'GLU',
  'GLU',
  'ARG',
  'GLU',
  'ALA',
  'GLY',
  'ARG',
  'THR',
  'ALA',
  'ALA',
  'VAL',
  'VAL',
  'LEU',
  'THR',
  'GLN',
  'LEU',
  'ALA',
  'ALA',
  'VAL',
  'ALA',
  'GLN',
  'LYS',
  'LEU',
  'SER',
  'LYS',
  'GLU',
  'ALA',
  'TRP',
  'SER',
  'ARG',
  'VAL',
  'VAL',
  'ILE',
  'ALA',
  'TYR',
  'GLU',
  'PRO',
  'VAL',
  'TRP',
  'ALA',
  'ILE',
  'GLY',
  'THR',
  'GLY',
  'LYS',
  'VAL',
  'ALA',
  'THR',
  'PRO',
  'GLN',
  'GLN',
  'ALA',
  'GLN',
  'GLU',
  'VAL',
  'HIS',
  'GLU',
  'LEU',
  'LEU',
  'ARG',
  'ARG',
  'TRP',
  'VAL',
  'ARG',
  'SER',
  'LYS',
  'LEU',
  'GLY',
  'THR',
  'ASP',
  'ILE',
  'ALA',
  'ALA',
  'GLN',
  'LEU',
  'ARG',
  'ILE',
  'LEU',
  'TYR',
  'GLY',
  'GLY',
  'SER',
  'VAL',
  'THR',
  'ALA',
  'LYS',
  'ASN',
  'ALA',
  'ARG',
  'THR',
  'LEU',
  'TYR',
  'GLN',
  'MET',
  'ARG',
  'ASP',
  'ILE',
  'ASN',
  'GLY',
  'PHE',
  'LEU',
  'VAL',
  'GLY',
  'GLY',
  'ALA',
  'SER',
  'LEU',
  'LYS',
  'PRO',
  'GLU',
  'PHE',
  'VAL',
  'GLU',
  'ILE',
  'ILE',
  'GLU',
  'ALA',
  'THR',
  'LYS']]

# Number of molecules of type protein
msm.get(molsys, element='molecule', selection='molecule_type=="protein"', n_molecules=True)

# Molecule type of molecules with index 1 to 9
msm.get(molsys, element='molecule', selection=range(1,10), molecule_type=True)

['protein',
 'water',
 'water',
 'water',
 'water',
 'water',
 'water',
 'water',
 'water']

With chains#

# Molecule type of molecules with index 1 to 9
msm.get(molsys, element='chain', selection='all', name=True)

['A', 'B', 'A', 'B']

# Molecule type of molecules with index 1 to 9
msm.get(molsys, element='chain', selection='all', id=True)

['A', 'B', 'C', 'D']

# Molecule type of molecules with index 1 to 9
msm.get(molsys, element='chain', selection='molecule_type=="protein"', id=True)

['A', 'B']

With entities#

# Name of entity with index 0
msm.get(molsys, element='entity', selection=0, name=True)

['TRIOSEPHOSPHATE ISOMERASE']

# Number of molecules in entity with index 1
msm.get(molsys, element='entity', selection=1, n_molecules=True)

[165]

# Index of molecules in entity with index 1
msm.get(molsys, element='entity', selection=1, molecule_index=True)

With bonds#

msm.get(molsys, element='atom', selection=[0,1,2,3,4,5], bonded_atoms=True)

[[1], [0, 2, 4], [1, 3, 9], [2], [1, 5], [4, 6]]

msm.get(molsys, element='atom', selection=[0,1,2,3,4,5], inner_bonded_atoms=True)

[[1], [0, 2, 4], [1, 3], [2], [1, 5], [4]]

msm.get(molsys, element='atom', selection=[0,1,2,3,4,5], bonded_atoms_pairs=True)

[[0, 1], [1, 2], [1, 4], [2, 3], [2, 9], [4, 5], [5, 6]]

msm.get(molsys, element='atom', selection=[0,1,2,3,4,5], inner_bonded_atoms_pairs=True)

[[0, 1], [1, 2], [1, 4], [2, 3], [4, 5]]

msm.get(molsys, element='atom', selection=[0,1,2,3,4,5], bond_index=True)

[[0], [0, 1, 2], [1, 3, 4], [3], [2, 5], [5, 6]]

msm.get(molsys, element='atom', selection=[0,1,2,3,4,5], n_bonds=True)

[1, 3, 3, 1, 2, 2]

msm.get(molsys, element='atom', selection=[0,1,2,3,4,5], inner_bond_index=True)

[[0], [0, 1, 2], [1, 3], [3], [2, 5], [5]]

msm.get(molsys, element='atom', selection=[0,1,2,3,4,5], n_inner_bonds=True)

[1, 3, 2, 1, 2, 1]

msm.select(molsys, element='bond', selection='group_index==3')

[26, 27, 28, 29, 30, 32, 33]

msm.get(molsys, element='bond', selection='group_index==3', index=True)

[26, 27, 28, 29, 30, 32, 33]

msm.get(molsys, element='bond', selection=[0,1,2,3,4], bonded_atoms=True)

[0, 1, 2, 3, 4, 9]

msm.get(molsys, element='bond', selection='group_index==3', bonded_atoms=True)

[25, 26, 27, 28, 29, 30, 31]

With the system#

The element system has some specific observables accounting for the amount of type of elements such as the number of aminoacid groups, ion molecules or protein molecules:

# Number of aminoacids and number of waters in the system
msm.get(molsys, element='system', n_amino_acids=True, n_waters=True)

[497, 165]

msm.get(molsys, element='system', n_bonds=True)

Examples with structural attributes#

Inspecting alternate sites#

For forms exposing sparse alternate-site mappings, request alternate_location=True. A query such as msm.get(molsys, selection=[4, 2], structure_indices=[2, 0, 2], alternate_location=True) returns three dictionaries in the requested structure order, including the repeated structure. Dictionary keys are integer source atom indices, so filtering atoms does not renumber keys to 0 and 1. Each entry’s atom_id values are string labels, independently of those indices. Join a site to the source atom with its key, not its atom ID.

Structures without alternate sites return empty dictionaries, and an absent attribute returns None. This query filters evidence; it does not choose an alternate conformation or move coordinates. The doctest in the API reference provides a complete three-atom example.

Extraction or conversion with an atom selection creates a new atom domain: retain its correspondence separately and use the extracted object’s indices when querying that object. The source-index rule applies to the system supplied to the query.

msm.get(molsys, element='system', n_structures=True)

msm.get(molsys, element='atom', selection=100, structure_indices=0, coordinates=True)

Magnitude	[[[1.8835 3.8270999999999997 5.0365]]]
Units	nanometer

msm.get(molsys, element='system', coordinates=True)

Magnitude

[[[1.8466999999999998 2.7638 8.3661]  [1.8580999999999999 2.8457 8.2415]  [1.7231 2.8536999999999995 8.1751]  ...  [2.685 6.2692 5.3171]  [0.0135 4.6709 3.6203]  [0.5324 6.512399999999999 5.142499999999999]]]

Units

nanometer

msm.get(molsys, element='system', structure_indices=0, box=True)

Magnitude	[[[4.3709999999999996 0.0 0.0] [0.0 7.765 0.0] [0.0 0.0 14.953999999999997]]]
Units	nanometer

box_lengths, box_angles, box_volume = msm.get(molsys, element='system', structure_indices=0,
                                              box_lengths=True, box_angles=True, box_volume=True)

box_lengths

Magnitude	[[4.371 7.765 14.954]]
Units	nanometer

box_angles

Magnitude	[[1.570796 1.570796 1.570796]]
Units	radian

box_volume

Magnitude	[507.55094750999984]
Units	nanometer³

Querying empty connectivity#

A geometric molecular system can validly have an empty bond collection. For a native four-atom MolSys or Topology, msm.get(molsys, element='atom', n_bonds=True) returns [0, 0, 0, 0]; bond_index=True returns [[], [], [], []]. Explicit atom subsets keep one count or collection per selected atom, and an empty atom selection returns an empty list. Internal bond indices also remain empty. With element='system' (the default), n_bonds=True returns the total 0.

This differs from an attribute unavailable in the input form, which can return None. Zero observed/stored bonds do not prove complete chemistry and must not be used to certify chemical typing or a force-field-ready molecular graph.

With element='group', n_bonds=True returns one count of distinct incident bonds per selected group, including bonds to atoms outside that group. An internal bond contributes once; a bond between two groups contributes once to each group. Empty connectivity gives zero per selected group and an empty group selection gives []. Native MolSys and Topology use the selected chemical_state; an explicit state index does not change the stored reference.

Querying partial hierarchy#

A source can contain atoms without group membership. After combining a protein with an SDF ligand, native atom-level group ID/name/type queries keep real protein values and return None for ungrouped ligand atoms. Group-based molecule/entity queries propagate missing parents. Missing membership never means group index 0. A wholly absent group table retains the existing group-identity None result; empty selections on a populated hierarchy return an empty list.

A supported single-record SDF has one structure: msm.get(source, n_structures=True) returns 1, [0] selects that structure, and an empty frame selection returns 0. Other frame indices raise. Use indices independently of IDs.