Release 0.11.0

.github/workflows/deploy_ghpages.yml

@@ -7,9 +7,6 @@ on:
       - master
       paths:
       - 'docsrc/**'
-   schedule:
-        # Run once a week on Sunday at 12:00 PM
-        - cron:  '0 12 * * 0'
 
 jobs:
 

CHANGELOG.md

@@ -1,36 +1,75 @@
 
+-------------------------------
+
+Version 0.11.0 - September 2020
+-----------------------------
+
+#### Overall changes
+
+* All Gauss models (``dd_gauss``,etc.) now use the standard deviation ``sigma`` instead of the FWHM as the width parameter for consistency with other method such as Rice distributions. (#19)
+
+* All hard-wired random seeds have been removed. 
+
+* A new method ``plot()`` has been added to the ``FitResult`` class returned by all fit functions. This will create a basic plot of the fit results. (#7)
+
+#### Specific changes
+* ``snlls``: 
+    - Renamed option ``penalty`` as ``reg`` and improved its interface (#13).
+    - The regularization parameter of the optimal solution is returned now (#20).
+
+* ``whitegaussnoise``: Added a ``seed`` option to select static noise realizations.
+
+* ``correctzerotime``: 
+    - Fixed bug when zero-time is at start/end of array (#24).
+    - Function no longer rescales the experimental data passed on to the function. 
+
+* ``fitsignal``:  
+    - The regularization parameter of the optimal solution is returned now (#20).
+    - Bug fixed when fitting dipolar evolution functions (no background and no experiment models) with a parametric distance distribution. 
+
+* ``fitmultimodel``: Start points are now spread over constrained parameter space grid instead of being randomble initiated (#22).
+
+* ``deerload``: 
+    - Now returns the time axis in microseconds instead of nanoseconds (#21).
+    - The bug appearing when loading certain BES3T files has been fixed (#14).
+
+* ``fitregmodel``: Now returns the fitted dipolar signal in the ``FitResult`` output
+
+* ``correctscale``: The parameter fit ranges have been adjusted.
+
+
 -------------------------------
 
 Version 0.10.0 - August 2020
 -----------------------------
 
 As of this version, DeerLab is written in Python in contrast to older versions based on MATLAB.
 
-Deprecated functions
-    The following functions have been deprecated due to limited usability or due to functionality overlap with other DeerLab functions: ``aptkernel``, ``backgroundstart``, ``fitbackground``, ``paramodel``, and ``time2freq``. 
+#### Deprecated functions
+The following functions have been deprecated due to limited usability or due to functionality overlap with other DeerLab functions: ``aptkernel``, ``backgroundstart``, ``fitbackground``, ``paramodel``, and ``time2freq``. 
 
-Overall changes
-    * All fit functions now return a single ``FitResult`` output which will contain all results. 
+#### Overall changes
+* All fit functions now return a single ``FitResult`` output which will contain all results. 
 
-    * All functions are now compatible with non-uniformly increasing distance axes. 
+* All functions are now compatible with non-uniformly increasing distance axes. 
 
-    * All fit functions are completely agnostic with respect of the abolute values of the signal amplitude. This is automatically fitted by all function and return as part of the results.
+* All fit functions are completely agnostic with respect of the abolute values of the signal amplitude. This is automatically fitted by all function and return as part of the results.
 
-    * Uncertainty quantification for all fit functions is returned as a ``UncertQuant`` object from which confidence intervals, parameter distributions, etc. can be generated generalizing the uncertainty interface for all DeerLab. Uncertainty can now be propagated to arbitrary functions.
+* Uncertainty quantification for all fit functions is returned as a ``UncertQuant`` object from which confidence intervals, parameter distributions, etc. can be generated generalizing the uncertainty interface for all DeerLab. Uncertainty can now be propagated to arbitrary functions.
 
-Specific changes
-    * ``fitparamodel``: the functionality has been streamlined. Function now fits arbitrary parametric models using non-linear leas-squares without consideration of whether it is a time-domain or distance-domain model. The models no longer need to take two inputs (axis+parameters) and now only tk the parameters as input. 
+#### Specific changes
+* ``fitparamodel``: the functionality has been streamlined. Function now fits arbitrary parametric models using non-linear leas-squares without consideration of whether it is a time-domain or distance-domain model. The models no longer need to take two inputs (axis+parameters) and now only tk the parameters as input. 
 
-    * ``fitregmodel``: goodness-of-fit estimators are now computed using the proper estimation the degrees of freedom.
+* ``fitregmodel``: goodness-of-fit estimators are now computed using the proper estimation the degrees of freedom.
 
-    * ``fitmultimodel``: added internal measures to avoid situations where one or several components are suppressed by fitting zero-amplitudes making the method more stable. 
+* ``fitmultimodel``: added internal measures to avoid situations where one or several components are suppressed by fitting zero-amplitudes making the method more stable. 
 
-    * ``uqst``: the uncertainty distributions of the parameters are now returned as properly normalized probability density functions.
+* ``uqst``: the uncertainty distributions of the parameters are now returned as properly normalized probability density functions.
 
-    * ``fftspec``: frequency axis construction has been corrected.
+* ``fftspec``: frequency axis construction has been corrected.
 
-    * ``regoperator``: now calculates the numerically exact finite-difference matrix using Fornberg's method.
+* ``regoperator``: now calculates the numerically exact finite-difference matrix using Fornberg's method.
 
-    * ``correctphase``: now can handle 2D-datasets.
+* ``correctphase``: now can handle 2D-datasets.
 
 -------------------------------

VERSION

@@ -1 +1 @@
-v0.10.0
+v0.11.0-dev

deerlab/bg_models.py

@@ -1,3 +1,8 @@
+# bg_models.py - Background parametric models
+# ---------------------------------------------------------------------------
+# This file is a part of DeerLab. License is MIT (see LICENSE.md). 
+# Copyright(c) 2019-2020: Luis Fabregas, Stefan Stoll and other contributors.
+
 import numpy as np
 import math as m
 import scipy as scp
@@ -46,7 +51,7 @@ def bg_exp(*args):
      -------------------------------------------------
       Parameter    Units     Lower    Upper    Start
      -------------------------------------------------
-      Decay Rate    us-1       0       200      0.35 
+      Decay Rate    μs⁻¹       0       200      0.35 
      -------------------------------------------------
 
 
@@ -76,7 +81,7 @@ def bg_exp(*args):
     if not args:
         info = dict(
             Parameters = ['Decay Rate'],
-            Units = ['us-1'],
+            Units = ['μs⁻¹'],
             Start = np.asarray([0.35]),
             Lower = np.asarray([0]),
             Upper = np.asarray([200])
@@ -115,7 +120,7 @@ def bg_hom3d(*args):
      ----------------------------------------------------------------------
       Parameter                        Units     Lower    Upper    Start
      ----------------------------------------------------------------------
-      Concentration of pumped spins     uM        0.01    5000      50 
+      Concentration of pumped spins     μM        0.01    5000      50 
      ----------------------------------------------------------------------
 
     Parameters
@@ -144,7 +149,7 @@ def bg_hom3d(*args):
     if not args:
         info = dict(
             Parameters = ['Concentration of pumped spins'],
-            Units = ['uM'],
+            Units = ['μM'],
             Start = np.asarray([50]),
             Lower = np.asarray([0.01]),
             Upper = np.asarray([5000])
@@ -193,7 +198,7 @@ def bg_hom3dex(*args):
      -----------------------------------------------------------------------------
       Parameter                                Units     Lower    Upper    Start
      -----------------------------------------------------------------------------
-      Fractal Concentration of pumped spins  umol/dm^d    0.01    5000      50 
+      Fractal Concentration of pumped spins   μmol/dmᵈ    0.01    5000      50 
       Exclusion distance                        nm        0.10     20       1 
      -----------------------------------------------------------------------------
 
@@ -223,7 +228,7 @@ def bg_hom3dex(*args):
     if not args:
         info = dict(
             Parameters = ['Fractal Concentration of pumped spins','Fractal dimensionality'],
-            Units = ['umol/dm^d',''],
+            Units = ['μmol/dmᵈ',''],
             Start = np.asarray([50,   1]),
             Lower = np.asarray([0.01, 0.01]),
             Upper = np.asarray([5000, 20])
@@ -292,7 +297,7 @@ def bg_homfractal(*args):
      -----------------------------------------------------------------------------
       Parameter                                Units     Lower    Upper    Start
      -----------------------------------------------------------------------------
-      Fractal Concentration of pumped spins  umol/dm^d    0.01    5000      50 
+      Fractal Concentration of pumped spins   μmol/dmᵈ    0.01    5000      50 
       Fractal dimensionality                               0        6       3
      -----------------------------------------------------------------------------
 
@@ -322,7 +327,7 @@ def bg_homfractal(*args):
     if not args:
         info = dict(
             Parameters = ['Fractal Concentration of pumped spins','Fractal dimensionality'],
-            Units = ['umol/dm^d',''],
+            Units = ['μmol/dmᵈ',''],
             Start = np.asarray([50,   3]),
             Lower = np.asarray([0.01, 0+np.finfo(float).eps]),
             Upper = np.asarray([5000, 6-np.finfo(float).eps])
@@ -383,7 +388,7 @@ def bg_strexp(*args):
      ----------------------------------------------------
       Parameter        Units     Lower    Upper   Start
      ----------------------------------------------------
-      Decay Rate       us-1       0       200      0.25 
+      Decay Rate       μs⁻¹       0       200      0.25 
       Stretch factor              0        6        1
      ----------------------------------------------------
 
@@ -413,7 +418,7 @@ def bg_strexp(*args):
     if not args:
         info = dict(
             Parameters = ['Decay Rate','Stretch factor'],
-            Units = ['us-1',''],
+            Units = ['μs⁻¹',''],
             Start = np.asarray([0.25, 1]),
             Lower = np.asarray([0,    0]),
             Upper = np.asarray([200,  6])
@@ -422,7 +427,7 @@ def bg_strexp(*args):
     t,param,lam = _parsargs(args,npar=2) 
 
     # Unpack model paramters
-    kappa = param[0]         # decay rate, us-1
+    kappa = param[0]         # decay rate, µs^-1
     d = param[1]            # fractal dimension    
     B = np.exp(-lam*kappa*abs(t)**d)
 
@@ -452,9 +457,9 @@ def bg_prodstrexp(*args):
      -----------------------------------------------------------------
       Parameter                      Units   Lower    Upper    Start
      -----------------------------------------------------------------
-      Decay Rate of 1st component    us-1      0       200      0.25 
+      Decay Rate of 1st component    μs⁻¹      0       200      0.25 
       Stretch factor 1st component             0        6        1
-      Decay Rate of 2nd component    us-1      0       200      0.25 
+      Decay Rate of 2nd component    μs⁻¹      0       200      0.25 
       Stretch factor 2nd component             0        6        1
      -----------------------------------------------------------------
 
@@ -484,7 +489,7 @@ def bg_prodstrexp(*args):
     if not args:
         info = dict(
             Parameters = ['Decay Rate of 1st component','Stretch factor of 1st component','Decay Rate of 2nd component','Stretch factor of 2nd component'],
-            Units = ['us-1','','us-1',''],
+            Units = ['µs^-1','','µs^-1',''],
             Start = np.asarray([0.25, 1, 0.25, 1]),
             Lower = np.asarray([ 0,   0,  0,   0]),
             Upper = np.asarray([200,  6, 200,  6])
@@ -527,10 +532,10 @@ def bg_sumstrexp(*args):
      -----------------------------------------------------------------
       Parameter                      Units   Lower    Upper    Start
      -----------------------------------------------------------------
-      Decay Rate of 1st component    us-1      0       200      0.25 
+      Decay Rate of 1st component    μs⁻¹      0       200      0.25 
       Stretch factor 1st component             0        6        1
       Amplitude of 1st component               0        1       0.50
-      Decay Rate of 2nd component    us-1      0       200      0.25 
+      Decay Rate of 2nd component    μs⁻¹      0       200      0.25 
       Stretch factor 2nd component             0        6        1
      -----------------------------------------------------------------
 
@@ -560,7 +565,7 @@ def bg_sumstrexp(*args):
     if not args:
         info = dict(
             Parameters = ['Decay Rate of 1st component','Stretch factor of 1st component','Amplitude of 1st component','Decay Rate of 2nd component','Stretch factor of 2nd component'],
-            Units = ['us-1','','','us-1',''],
+            Units = ['μs⁻¹','','','μs⁻¹',''],
             Start = np.asarray([0.25, 1, 0.5, 0.25, 1]),
             Lower = np.asarray([ 0,   0,  0,   0,   0]),
             Upper = np.asarray([200,  6,  1,  200,  6])
@@ -606,7 +611,7 @@ def bg_poly1(*args):
       Parameter              Units    Lower    Upper    Start
      ----------------------------------------------------------
       Intercept                         0       200       1  
-      1st-order coefficient  us^-1    -200      200      -1  
+      1st-order coefficient  μs⁻¹    -200      200      -1  
      ----------------------------------------------------------
 
     Parameters
@@ -635,7 +640,7 @@ def bg_poly1(*args):
     if not args:
         info = dict(
             Parameters = ['Intercept','1st-order coefficient'],
-            Units = ['','us-1'],
+            Units = ['','μs⁻¹'],
             Start = np.asarray([ 1,   -1 ]),
             Lower = np.asarray([ 0,  -200]),
             Upper = np.asarray([200,  200])
@@ -678,8 +683,8 @@ def bg_poly2(*args):
       Parameter              Units    Lower    Upper    Start
      ----------------------------------------------------------
       Intercept                         0       200       1  
-      1st-order coefficient  us^-1    -200      200      -1  
-      2nd-order coefficient  us^-2    -200      200      -1 
+      1st-order coefficient  μs⁻¹    -200      200      -1  
+      2nd-order coefficient  μs⁻²    -200      200      -1 
      ----------------------------------------------------------
 
     Parameters
@@ -708,7 +713,7 @@ def bg_poly2(*args):
     if not args:
         info = dict(
             Parameters = ['Intercept','1st-order coefficient','2nd-order coefficient'],
-            Units = ['','us-1','us-2'],
+            Units = ['','μs⁻¹','μs⁻²'],
             Start = np.asarray([ 1,   -1 , -1]),
             Lower = np.asarray([ 0,  -200, -200]),
             Upper = np.asarray([200,  200,  200])
@@ -747,9 +752,9 @@ def bg_poly3(*args):
       Parameter              Units    Lower    Upper    Start
      ----------------------------------------------------------
       Intercept                         0       200       1  
-      1st-order coefficient  us^-1    -200      200      -1  
-      2nd-order coefficient  us^-2    -200      200      -1 
-      3rd-order coefficient  us^-3    -200      200      -1
+      1st-order coefficient   μs⁻¹    -200      200      -1  
+      2nd-order coefficient   μs⁻²    -200      200      -1 
+      3rd-order coefficient   μs⁻³    -200      200      -1
      ----------------------------------------------------------
 
     Parameters
@@ -778,7 +783,7 @@ def bg_poly3(*args):
     if not args:
         info = dict(
             Parameters = ['Intercept','1st-order coefficient','2nd-order coefficient','3rd-order coefficient'],
-            Units = ['','us-1','us-2','us-3'],
+            Units = ['','μs⁻¹','μs⁻²','μs⁻³'],
             Start = np.asarray([ 1,  -1  , -1,   -1  ]),
             Lower = np.asarray([ 0,  -200, -200, -200]),
             Upper = np.asarray([200,  200,  200,  200])

deerlab/bootan.py

@@ -15,7 +15,7 @@ def bootan(fcn,Vexp,Vfit, samples=1000, resampling='gaussian', verbose = False):
     fcn : callable
         Function to be analyzed. Must be a callable function accepting a signal array as input and returning a tuple with all variables to be analyzed.
         All variables must be numerical arrays (no strings or booleans) and must preserve shape between calls.
-    V : array_like or list of array_like
+    Vexp : array_like or list of array_like
         Experimental dataset(s).
     Vfit : array or list of array_like
         Fit of the dataset(s).
@@ -97,9 +97,6 @@ def myfcn(V):
     Vresample = [0]*nSignals
     for iSample in range(nSamples-1):
 
-        # Change the random seed each iteration, but keeping reproducibility between runs
-        np.random.seed(iSample)
-
         # Inform of progress if requested
         if verbose:
             print('Bootstrapping: #{}/#{} samples finished'.format(iSample+1,nSamples), end='\r', flush=True)
@@ -110,11 +107,11 @@ def myfcn(V):
             if iSample>0:
 
                 #Determine requested re-sampling method
-                if resampling is 'gaussian':
+                if resampling == 'gaussian':
                     # Resample from a Gaussian distribution with variance estimated from the residuals
                     Vresample[i] = Vfit[i] + np.random.normal(0, sigma[i], len(Vfit[i]))
 
-                elif resampling is 'residual':
+                elif resampling == 'residual':
                     # Resample from the residual directly
                     Vresample[i] =  Vfit[i] + residuals[i][np.random.permutation(len(Vfit[i]))]
                 else: