.. mdciao documentation master file, created by
   sphinx-quickstart on Fri Sep  6 11:54:24 2019.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

mdciao: Analysis of Molecular Dynamics Simulations Using Residue Neighborhoods
==============================================================================

|Python Package| |Coverage| |DOI| |License|

.. figure:: imgs/banner.png
   :scale: 33%

.. figure:: imgs/distro_and_violin.png
   :scale: 25%

.. _my-reference-label:
.. figure:: imgs/interface.combined.png
   :scale: 33%

``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 <https://mdtraj.org/>`_ is doing most of the computation and handling of molecular information, using `BioPython <https://biopython.org/>`_ for sequence alignment, `pandas <https://pandas.pydata.org/>`_ for many table and IO related operations, and `matplotlib <https://matplotlib.org>`_ for visualizaton. It tries to automatically use the consensus nomenclature for

* GPCRs, e.g. `Ballesteros-Weinstein-Numbering <https://www.sciencedirect.com/science/article/pii/S1043947105800497>`_ or structure-based schemes by `Gloriam et al <https://doi.org/10.1016/j.tips.2014.11.001>`_, and
* G-proteins, via `Common G-alpha Numbering (CGN) <https://www.mrc-lmb.cam.ac.uk/CGN/faq.html>`_

by either using local files or on-the-fly lookups of the `GPCRdb <https://gpcrdb.org/>`_
and/or `<https://www.mrc-lmb.cam.ac.uk/CGN/>`_

Basic Principle
---------------

``mdciao``  takes the files typically generated by a molecular dynamics (MD) simulation, i.e.

* topology files, like *prot.gro* or *prot.pdb*
* trajectory files, like *traj1.xtc*, *traj2.xtc*

and calculates the  time-traces of residue-residue distances, and from there, **contact frequencies** and **distance distributions**.

.. note::

 A note of caution regarding the above definitions for *contact* and *frequency*:

 * the kinetic information is averaged out. Contacts quickly breaking and forming and contacts that break (or form) only once **will have the same frequency** as long as the **fraction of total time** they are formed is the same. For analysis taking kinetics into account, use. e.g. `pyemma <http://mdtraj.org>`_.
 * The sharp, "distance-only" cutoff can sometimes over- or under-represent some interaction types. Modules like `get_contacts <https://github.com/getcontacts/getcontacts>`_ capture these interactions better, and have a ton of other features features.
 * Frequencies are just **averages** over the input data. In some cases, *simply* computing averages is a bad idea. The user is `responsible for deciding over what data to average <https://en.wikipedia.org/wiki/Garbage_in,_garbage_out>`_. For example, if your data is highly heterogenous you might want to `cluster <https://manual.gromacs.org/documentation/2018/onlinehelp/gmx-cluster.html>`_ your data into into `cluster1.xtc`, ``cluster.2.xtc`` etc and then do a per-cluster analysis with ``mdciao``

 These issues (if/when they arise) can be spotted easily by looking at the time-traces and informed decisions can be made wrt to parameters like the cutt-off value, number of contacts displayed and many others.

.. |Python Package| image::
   https://github.com/gph82/mdciao/actions/workflows/python-package.yml/badge.svg
   :target: https://github.com/gph82/mdciao/actions/workflows/python-package.yml

.. |Coverage| image::
   https://codecov.io/gh/gph82/mdciao/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/gph82/mdciao

.. |License| image::
    https://img.shields.io/github/license/gph82/mdciao

.. |DOI| image::
   https://zenodo.org/badge/DOI/10.5281/zenodo.5643177.svg
   :target: https://doi.org/10.5281/zenodo.5643177

.. there's this issue about the self-referencing TOC that I cannot solve
.. https://github.com/sphinx-doc/sphinx/issues/4602

.. toctree::
   :hidden:

   installation
   CLI Tutorial <overview>
   API Jupyter Notebook Tutorial <notebooks/Tutorial.ipynb>
   notebooks/Covid-19-Spike-Protein-Example.ipynb
   notebooks/Covid-19-Spike-Protein-Interface.ipynb
   cli_cli/cli_cli
   api/api
   FAQ