Documentation update for 0.12.0 (#45)

* docs: major edits, included license, and beginners guide section * fitsignal: experiment parameter are now properly printed when verbose (bug fix) * docs: rewritten uncertainty section * docs: minor edits and spelling corrections * docs: rewriten Basics section, edits on other pages * docs: search engine highlighting no longer introduces spaces (bug fix) * docs: minor edits * docs: adapted phenomenological background model equations to #43 * docs: minor edits in frontpage * docs: fixed example in fitparamodel docstring (#47)
JeschkeLab · Oct 23, 2020 · 8763325 · 8763325
1 parent 5ac739c
commit 8763325
Show file tree

Hide file tree

Showing 24 changed files with 684 additions and 244 deletions.
diff --git a/README.md b/README.md
@@ -34,7 +34,7 @@ More details on the installation of DeerLab can be found [here](https://jeschkel
 
 A paper about DeerLab is currently submitted for publication. When you use DeerLab in your work, for now, please cite the preprint
 
-> Fábregas Ibáñez, L., Jeschke, G., and Stoll, S.: DeerLab: A comprehensive software package for analyzing dipolar EPR spectroscopy data, Magn. Reson. Discuss., https://doi.org/10.5194/mr-2020-13, 2020
+> Fábregas Ibáñez, L., Jeschke, G., and Stoll, S.: a comprehensive software package for analyzing dipolar electron paramagnetic resonance spectroscopy data, Magn. Reson., 1, 209–224, 2020, doi.org/10.5194/mr-1-209-2020
 
 Please check back frequently for updated publication information.
 

diff --git a/deerlab/fitparamodel.py b/deerlab/fitparamodel.py
@@ -87,7 +87,7 @@ def Vmodel(par):
             rmean,fwhm,lam,conc = par
             B = dl.bg_hom3d(t,conc)
             P = dl.dd_gauss(r,[rmean,fwhm])
-            V = (1-lam + lam*K0@P)*B[:,np,newaxis]
+            V = (1-lam + lam*K0@P)*B
             return V
         
         # par: rmean fwhm lam conc
@@ -106,8 +106,8 @@ def Vmodel(par):
             rmean,fwhm,lam1,lam,2conc = par
             B = dl.bg_hom3d(t,conc)
             P = dl.dd_gauss(r,[rmean,fwhm])
-            V1 = (1-lam1 + lam1*K1@P)*B[:,np,newaxis]
-            V2 = (1-lam2 + lam2*K2@P)*B[:,np,newaxis]
+            V1 = (1-lam1 + lam1*K1@P)*B
+            V2 = (1-lam2 + lam2*K2@P)*B
             return V
         
         # par: rmean fwhm lam1 lam2 conc

diff --git a/deerlab/fitsignal.py b/deerlab/fitsignal.py
@@ -137,7 +137,7 @@ def fitsignal(Vexp, t, r, dd_model='P', bg_model=bg_hom3d, ex_model=ex_4pdeer,
         Array of weighting coefficients for the individual signals in global fitting,
         the default is all weighted equally.
         If not specified all datasets are weighted equally.
-    regParam (str or scalar):
+    regparam (str or scalar):
         Method for the automatic selection of the optimal regularization parameter:
 
         * ``'lr'`` - L-curve minimum-radius method (LR)
@@ -309,14 +309,14 @@ def multiPathwayModel(par):
 
             # Get pathway information
             if includeExperiment[iSignal]:
-                pathinfo = ex_model[iSignal](ex_par)
+                pathways = ex_model[iSignal](ex_par)
             else:
-                pathinfo = 1
+                pathways = 1
 
             # Compute the multipathway-background
-            B_ = dl.dipolarbackground(t[iSignal],pathinfo,Bfcn)
+            B_ = dl.dipolarbackground(t[iSignal],pathways,Bfcn)
             # Compute the multipathway-kernel
-            K_ = dl.dipolarkernel(t[iSignal],r,pathinfo)
+            K_ = dl.dipolarkernel(t[iSignal],r,pathways)
             Ks.append(K_*B_[:,np.newaxis])
             Bs.append(B_)
 
@@ -613,9 +613,9 @@ def _display_results():
                     ci = paruq['ex'][i].ci(95)
                 else:
                     ci = np.full((len(parfit['ex'][i]),2),np.nan)
-                    for j in range(len(parfit['ex'][i])):
-                        c = parfit['ex'][i][j]
-                        print(pstr.format('exparam',j,c,ci[j,0],ci[j,1],info['Parameters'][j],info['Units'][j]))
+                for j in range(len(parfit['ex'][i])):
+                    c = parfit['ex'][i][j]
+                    print(pstr.format('exparam',j,c,ci[j,0],ci[j,1],info['Parameters'][j],info['Units'][j]))
         print('----------------------------------------------------------------------------')
 
 

diff --git a/docsrc/source/_static/theme_override.css b/docsrc/source/_static/theme_override.css
@@ -3288,7 +3288,7 @@ footer span.commit code,footer span.commit .rst-content tt,.rst-content footer s
     background: #F1C40F;
     display: inline-block;
     font-weight: bold;
-    padding: 0 6px}
+    padding: 0 0px}
 .rst-content .footnote-reference,.rst-content .citation-reference {
     vertical-align: baseline;
     position: relative;

diff --git a/docsrc/source/basics.rst b/docsrc/source/basics.rst
diff --git a/docsrc/source/beginners_guide.rst b/docsrc/source/beginners_guide.rst
diff --git a/docsrc/source/changelog.rst b/docsrc/source/changelog.rst
@@ -1,6 +1,7 @@
+.. _changelog:
 
-----------
-Changelog
-----------
+--------------
+Release Notes
+--------------
 
 .. mdinclude:: ../../CHANGELOG.md
diff --git a/docsrc/source/examples.rst b/docsrc/source/examples.rst
@@ -1 +1,3 @@
+.. _examples:
+
 .. include:: ./auto_examples/index.rst
diff --git a/docsrc/source/firstscript.rst b/docsrc/source/firstscript.rst
@@ -1,28 +1,47 @@
-A first script
+Quickstart tutorial
 ============================================================
 
-Here is a first script that shows how DeerLab works. It simulates a noisy DEER data trace and then fits it.
+This tutorial is intended as a overview of the fundamentals of DeerLab. If you are not familiar with DeerLab or 
+dipolar EPR spectroscopy data analysis, then the :ref:`Beginner's Guide <beginners_guide>` might give you a better
+insight on the basics for using DeerLab.  
 
-We start by importing DeerLab
-
-.. code-block:: python
+This tutorial will assume that DeerLab is already installed on your computer. DeerLab always needs to be imported prior
+to calling any of its functions as well as any other packages ::
 
    import deerlab as dl              # we always use 'dl' as the local name for DeerLab
+   import numpy as np                # NumPy: vectors, matrices, linear algebra
+   import matplotlib.pyplot as plt   # MatPlotLib: plotting
 
-and other needed packages:
+Loading experimental data
+--------------------------
 
-.. code-block:: python
 
-   import numpy as np                # NumPy: vectors, matrices, linear algebra
-   import matplotlib.pyplot as plt   # MatPlotLib: plotting
 
-Then, we generate a distance distribution consisting of a single Gaussian:
+
+Simulating dipolar signals
+---------------------------
+
+DeerLab is provides the tools for simulating dipolar signals originating from different experiments. Note that these simulations 
+are not based on spin dynamics simulations but rather on theoretical analytical treatments of such problems. 
+
+Simulations in DeerLab can be easily achieved via the Fredholm integral which for a general dipolar signal reads
+
+.. math:: V(t) = \int K(t,r)P(r) \mathrm{d}r
+
+which in matrix form reads
+
+.. math:: \boldsymbol{V} = \boldsymbol{K}\boldsymbol{P} 
+
+To simulate a dipolar signal you need first to define a distance distribution. This distribution can be the result of a fit, come 
+from molecular dynamics simulations, etc. or you can assume a certain shape for the distribution and use one of the parametric models 
+available in DeerLab. For example, to simulate a Gaussian distance distribution use the ``dd_gauss`` model function
 
 .. code-block:: python
 
-   N = 201                            # number of points
-   r = np.linspace(1.5,7,N)           # distance range, in nanometers
-   P = dl.dd_gauss(r,[3.5, 0.15])     # single-Gaussian distance distribution
+   r = np.linspace(1.5,7,200)         # distance range, in nm
+   rmean = 3.5 # nm
+   sigma = 0.3 # nm
+   P = dl.dd_gauss(r,[rmean, sigma])  # single-Gaussian distance distribution
 
 Next, we calculate the background decay function due to a homogeneus 3D distribution of spins:
 

diff --git a/docsrc/source/functions.rst b/docsrc/source/functions.rst
@@ -4,9 +4,7 @@
 Functions
 ---------------------
 
-This is the official documentation for the DeerLab toolbox functions. The following list contains the names of the different function and a brief description of their functionality. The parametric model functions are listed in separate sections.
-
-
+The following list contains the names of the different function and a brief description of their functionality. The parametric model functions are listed in separate sections.
 
 Modeling
 =========================================

diff --git a/docsrc/source/images/beginners_guide1.png b/docsrc/source/images/beginners_guide1.png
diff --git a/docsrc/source/index.rst b/docsrc/source/index.rst
@@ -1,45 +1,74 @@
-DeerLab |version| Documentation
+DeerLab |version|
 =====================================================
 
 .. warning:: DeerLab is currently in the pre-release stage (version numbers 0.x.x) and under active development. Major changes are likely before the first stable version (1.0.0) is released.
 
 DeerLab is a free software package for the analysis of dipolar EPR (electron paramagnetic resonance) spectroscopy data based on the Python programming language. Dipolar EPR spectroscopy techniques include DEER (double electron-electron resonance), RIDME (relaxation-induced dipolar modulation enhancement), and others.
 
-DeerLab consists of a collection of functions that perform modelling, processing or fitting tasks. They can be combined in scripts to build custom data analysis workflows. To model distance distributions, DeerLab supports two types of model classes and associated workflows: parameter-free models (as used in Tikhonov regularization) as well as a series of parameterized models (mutli-Gaussians etc). It also provides a selection of background and experiment models. 
+DeerLab consists of a collection of functions that perform modelling, processing or fitting tasks. They can be combined in scripts to build custom data analysis workflows. To model distance distributions, DeerLab supports two types of model classes and associated workflows: parameter-free models (as used in Tikhonov regularization) as well as a series of parameterized models (multi-Gaussians etc). It also provides a selection of background and experiment models. 
 
-When you use DeerLab in your work, please cite the following publication:
+-------
 
+Documentation
+    To get started read the :ref:`beginners_guide` tutorial. 
 
-.. raw:: html 
+    Looking for a specific topic? Look at the :ref:`selection of examples <examples>` or at :ref:`reference <functions>` for specific DeerLab functions. 
 
-    <div style="height:100px; width:100%; display:flex; flex-wrap:wrap; align-items:center;">
-        <div style="height:100%;">
-            <img src='https://www.magnetic-resonance-ampere.net/graphic_journal_cover_normal.png', style="margin-top:1%; margin-bottom:1%;height:96%;">
+-------
+
+What's new?
+    Check the :ref:`changelog` for the changes introduced in the latest releases.
+
+-------
+
+Citing DeerLab
+    When you use DeerLab in your work, please cite the following publication:
+
+    .. raw:: html 
+
+        <div style="height:2%px; width:100%; display:flex; flex-wrap:wrap; align-items:center;">
+            <div style="width:7%;">
+                <img src='https://www.magnetic-resonance-ampere.net/graphic_journal_cover_normal.png', style="margin-top:1%; margin-bottom:1%; width=50% !important ; ">
+            </div>
+            <div style="margin-left:1%; font-size:14px">
+                <h3 style="font-size:110%">  DeerLab: a comprehensive software package for analyzing dipolar electron paramagnetic resonance spectroscopy data </h3> 
+                Luis Fábregas Ibáñez, Gunnar Jeschke, Stefan Stoll <br>
+                Magn. Reson., 1, 209–224, 2020 <br>
+                <a href="https://doi.org/10.5194/mr-1-209-2020"> doi.org/10.5194/mr-1-209-2020</a>
+            </div>
         </div>
-        <div style="margin-left:1%; font-size:14px">
-            <h3 style="font-size:110%">  DeerLab: a comprehensive software package for analyzing dipolar electron paramagnetic resonance spectroscopy data </h3> 
-            Luis Fábregas Ibáñez, Gunnar Jeschke, Stefan Stoll <br>
-            Magn. Reson., 1, 209–224, 2020 <br>
-            <a> doi.org/10.5194/mr-1-209-2020</a>
+
+
+-------
+
+Contributing
+    .. raw:: html 
+
+        <div style="height:3%; width:100%; display:flex; flex-wrap:wrap; align-items:center;">
+            <div style="width:5%;">
+                <img src='https://upload.wikimedia.org/wikipedia/commons/thumb/9/91/Octicons-mark-github.svg/1200px-Octicons-mark-github.svg.png', style="margin-top:1%; margin-bottom:1%;height:60%;">
+            </div>
+            <div style="margin-left:1%; font-size:14px">
+                DeerLab is hosted on <a href="https://github.com/JeschkeLab/DeerLab"> Github </a>:
+                <ul style="font-size:14px">
+                <li> Bugs and feature requests can be reported on the <a href="https://github.com/JeschkeLab/DeerLab/issues"> issue tracker </a>.
+                <li> Any contributions in the form of <a href="https://github.com/JeschkeLab/DeerLab/pulls"> pull requests</a>  are very welcome.
+                </ul>
+            </div>
         </div>
-    </div>
 
-.. toctree::
-    :hidden:
-    :caption: Installation
-    :maxdepth: 0
 
-    ./installation
+.. include:: changelog.rst
+    :start-after: Version
 
 .. toctree::
     :hidden:
     :caption: User Guide
     :maxdepth: 0
 
-    ./firstscript
+    ./installation
     ./basics
-    ./preprocess
-    ./fitting
+    ./beginners_guide
     ./uncertainty
     ./examples
 
@@ -57,6 +86,7 @@ When you use DeerLab in your work, please cite the following publication:
     :caption: Others
     :maxdepth: 1
 
+    ./license
     ./funding
     ./changelog
 

diff --git a/docsrc/source/installation.rst b/docsrc/source/installation.rst
@@ -1,4 +1,6 @@
-Installation instructions
+.. _installation:
+
+Installation
 =========================
 
 Requirements
@@ -11,11 +13,11 @@ DeerLab requires one of the following versions of the Python interpreter
 
 which can be downloaded from the `official Python distribution <https://www.python.org/>`_.
 
-For Windows systems it is imporant to ensure that the **Install launcher for all users (recommended)** and the **Add Python 3.x to PATH** checkboxes at the bottom are checked. To test if python has been succesfully installed, open a terminal window and run the command::
+For Windows systems it is important to ensure that the **Install launcher for all users (recommended)** and the **Add Python 3.x to PATH** checkboxes at the bottom are checked. To test if python has been successfully installed, open a terminal window and run the command::
 
 	python
 
-wihch should open the Python interface as well as display the installed Python version. To exit use the ``exit()`` command.
+which should open the Python interface as well as display the installed Python version. To exit use the ``exit()`` command.
 
 Installing pre-built DeerLab
 -----------------------------

diff --git a/docsrc/source/license.rst b/docsrc/source/license.rst
@@ -0,0 +1,35 @@
+License
+-------
+
+.. raw:: html 
+
+    <div style="height:80px; width:100%; margin-bottom:1%;">
+        <div style="width=40%; margin-right:8%; font-size:16px">
+            <h3 style="font-size:110%">  MIT License </h3> 
+        </div>
+        <div style="height:70%; width=30%">
+            <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/0/0c/MIT_logo.svg/1200px-MIT_logo.svg.png", style="margin-top:0%; margin-bottom:5%;height:96%;">
+        </div>
+    <br>
+    </div>    
+
+
+Copyright (c) 2019-2020 Luis Fabregas, Stefan Stoll, and others
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docsrc/source/models/bg_exp.rst b/docsrc/source/models/bg_exp.rst
@@ -12,7 +12,7 @@ Model
 
 .. math::
 
-   B(t) = \exp\left(-\lambda\kappa \vert t \vert\right)
+   B(t) = \exp\left(-\kappa \vert t \vert\right)
 
 ============== =============== ============= ============= ============= ================================
  Variable         Symbol        Start Value   Lower bound   Upper bound      Description

diff --git a/docsrc/source/models/bg_hom3dex.rst b/docsrc/source/models/bg_hom3dex.rst
@@ -17,13 +17,11 @@ This implements a hard-shell excluded-volume model, with pumped spin concentrati
 
 The expression for this model is
 
-.. math::
-   B(t) = \mathrm{exp}\left(-\frac{8\pi^2}{9\sqrt{3}}\alpha(R) \lambda c D |t|\right)`
+.. math:: B(t) = \mathrm{exp}\left(-\frac{8\pi^2}{9\sqrt{3}}\alpha(R) \lambda c D |t|\right)`
 
 where :math:`c` is the spin concentration (entered in spins/m\ :sup:`3` into this expression) and :math:`D` is the dipolar constant
 
-.. math::
-   D = \frac{\mu_0}{4\pi}\frac{(g_\mathrm{e}\mu_\mathrm{B})^2}{\hbar}
+.. math:: D = \frac{\mu_0}{4\pi}\frac{(g_\mathrm{e}\mu_\mathrm{B})^2}{\hbar}
 
 The function :math:`\alpha(R)` of the exclusion distance :math:`R` captures the excluded-volume effect. It is a smooth function, but doesn't have an analytical representation. For details, see `Kattnig et al, J.Phys.Chem.B 2013, 117, 16542 <https://pubs.acs.org/doi/abs/10.1021/jp408338q>`_.
 

diff --git a/docsrc/source/models/bg_poly1.rst b/docsrc/source/models/bg_poly1.rst
@@ -10,7 +10,7 @@
 Model
 =========================================
 
-:math:`B(t) = p_0 + p_1(\lambda t)`
+:math:`B(t) = p_0 + p_1 t`
 
 ============== =============== ============= ============= ============= ====================================
  Variable         Symbol        Start Value   Lower bound   Upper bound      Description

diff --git a/docsrc/source/models/bg_poly2.rst b/docsrc/source/models/bg_poly2.rst
@@ -11,7 +11,7 @@
 Model
 =========================================
 
-:math:`B(t) = p_0 + p_1(\lambda t) + p_2(\lambda t)^2`
+:math:`B(t) = p_0 + p_1 t + p_2t^2`
 
 ============== =============== ============= ============= ============= ===================================
  Variable         Symbol        Start Value   Lower bound   Upper bound      Description

diff --git a/docsrc/source/models/bg_poly3.rst b/docsrc/source/models/bg_poly3.rst
@@ -11,7 +11,7 @@
 Model
 =========================================
 
-:math:`B(t) = p_0 + p_1(\lambda t) + p_2(\lambda t)^2 + p_3(\lambda t)^3`
+:math:`B(t) = p_0 + p_1t + p_2t^2 + p_3t^3`
 
 ============== =============== ============= ============= ============= ===================================
  Variable         Symbol        Start Value   Lower bound   Upper bound      Description

diff --git a/docsrc/source/models/bg_prodstrexp.rst b/docsrc/source/models/bg_prodstrexp.rst
@@ -11,7 +11,7 @@
 Model
 =========================================
 
-:math:`B(t) = \exp\left(-\lambda\kappa_1 \vert t \vert^{d_1}\right) \exp\left(-\lambda\kappa_2 \vert t\vert^{d_2}\right)`
+:math:`B(t) = \exp\left(-\kappa_1 \vert t \vert^{d_1}\right) \exp\left(-\kappa_2 \vert t\vert^{d_2}\right)`
 
 ============== ================= ============= ============= ============= =================================
  Variable         Symbol          Start Value   Lower bound   Upper bound      Description

diff --git a/docsrc/source/models/bg_strexp.rst b/docsrc/source/models/bg_strexp.rst
@@ -13,7 +13,7 @@ Model
 
 .. math::
 
-    B(t) = \exp\left(-\lambda \kappa \vert t\vert^{d}\right)
+    B(t) = \exp\left(-\kappa \vert t\vert^{d}\right)
 
 ============== ================= ============= ============= ============= =================================
  Variable         Symbol          Start Value   Lower bound   Upper bound      Description