Get label#

Generating label strings for molecular system elements.

The function molsysmt.basic.get_label() allows you to generate custom label strings for elements in a molecular system. These labels are useful for tables, plots, or text-based reporting. The format of the label string and the attributes included are defined by the user.

Hint

Visit the section Elements or Attributes if you are not familiar with the concepts of “element” or “attribute” in MolSysMT.

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_label().

Basic usage#

Let’s show how this function works using a PDB structure (1BRS):

import molsysmt as msm

molsys = msm.convert('1BRS')

Let’s for instance get a label for atoms with atom index in [0,1,2] with the format “atom_name-atom_id@atom_index”:

msm.get_label(molsys, element='atom', selection=[0,1,2], string='{atom_name}-{atom_id}@{atom_index}')

['N-1@0', 'CA-2@1', 'C-3@2']

Tip

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

As you can see in the previous cell, the format is introduced with the value of the string input argument. This string value must take the same form of a f-string with the elements attributes as local variables.

Here we use shorthand attribute names like name and id, which are automatically interpreted as atom_name and atom_id since element='atom'.

msm.get_label(molsys, element='atom', selection=[0,1,2], string='{name}_{id}')

['N_1', 'CA_2', 'C_3']

The attribute names “name”, “id” or “index” are intepreted as the corresponding attributes for the chosen elements. For instance, “name” when element='atom' is automatically replaced by “atom_name” as it was shown in the last cell.

Now, let’s include some other attributes in the label strings:

msm.get_label(molsys, element='atom', selection=[0,1,2], string='{atom_name}_{atom_id}-{group_name}_{group_id}')

['N_1-VAL_3', 'CA_2-VAL_3', 'C_3-VAL_3']

The elements to be labeled can be chosen with the input argument element and its selection with the argument selection:

msm.get_label(molsys, element='group', selection='group_name in ["THR", "TYR"] within 6.0 angstroms of group_index==10',
              string='{group_name}{group_id}/{entity_name}')

['TYR13/BARNASE', 'THR16/BARNASE', 'TYR17/BARNASE']

More descriptive or longer strings can also be generated. For instance, if you need to include detailed labels for each non-water component in a table, molsysmt.basic.get_label() allows you to automate this:

msm.get_label(molsys, element='component', selection='molecule_type!="water"',
              string='Component {component_index} in {chain_id} of {entity_name} [{n_atoms} atoms & {n_bonds} bonds]')

['Component 0 in A of BARNASE [864 atoms & 885 bonds]',
 'Component 1 in B of BARNASE [878 atoms & 899 bonds]',
 'Component 2 in C of BARNASE [839 atoms & 860 bonds]',
 'Component 3 in D of BARSTAR [517 atoms & 529 bonds]',
 'Component 4 in D of BARSTAR [176 atoms & 176 bonds]',
 'Component 5 in E of BARSTAR [488 atoms & 500 bonds]',
 'Component 6 in E of BARSTAR [177 atoms & 177 bonds]',
 'Component 7 in F of BARSTAR [699 atoms & 712 bonds]']