Compare#

Comparing molecular systems across selected attributes.

The function molsysmt.basic.compare() allows you to compare two molecular systems, or specific parts of them, based on selected attributes. The function can return a single boolean or a detailed per-attribute report. Differences in array shapes or collection sizes are reported as False for the affected attributes; they are ordinary comparison results and do not emit warnings.

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

Matching missing metadata entries compare equal, including NaN values used for undefined labels. A missing entry and a populated entry compare unequal. Use output_type="dictionary" to inspect which attributes differ.

Basic usage#

Let’s explore how to compare molecular systems using three systems derived from the T4 lysozyme dataset (181l.bcif.gz):

import molsysmt as msm

molsys_A = msm.systems['T4 lysozyme L99A']['181l.bcif.gz']
molsys_B = msm.convert(molsys_A, to_form='molsysmt.MolSys')
molsys_C = msm.extract(molsys_B, selection='molecule_type=="protein"')

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.

Systems \(A\) and \(B\) are equivalent in content—they only differ in form (mmcif file vs molsysmt.MolSys). System \(C\) is a subset containing only the protein part of \(B\).

Let’s inspect the state of \(B\) and \(C\) before comparing them:

msm.info(molsys_B)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_waters	n_ions	n_small_molecules	n_proteins	n_structures
molsysmt.MolSys	1441	302	141	6	141	5	136	2	2	1	1

msm.info(molsys_C)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_proteins	n_structures
molsysmt.MolSys	1289	162	1	1	1	1	1	1

Now let’s compare \(A\) with \(B\), and \(B\) with \(C\):

msm.compare(molsys_A, molsys_B)

True

msm.compare(molsys_B, molsys_C)

False

Tip

All methods defined in the molsysmt.basic module can also be invoked from the library’s top level. Hence, molsysmt.compare() is the same function as molsysmt.basic.compare().

By default, only the elements are compared. Other attributes such as coordinates, box, or n_atoms can be included explicitly in the comparison:

msm.compare(molsys_A, molsys_B, coordinates=True, box=True, n_atoms=True)

True

msm.compare(molsys_B, molsys_C, coordinates=True, box=True, n_atoms=True)

False

A detailed report showing the result for each attribute can be obtained by setting output_type='dictionary':

msm.compare(molsys_B, molsys_C, coordinates=True, box=True, n_atoms=True, output_type='dictionary')

{'n_atoms': False, 'box': True, 'coordinates': False}

You can also test for the negation of a condition by setting the attribute value to False:

msm.compare(molsys_B, molsys_C, coordinates=False, box=True, n_atoms=False, output_type='dictionary')

{'n_atoms': True, 'box': True, 'coordinates': True}

Comparing selections#

You can restrict the comparison to specific atom selections in each system. For example, comparing the protein selection of \(B\) against system \(C\) (which is protein-only) yields True:

msm.compare(molsys_B, molsys_C, selection='molecule_type=="protein"', selection_2='all')

True

Comparing structures#

Similarly, when comparing multi-structure systems, use structure_indices for the first system and structure_indices_2 for the second:

msm.compare(molsys_B, molsys_C, structure_indices=0, structure_indices_2=0)

False