MDAnalysis · ojeda-e · Aug 8, 2021 · Aug 4, 2021 · Aug 4, 2021 · Aug 6, 2021
diff --git a/docs/conf.py b/docs/conf.py
@@ -49,8 +49,10 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'sphinx.ext.extlinks',
+    'sphinx.ext.autosectionlabel'
 ]
 
+autosectionlabel_prefix_document = True
 autosummary_generate = True
 napoleon_google_docstring = False
 napoleon_use_param = False

diff --git a/docs/source/_static/AtomsReference.png b/docs/source/_static/AtomsReference.png
diff --git a/docs/source/_static/AvgFrames.png b/docs/source/_static/AvgFrames.png
diff --git a/docs/source/_static/DeriveSurfCurv_.png b/docs/source/_static/DeriveSurfCurv_.png
diff --git a/docs/source/_static/DiagramAlgorithm.png b/docs/source/_static/DiagramAlgorithm.png
diff --git a/docs/source/_static/example_mean_membrane.png b/docs/source/_static/example_mean_membrane.png
diff --git a/docs/source/_static/example_mean_membrane_contour.png b/docs/source/_static/example_mean_membrane_contour.png
diff --git a/docs/source/_static/grid.png b/docs/source/_static/grid.png
diff --git a/docs/source/pages/Algorithm.rst b/docs/source/pages/Algorithm.rst
@@ -1,47 +1,121 @@
+.. role:: raw-math(raw) :format: latex html
+
 Algorithm
 =========================================================
 
-The membrane curvature MDAnalysis module calculates the mean and Gaussian curvature 
-from surfaces derived by a group of reference. By default, the group of reference 
-implemented are lipid headgroups.
+Overview
+---------
+
+
+MembraneCurvature calculates mean and Gaussian curvature of surfaces derived
+from atoms of reference in 4 steps:
+
+:ref:`select-atoms`
+
+:ref:`set-grid`
+
+:ref:`derive-surface-curvature` 
+
+:ref:`iterate`
 
-The algorithm locates all the atoms in the group of reference and maps each element 
-of the group to a grid of `m x n` dimensions. The dimensions of the grid are 
-determined by the length of the simulation box in the first frame of the 
-trajectory.
+A summary of the algorithm used in MembraneCurvature is shown in the following
+diagram:
 
-The grid is then divided in `m x n` elements, with unit cells of width `uw` = 2nm 
-(default value). In this way, for every atom in the group of reference an indexed cell 
-in the grid is assigned according to their respective `x` and `y` coordinates.
-i.e. `(x, y) ↦ [i, j]`. 
+|diagram|
+
+.. _select-atoms:
+
+1. Select atoms of reference
+-----------------------------
+
+The first step in the algorithm consists in selecting atoms that will be used as
+a reference to derive a surface. This selection will be contained in an
+AtomGroup. Typically in biological membranes, lipid headgroups are the most
+common elements to use as an AtomGroup of reference. 
+
+|atoms|
+
+.. _set-grid:
+
+2. Set grid
+-------------
+The dimensions of the grid are determined by the size of the simulation box
+contained in the `MDAnalysis Universe`_. The grid comprises `n_x_bins` x `n_y_bins` number of bins.
 
 |grid|
 
-Once the grid is populated with the atoms in the group of reference, the associated
-`z` coordinate of each atom is stored in an array assigned to each [i, j] unit cell.
-The length of these arrays will depend on the number of atoms of reference that
-are mapped to a given `[i, j]` unit cell. Subsequently, once all values of `z` are
-stored, the mean value of `z` stored in that array is calculated. Since this operation 
-is performed for every frame, the length of the array containing the mean `z` position
-will be determined by the number of frames iterated in the trajectory.
+For every atom in the AtomGroup of reference, MembraneCurvature assigns an index
+in the grid, according to their respective `x` and `y` coordinates. i.e. `(x, y) ↦ [l, m]`. 
+
+.. note::
+  Unless the user provides a different input, the dimensions of the grid will be determined by
 
-.. code-block:: python
+  .. code-block:: python
 
-    len(reference_atoms[i,j]) == len(u.trajectory)
+      grid_dimension_x = (0, universe.dimensions[0])
+      grid_dimension_y = (0, universe.dimensions[1])
 
-After iterating over every frame of the trajectory, the mean value of the stored `z`
-coordinate are calculated. These mean values of `z` are the ones used to derive the
-surface.
+Once the grid is populated according to the coordinates of the atoms in the
+AtomGroup of reference, the associated `z` coordinate of each atom in the AtomGroup 
+is stored in an array assigned to each `[l, m]` index.
 
-With the defined surface, then values of mean (`H`) and Gaussian (`K`) curvature
-are calculated. This analysis returns a 2-dimensional array of `m x n` with the values of mean
-mean and Gaussian curvature. The length of this array is `m x n`.
+.. _derive-surface-curvature:
 
-More information on how to visualize the results of the MDAnalysis Membrane 
-Curvature toolkit can be found in the Visualization_ page .
+3. Derive surface and calculate curvature
+------------------------------------------
 
-.. |grid| image:: ../_static/gridmap.png
+Once the surface formed by the atoms of reference is derived, values of mean (`H`)
+and Gaussian (`K`) curvature are calculated according to their respective equations.
+
+For every frame of the trajectory, the surface derived from the `AtomGroup` is
+calculated and stored in :attr:`MembraneCurvature.results.z_surface`.
+Similarly, the calculation of mean and Gaussian curvature is performed in every
+frame and stored in :attr:`MembraneCurvature.results.mean_curvature` and
+:attr:`MembraneCurvature.results.gaussian_curvature`, respectively.
+
+|surf|
+
+.. _iterate:
+
+4. Average over frames
+-----------------------------------
+
+The attributes :attr:`MembraneCurvature.results.average_mean_curvature` and
+:attr:`MembraneCurvature.results.average_gaussian_curvature` contain the computed
+values of mean and Gaussian curvature averaged over the `n_frames` of the
+trajectory. 
+
+After performing the average over frames, the 
+:attr:`~MembraneCurvature.results.average_z_surface`
+:attr:`~MembraneCurvature.results.average_mean_curvature`, 
+:attr:`~MembraneCurvature.results.average_gaussian_curvature` arrays have shape 
+`(n_x_bins, n_y_bins)`.
+
+|avg_frames|
+
+
+.. |grid_map| image:: ../_static/gridmap.png
   :width: 400
   :alt: GridMap
 
-.. _Visualization:
+.. |diagram| image:: ../_static/DiagramAlgorithm.png
+  :width: 800
+  :alt: MembraneCurvature_diagram
+
+.. |atoms| image:: ../_static/AtomsReference.png
+  :width: 600
+  :alt: atoms_ref
+
+.. |grid| image:: ../_static/grid.png
+  :width: 600
+  :alt: Grid
+
+.. |surf| image:: ../_static/DeriveSurfCurv_.png
+  :width: 800
+  :alt: CurvDiaagram
+
+.. |avg_frames| image:: ../_static/AvgFrames.png
+  :width: 800
+  :alt: avgFrames
+
+.. _`MDAnalysis Universe`: https://docs.mdanalysis.org/2.0.0-dev0/documentation_pages/core/universe.html?highlight=universe
diff --git a/docs/source/pages/Usage.rst b/docs/source/pages/Usage.rst
@@ -1,23 +1,127 @@
 Usage
 =========================================================
 
-A simple plot using `imshow` can be obtained by::
+In this page, you can find examples of how to use MembraneCurvature to derive  curvature profiles in three types of 
+systems:
 
+:ref:`membrane-only`.
 
-        import matplotlib.pyplot as plt
+:ref:`membrane-protein`.
 
-        fig, ax = plt.subplots()
-        ax.imshow(mean_curvature, cmap='bwr', interpolation='gaussian', origin='lower')
-        ax.set_title('Mean Curvature')
-        plt.show()
+        :ref:`membrane-protein-pr`.
 
+        :ref:`membrane-protein-no-pr`.
 
-As an alternative, you can use contour plots using `contourf`::
+.. note::
+   All the examples included in this page show how to use MembraneCurvature
+   using data files from `MDAnalysisTests`_ and `MDAnalysisData`_. 
+   You can find instructions on how to install MDAnalysisData the `installation page`_.
 
+.. _membrane-only:
 
-        import matplotlib.pyplot as plt
+1. Membrane-only systems
+-----------------------------
 
-        fig, ax = plt.subplots()
-        ax.contourf(mean_curvature, cmap='bwr, origin='lower')
-        ax.set_title('Mean Curvature')
-        plt.show()
+In this example, we show a basic usage of MembraneCurvature in a system that
+comprises a lipid bilayer of DPPC:CHOL using the Martini force field. Since we
+have a bilayer, we select atoms of phoshpholipid head groups in the upper
+leaflet only using the :attr:`~select` parameter and apply coordinate wrapping.
+Once we run :attr:`~MembraneCurvature`, we can extract the values of mean and
+Gaussian curvature::
+
+        import MDAnalysis as mda
+        from membrane_curvature.base import MembraneCurvature
+        from MDAnalysis.tests.datafiles import Martini_membrane_gro
+
+        universe = mda.Universe(Martini_membrane_gro)
+
+        curvature_upper_leaflet = MembraneCurvature(universe, 
+                                                    select='resid 1-225 and name PO4', 
+                                                    n_x_bins=8, 
+                                                    n_y_bins=8, 
+                                                    wrap=True).run()
+
+
+        # extract mean curvature
+        mean_upper_leaflet = curvature_upper_leaflet.results.average_mean
+
+        # extract Gaussian
+        gaussian_upper_leaflet = curvature_upper_leaflet.results.average_gaussian
+
+You can find more complex examples in the tutorial notebooks.
+
+
+.. _membrane-protein:
+
+2.1 Membrane-protein systems
+------------------------------
+
+
+.. _membrane-protein-pr:
+
+2.1.1 Membrane-protein systems, protein with position restraints
+------------------------------------------------------------------
+
+In this example, we have a simulation box comprising a copy of the Yiip
+transporter, embedded in a lipid bilayer of POPE:POPG. Similar to the example
+for membrane-only, we select the atoms for the upper leaflet and apply
+coordinate wrapping. Then, we can calculate membrane curvature as::
+
+        import MDAnalysis as mda
+        from membrane_curvature.base import MembraneCurvature
+        from MDAnalysis.tests.datafiles import XTC_MEMPROT, GRO_MEMPROT
+
+        universe = mda.Universe(GRO_MEMB_PROT, XTC_MEMPROT)
+
+        curvature_upper_leaflet = MembraneCurvature(universe,
+                                               select='resid 297-517 and name P', 
+                                               n_x_bins=2, 
+                                               n_y_bins=2, 
+                                               wrap=True).run
+
+        avg_curvature_upper_leaflet = membrane_curvature.results.average_mean_curvature
+
+.. note::
+        When passing raw trajectories, in systems of :ref:`membrane-only` and 
+        :ref:`membrane-protein-pr` set :attr:`~wrap=True` to improve sampling. 
+
+Some points to keep in mind when calculating membrane curvature in :ref:`membrane-only`
+and :ref:`membrane-protein-pr` are addressed in this `blog post`_. 
+
+.. _membrane-protein-no-pr:
+
+2.1.2. Membrane-protein systems, protein with no position restraints
+---------------------------------------------------------------------
+
+For membrane-protein systems where the simulation setup has no position
+restraints on the protein, a trajectory preprocessing by the user is required.
+
+After you have preprocessed the trajectory, a typical usage of membrane curvature is::
+
+        import MDAnalysis as mda
+        from membrane_curvature.base import MembraneCurvature
+        from MDAnalysis.tests.datafiles import TPR_MEMB_PROT_FIT, GRO_MEMB_PROT_FIT
+
+        universe = mda.Universe(TPR_MEMB_PROT_FIT, GRO_MEMB_PROT_FIT)
+
+        membrane_curvature = MembraneCurvature(universe, 
+                                               select='name PO4', 
+                                               wrap=False,
+                                               n_x_bins=10,
+                                               n_y_bins=10)
+
+        membrane_curvature.run()
+
+        avg_mean_curvature  = membrane_curvature.results.mean_curvature
+
+
+More information on how to visualize the results of the MDAnalysis Membrane 
+Curvature tool can be found in the :ref:`visualization` page.
+
+.. _`blog post`: https://ojeda-e.github.io/blog/Considerations-curvature-MD-simulations-PartI/
+
+.. _`installation page`: https://www.mdanalysis.org/MDAnalysisData/install.html
+
+.. _`MDAnalysisData`: https://www.mdanalysis.org/MDAnalysisData/
+
+.. _`MDAnalysisTests`: https://github.com/MDAnalysis/mdanalysis/wiki/UnitTests