mdciao: Accessible Analysis and Visualization of Molecular Dynamics Simulation Data

mdciao is a Python module that provides quick, "one-shot" command-line tools to analyze molecular simulation data using residue-residue distances. mdciao tries to automate as much as possible for non-experienced users while remaining highly customizable for advanced users, by exposing an API to construct your own analysis workflow.

Under the hood, the module mdtraj is doing most of the computation and handling of molecular information, using BioPython for sequence alignment, pandas for many table and IO related operations, and matplotlib for visualization. It tries to automatically use the consensus nomenclature for

• GPCRs

  • via Ballesteros-Weinstein-Numbering or structure-based schemes by Gloriam et al for the receptor's TM domain, or
  • via generic-residue-numbering for the GAIN domain of adhesion GPCRs

• G-proteins

  • via Common G-alpha Numbering (CGN)

• Kinases

  • via their 85 pocket-residue numbering scheme

using local files or on-the-fly lookups of the GPCRdb and/or KLIFS.

Licenses

• mdciao is licensed under the GNU Lesser General Public License v3.0 or later (LGPL-3.0-or-later, see the LICENSE.txt).

• mdciao uses a modified version of the method mdtraj.compute_contacts of mdtraj. This modified version is published along with mdciao and can be found in contacts/_md_compute_contacts.py. Please see that file for details on the modifications.

• Modules used by mdciao have different licenses. You can check any module's license in your Python environment using pip-licenses:

  >>> pip-licenses | grep module_name

Documentation

Currently, docs are hosted at https://mdciao.org.

System Requirements

mdciao is developed in GNU/Linux, and CI-tested via github actions for GNU/Linux and MacOs. Tested Python versions are:

• GNU/Linux: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12
• MacOs: 3.7, 3.8, 3.9, 3.10, 3.11, 3.12. For Python 3.7, four CI-tests involving mdtraj.compute_dssp , are skipped because of a hard to reproduce, random segmentation fault, which apparently wont fix, see here mdtraj/mdtraj#1574 and here.

So everything should work out of the box in these conditions.

Python 3.13 users

Python 3.13 support is unofficial, because the module bezier currently requires python <=3.12.

Still, you can install mdciao in Python 3.13 if you install bezier previously with these environment variables:

>>> BEZIER_NO_EXTENSION="True" BEZIER_IGNORE_VERSION_CHECK="True" pip install bezier
>>> pip install mdciao

You can check what these variables do here.

Since mdciao installs and passes the CI-tests for Python 3.13 in such an environment, you can use it at your own risk. Please report on any issues you might find.

Authors

mdciao is written and maintained by Guillermo Pérez-Hernández (ORCID) currently at the Institute of Medical Physics and Biophysics in the Charité Universitäsmedizin Berlin.

Please cite:

• mdciao: Accessible Analysis and Visualization of Molecular Dynamics Simulation Data

  Guillermo Pérez-Hernández, Peter-Werner Hildebrand

  bioRxiv 2022.07.15.500163

  https://doi.org/10.1101/2022.07.15.500163

• mdciao: Accessible Analysis and Visualization of Molecular Dynamics Simulation Data

  Guillermo Pérez-Hernández, Peter-Werner Hildebrand

  PLOS Computational Biology, 2025 (accepted, will supersede the bioRxiv reference)

Scope

mdciao originated as a loose collection of CLI scripts used in our lab to streamline contact-frequency analysis of MD simulations with mdtraj, which is doing a lot of the heavy work under the hood of mdciao. The goal was to take the less scripting-affine lab members from their raw data to informative graphs about the general vicinity of their residues of interest without much hassle. From there, it grew to incorporate many of the things routinely done in the lab (with a focus on GPCRs and G proteins) and ultimately a package available for third-party use was made.

The main publications which have driven the development of mdciao are:

• Function and dynamics of the intrinsically disordered carboxyl terminus of β2 adrenergic receptor.

  Heng, J., Hu, Y., Pérez-Hernández, G. et al.

  Nat Commun 14, 2005 (2023).

  https://doi.org/10.1038/s41467-023-37233-1

• Time-resolved cryo-EM of G-protein activation by a GPCR.

  Papasergi-Scott, M.M., Pérez-Hernández, G., Batebi, H. et al.

  Nature 629, 1182–1191 (2024).

  https://doi.org/10.1038/s41586-024-07153-1

• Mechanistic insights into G-protein coupling with an agonist-bound G-protein-coupled receptor.

  Batebi, H., Pérez-Hernández, G., Rahman, S.N. et al.

  Nat Struct Mol Biol (2024).

  https://doi.org/10.1038/s41594-024-01334-2

• Generic residue numbering of the GAIN domain of adhesion GPCRs.

  Seufert, F., Pérez-Hernández, G., Pándy-Szekeres, G. et al.

  Nat Commun 16, 246 (2025).

  https://doi.org/10.1038/s41467-024-55466-6

TODOs

You can find an informal list of TODOs and known issues here.