Merge pull request #52 from gph82/interface_selection

Mostly, this PR is about:
1) the way interfaces are defined, including some API changes&breaks
2) using consensus labels as much as possible
3) enable 'fragments'=heuristic_name (e.g. "chains") when possible (still not everywhere)
4) Pull up some returned values to be accessible to the user, e.g. flareplot_attrs for finer tunig and repframes to access geometries directly after wrappers of the underlying methods have been called (these are some API breaks) 
5) Include a new example dataset and notebook

There's many other minor changes to the docs, typos, some smaller refactors but the above list summarizes the largest changes.

We expand a bit on 1) and 2)

1.1) It tries to differentiate better between fragmenting for display and tagging purposes ('fragments') vs fragmenting for interface selection  'frag_idxs_group_1, frag_idxs_group_2' are renamed 'interface_selection_1, interface_selection_2', and the docs try to explain this better.

1.2) A new feature is that selecting interface members can be done using consensus descriptors ("TM6" vs "TM3") regardless of what fragmentation heuristic is used ("chains") as long as some consensus information is there.

1.3) To give even finer control over interface selection, new optarg 'AA_selection' is introduced to fine tune the interface definition.

1.4) Instead of raising exception, self-contacts "TM3" vs "TM*" will simply delete self-contacts (and inform the user) unless 'self_interface=True'. 

2.1) The low level label-generating-methods get new options for 'AA_format'='just_consensus' and 'try_consensus', which allow the higher level methods like compare_violins and compare_groups_of_contacts to to 'sort_by'='consensus' (via plot_unified_freq_dicts via the lower-level sorter methods)

doc/FAQ.rst

@@ -3,7 +3,7 @@ FAQ Notebooks
 
 .. toctree::
 
-   notebooks/Missing_Contacts.ipynb
-   notebooks/Flareplot_Schemes.ipynb
-   notebooks/Comparing_CGs_Bars.ipynb
-   notebooks/Comparing_CGs_Flares.ipynb
+   notebooks/02.Missing_Contacts.ipynb
+   notebooks/05.Flareplot_Schemes.ipynb
+   notebooks/03.Comparing_CGs_Bars.ipynb
+   notebooks/04.Comparing_CGs_Flares.ipynb

doc/basic_usage.rst

@@ -19,7 +19,7 @@ Below you will find a very simple example of how to use ``mdciao`` from the comm
 
 This basic command::
 
- mdc_neighborhoods.py prot.pdb traj.xtc --residues L394 -nf #nf: don't use fragments
+ mdc_neighborhoods.py top.pdb traj.xtc --residues L394 -nf #nf: don't use fragments
 
 
 will print the following to the terminal (some headers have been left out)::

doc/cli_stub.rst

@@ -48,4 +48,4 @@ What these tools do is:
 * mdc_residues
     Find residues in an input topology using Unix filename pattern matching. Example :ref:`here <residues_HL>`.
 
-You can see their documentation by using the ``-h`` flag when invoking them from the command line, keep reading the ref:`Highlights` or the :ref:`CLI Reference`.
+You can see their documentation by using the ``-h`` flag when invoking them from the command line, keep reading the :ref:`Highlights` or the :ref:`CLI Reference`.

doc/gallery.rst

@@ -13,21 +13,21 @@ The notebooks can be accessed locally by issuing::
 
 from the CLI. This will create a local "sandboxed" copy of the notebooks,
 which you can modify and play around with without breaking
-the original notebooks. Note: all notebooks except the last two.
+the original notebooks. Note: the Covid notebooks are not shipped with `mdciao`.
 
 Tutorials
 ---------
 
 .. list-table::
 
     * - .. figure:: _build/html/_images/interface.combined.png
-           :target: notebooks/Tutorial.html
+           :target: notebooks/01.Tutorial.html
            :height: 100px
 
            ..
 
-           |br| `One single notebook providing <notebooks/Tutorial.html>`_
-           |br| `an overview of mdciao <notebooks/Tutorial.html>`_
+           |br| `One single notebook providing <notebooks/01.Tutorial.html>`_
+           |br| `an overview of mdciao <notebooks/01.Tutorial.html>`_
 
 FAQs
 ----
@@ -36,40 +36,40 @@ how particular optional parameters affect the output of some methods.
 
 .. list-table::
 
-    * - .. figure:: _build/doctrees/nbsphinx/notebooks_Missing_Contacts_15_1.png
-           :target: notebooks/Missing_Contacts.html
+    * - .. figure:: _build/doctrees/nbsphinx/notebooks_02.Missing_Contacts_15_1.png
+           :target: notebooks/02.Missing_Contacts.html
            :height: 100px
 
            ..
 
-           |br| `Missing Contacts <notebooks/Missing_Contacts.html>`_
+           |br| `Missing Contacts <notebooks/02.Missing_Contacts.html>`_
 
       - .. figure:: _build/html/_images/notebooks_Comparing_CGs_Bars_41_1.png
-           :target: notebooks/Comparing_CGs_Bars.html
+           :target: notebooks/03.Comparing_CGs_Bars.html
            :height: 100px
 
            ..
 
-           |br| `Comparing Frequencies: <notebooks/Comparing_CGs_Bars.html>`_
-           |br| `Bar Plots <notebooks/Comparing_CGs_Bars.html>`_
+           |br| `Comparing Frequencies: <notebooks/03.Comparing_CGs_Bars.html>`_
+           |br| `Bar Plots <notebooks/03.Comparing_CGs_Bars.html>`_
 
     * - .. figure:: _build/html/_images/notebooks_Comparing_CGs_Flares_41_1.png
-           :target: notebooks/Comparing_CGs_Flares.html
+           :target: notebooks/04.Comparing_CGs_Flares.html
            :height: 100px
 
            ..
 
-           |br| `Comparing Frequencies: <notebooks/Comparing_CGs_Flares.html>`_
-           |br| `Flareplots <notebooks/Comparing_CGs_Flares.html>`_
+           |br| `Comparing Frequencies: <notebooks/04.Comparing_CGs_Flares.html>`_
+           |br| `Flareplots <notebooks/04.Comparing_CGs_Flares.html>`_
 
       - .. figure:: _build/doctrees/nbsphinx/notebooks_Flareplot_Schemes_22_1.png
-           :target: notebooks/Flareplot_Schemes.html
+           :target: notebooks/05.Flareplot_Schemes.html
            :height: 100px
 
            ..
 
-           |br| `Controlling Flareplots: <notebooks/Flareplot_Schemes.html>`_
-           |br| `Schemes <notebooks/Flareplot_Schemes.html>`_
+           |br| `Controlling Flareplots: <notebooks/05.Flareplot_Schemes.html>`_
+           |br| `Schemes <notebooks/05.Flareplot_Schemes.html>`_
 
 Examples
 --------
@@ -79,23 +79,23 @@ They are the best starting point to copy and modify with your own data.
 .. list-table::
 
     * - .. figure:: _build/html/_images/notebooks_Manuscript_17_0.png
-           :target: notebooks/Manuscript.html
+           :target: notebooks/08.Manuscript.html
            :height: 100px
 
            ..
 
-           |br| `Interfaces: <notebooks/Manuscript.html>`_
-           |br| `β2 Adrenergic Receptor in Complex with <notebooks/Manuscript.html>`_
-           |br| `Empty Gs-Protein <notebooks/Manuscript.html>`_
+           |br| `Interfaces: <notebooks/08.Manuscript.html>`_
+           |br| `β2 Adrenergic Receptor in Complex with <notebooks/08.Manuscript.html>`_
+           |br| `Empty Gs-Protein <notebooks/08.Manuscript.html>`_
 
       - .. figure:: _build/html/_images/notebooks_EGFR_Kinase_Inhibitors_14_0.png
-           :target: notebooks/EGFR_Kinase_Inhibitors.html
+           :target: notebooks/07.EGFR_Kinase_Inhibitors.html
            :height: 100px
 
            ..
 
-           |br| `Binding-Pockets: <notebooks/EGFR_Kinase_Inhibitors.html>`_
-           |br| `EGFR Kinase Inhibitors <notebooks/EGFR_Kinase_Inhibitors.html>`_
+           |br| `Binding-Pockets: <notebooks/07.EGFR_Kinase_Inhibitors.html>`_
+           |br| `EGFR Kinase Inhibitors <notebooks/07.EGFR_Kinase_Inhibitors.html>`_
 
     * - .. figure:: _build/html/_images/notebooks_Covid-19-Spike-Protein-Example_23_1.png
            :target: notebooks/Covid-19-Spike-Protein-Example.html
@@ -116,15 +116,22 @@ They are the best starting point to copy and modify with your own data.
            |br| `Example 2: Molecular Interfaces <notebooks/Covid-19-Spike-Protein-Interface.html>`_
 
     * - .. figure:: imgs/MSA_via_Consensus_Labels.png
-           :target: notebooks/MSA_via_Consensus_Labels.html
+           :target: notebooks/06.MSA_via_Consensus_Labels.html
            :height: 100px
 
            ..
 
-           |br| `3D Multiple Sequence Alignment via <notebooks/MSA_via_Consensus_Labels.html>`_
-           |br| `Consensus Labels on μ-Opioid Receptor, <notebooks/MSA_via_Consensus_Labels.html>`_
-           |br| `β2 Adregneric Receptor, Opsin, and <notebooks/MSA_via_Consensus_Labels.html>`_
-           |br| `Dopamine D1 Receptor <notebooks/MSA_via_Consensus_Labels.html>`_
+           |br| `3D Multiple Sequence Alignment via <notebooks/06.MSA_via_Consensus_Labels.html>`_
+           |br| `Consensus Labels on μ-Opioid Receptor, <notebooks/06.MSA_via_Consensus_Labels.html>`_
+           |br| `β2 Adregneric Receptor, Opsin, and <notebooks/06.MSA_via_Consensus_Labels.html>`_
+           |br| `Dopamine D1 Receptor <notebooks/06.MSA_via_Consensus_Labels.html>`_
 
+      - .. figure:: imgs/MSA_via_Consensus_Labels.png
+           :target: notebooks/09.Consensus_Labels.html
+           :height: 100px
+
+           ..
 
-      - ..
+           |br| `Contact Frequencies  <notebooks/09.Consensus_Labels.html>`_
+           |br| `for multiple systems <notebooks/09.Consensus_Labels.html>`_
+           |br| `via consensus labels <notebooks/09.Consensus_Labels.html>`_

doc/highlights.rst

@@ -8,7 +8,7 @@ Highlights
 .. _`initial example`:
 * paper-ready tables and figures from the command line::
 
-   mdc_neighborhoods.py prot.pdb traj.xtc -r L394 --GPCR adrb2_human --CGN gnas2_human -ni -at #ni: not interactive, at: show atom-types
+   mdc_neighborhoods.py top.pdb traj.xtc -r L394 --GPCR adrb2_human --CGN gnas2_human -ni -at #ni: not interactive, at: show atom-types
 
   .. figure:: imgs/bars_and_PDF.png
       :scale: 40%
@@ -78,7 +78,7 @@ Highlights
   - *G.HN.** : CGN-nomenclature for the :math:`G\alpha_N`-subunit
  You can check your selection **before** running a computation by using ``mdc_residues.py``::
 
-  >>> mdc_residues.py GLU*,P0G,380-394,G.HN.* prot.pdb --GPCR adrb2_human --CGN GNAS2_HUMAN -ni
+  >>> mdc_residues.py GLU*,P0G,380-394,G.HN.* top.pdb --GPCR adrb2_human --CGN GNAS2_HUMAN -ni
   Your selection 'GLU*,P0G,380-394,G.HN.*' yields:
      residue      residx    fragment      resSeq        GPCR         CGN
        GLU10           6           0          10        None     G.HN.27
@@ -148,7 +148,7 @@ Highlights
 
 * use fragment definitions --like the ones above, ``0`` for the :math:`G\alpha`-unit and ``3`` for the receptor-- to compute interfaces in an automated way, i.e. without having to specifying individual residues::
 
-   >>> mdc_interface.py prot.pdb traj.xtc -fg1 0 -fg2 3 --GPCR adrb2_human --CGN GNAS2_HUMAN -t "3SN6 beta2AR-Galpha interface" -ni
+   >>> mdc_interface.py top.pdb traj.xtc -fg1 0 -fg2 3 --GPCR adrb2_human --CGN GNAS2_HUMAN -t "3SN6 beta2AR-Galpha interface" -ni
    ...
    The following 50 contacts capture 35.56 (~96%) of the total frequency 36.88 (over 75 contacts with nonzero frequency).
    As orientation value, the first 44 ctcs already capture 90.0% of 36.88.
@@ -239,7 +239,7 @@ Highlights
 
   The command::
 
-   >>> mdc_sites.py prot.pdb traj.xtc --site tip.json -at -nf -sa #sa: short AA-names
+   >>> mdc_sites.py top.pdb traj.xtc --site tip.json -at -nf -sa #sa: short AA-names
    ...
    The following files have been created:
    ./sites.overall@4.0_Ang.pdf
@@ -285,7 +285,7 @@ Highlights
 
   Now we use ``mdc_neighborhoods.py`` on our data::
 
-   >>> mdc_neighborhoods.py prot.pdb traj.xtc -r R131 -nf -o 3SN6.MD
+   >>> mdc_neighborhoods.py top.pdb traj.xtc -r R131 -nf -o 3SN6.MD
    ...
    The following 4 contacts capture 2.12 (~100%) of the total frequency 2.12 (over 5 contacts with nonzero frequency).
    ...

doc/index.rst

@@ -37,12 +37,12 @@ Basic Principle
 
 ``mdciao``  takes the files typically generated by a molecular dynamics (MD) simulation, i.e.
 
-* topology files, like *prot.gro* or *prot.pdb*
+* topology files, like *prot.gro* or *top.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**. The most simple command line call would look approximately like this::
 
- mdc_neighborhoods.py prot.pdb traj.xtc --residues L394
+ mdc_neighborhoods.py top.pdb traj.xtc --residues L394
  [...]
  The following 5 contacts capture 3.88 (~90%) of the total frequency 4.31 (over 7 contacts with nonzero frequency).
  As orientation value, the first 5 ctcs already capture 90.0% of 4.31.