Get label#

Generating label strings for molecular system elements

The basic module in MolSysMT includes a function to generate custom label strings for elements in a molecular system. These labels are useful for tables, plots, or any text-based reporting.

As it will be shown in the following section, the format of the label string and the attributes included are defined by the user.

Hint

Visit the section User guide > Introduction > Molecular System > Element in case you are not familiar with the concept of “element” in MolSysMT.

Visit the section User guide > Introduction > Molecular System > Attribute in case you are not familiar with the concept of “attribute” in MolSysMT.

Added in version 1.0.0.

How this function works#

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

The function molsysmt.basic.get_label() allows you to get label strings of specific elements of a molecular system with the format you choose. Let’s illustrate how this function works with some few examples:

import molsysmt as msm

/home/diego/Myopt/miniconda3/envs/MolSysMT@uibcdf_3.12/lib/python3.12/site-packages/nglview/__init__.py:12: UserWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html. The pkg_resources package is slated for removal as early as 2025-11-30. Refrain from using this package or pin to Setuptools<81.
  import pkg_resources

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 be invoked also from the main level of the library. Hence, molsysmt.get_label() is the same method 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]']