Minimize uvars test (#913)

* add test for MinimizerResult.uvars after successful fit

* update fitting doc to add uvars (and other items) into table of MinimizerResult attributes

doc/fitting.rst

@@ -330,6 +330,18 @@ Goodness-of-Fit Statistics
 +----------------------+----------------------------------------------------------------------------+
 |    nfree             | degrees of freedom in fit: :math:`N - N_{\rm varys}`                       |
 +----------------------+----------------------------------------------------------------------------+
+|    aborted           | boolean of whether the fit has been aborted.                               |
++----------------------+----------------------------------------------------------------------------+
+|    success           | boolean for a minimal test of whether the fit finished successfully        |
++----------------------+----------------------------------------------------------------------------+
+|    errorbars         | boolean of whether error bars and unccertainty were estimated              |
++----------------------+----------------------------------------------------------------------------+
+|    ier               | integer flag describing message from ``leastsq``.                          |
++----------------------+----------------------------------------------------------------------------+
+|    message           | simple message from ``leastsq``                                            |
++----------------------+----------------------------------------------------------------------------+
+|    method            | name of fitting methods                                                    |
++----------------------+----------------------------------------------------------------------------+
 |    residual          | residual array, returned by the objective function: :math:`\{\rm Resid_i\}`|
 +----------------------+----------------------------------------------------------------------------+
 |    chisqr            | chi-square: :math:`\chi^2 = \sum_i^N [{\rm Resid}_i]^2`                    |
@@ -340,12 +352,18 @@ Goodness-of-Fit Statistics
 +----------------------+----------------------------------------------------------------------------+
 |    bic               | Bayesian Information Criterion statistic (see below)                       |
 +----------------------+----------------------------------------------------------------------------+
+|    params            | best-fit parameters after fit, with uncertainties is available             |
++----------------------+----------------------------------------------------------------------------+
 |    var_names         | ordered list of variable parameter names used for init_vals and covar      |
 +----------------------+----------------------------------------------------------------------------+
 |    covar             | covariance matrix (with rows/columns using var_names)                      |
 +----------------------+----------------------------------------------------------------------------+
 |    init_vals         | list of initial values for variable parameters                             |
 +----------------------+----------------------------------------------------------------------------+
+|    init_values       | dictionary of initial values for variable Parameters.                      |
++----------------------+----------------------------------------------------------------------------+
+|    uvars             | dictionary of uncertainties uvalues for all Parameters.                    |
++----------------------+----------------------------------------------------------------------------+
 |    call_kws          | dict of keyword arguments sent to underlying solver                        |
 +----------------------+----------------------------------------------------------------------------+
 
@@ -424,15 +442,25 @@ these statistics.
 Uncertainties in Variable Parameters, and their Correlations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. _uncertainties:   https://github.com/lebigot/uncertainties/
+
 As mentioned above, when a fit is complete the uncertainties for fitted
-Parameters as well as the correlations between pairs of Parameters are
-usually calculated. This happens automatically either when using the
-default :meth:`leastsq` method, the :meth:`least_squares` method, or for
-most other fitting methods if the highly-recommended ``numdifftools``
-package is available. The estimated standard error (the :math:`1\sigma`
-uncertainty) for each variable Parameter will be contained in the
-:attr:`stderr`, while the :attr:`correl` attribute for each Parameter will
-contain a dictionary of the correlation with each other variable Parameter.
+Parameters as well as the correlations between pairs of Parameters are usually
+calculated. This happens automatically either when using the default
+:meth:`leastsq` method, the :meth:`least_squares` method, or for most other
+fitting methods if the highly-recommended ``numdifftools`` package is
+available. The estimated standard error (the :math:`1\sigma` uncertainty) for
+each variable Parameter will be contained in the :attr:`stderr`, while the
+:attr:`correl` attribute for each Parameter will contain a dictionary of the
+correlation with each other variable Parameter.  These updated parameters with
+uncertainty and correlation information will be placed in
+``MinimizerResult.params``, so that you may access the best fit value, standard
+error and correlation. For a successful fit for which uncertainties and
+correlations can be calculated, the ``MinimizerResult`` will also have a
+``uvars`` attribute that is a dictionary with keynames for each Parameter
+(includnig constraints) and values of ``Ufloats`` from the `uncertainties`_
+package using the best fit values, the standard error and the correlation
+between Parameters.
 
 These estimates of the uncertainties are done by inverting the Hessian
 matrix which represents the second derivative of fit quality for each

doc/model.rst

@@ -818,7 +818,8 @@ Parameters and Variables
 
 .. attribute::  params
 
-   Parameters used in fit; will contain the best-fit values.
+   Parameters used in fit; will contain the best-fit values and uncertainties
+   if available.
 
 .. attribute:: uvars
 

tests/test_params_uvars.py

@@ -3,6 +3,7 @@
 
 import numpy as np
 
+from lmfit import create_params, minimize
 from lmfit.models import ExponentialModel, GaussianModel
 
 y, x = np.loadtxt(os.path.join(os.path.dirname(__file__), '..',
@@ -96,3 +97,36 @@ def post_fit(result):
 
     assert post_area.stderr > 43
     assert post_area.stderr < 48
+
+
+def test_uvars_with_minimize():
+    "test that uvars is an attribute of params GH #911"
+    def residual(pars, x, data=None):
+        """Model a decaying sine wave and subtract data."""
+        vals = pars.valuesdict()
+        amp = vals['amp']
+        per = vals['period']
+        shift = vals['shift']
+        decay = vals['decay']
+
+        if abs(shift) > np.pi/2:
+            shift = shift - np.sign(shift)*np.pi
+        model = amp * np.sin(shift + x/per) * np.exp(-x*x*decay*decay)
+        if data is None:
+            return model
+        return model - data
+
+    p_true = create_params(amp=14.0, period=5.46, shift=0.123, decay=0.032)
+    np.random.seed(0)
+    x = np.linspace(0.0, 250., 1001)
+    noise = np.random.normal(scale=0.7215, size=x.size)
+    data = residual(p_true, x) + noise
+
+    fit_params = create_params(amp=13, period=2, shift=0, decay=0.02)
+    out = minimize(residual, fit_params, args=(x,), kws={'data': data})
+
+    assert hasattr(out, 'uvars')
+    assert out.uvars['amp'].nominal_value > 10
+    assert out.uvars['amp'].nominal_value < 20
+    assert out.uvars['amp'].std_dev > 0.05
+    assert out.uvars['amp'].std_dev < 0.50