Merge pull request #614 from lmfit/doc_emcee_fixes

doc and emcee_example fixes

Author: newville

doc/builtin_models.rst

@@ -34,24 +34,35 @@ All the models listed below are one-dimensional, with an independent
 variable named ``x``.  Many of these models represent a function with a
 distinct peak, and so share common features.  To maintain uniformity,
 common parameter names are used whenever possible.  Thus, most models have
-a parameter called ``amplitude`` that represents the overall height (or
-area of) a peak or function, a ``center`` parameter that represents a peak
-centroid position, and a ``sigma`` parameter that gives a characteristic
-width.  Many peak shapes also have a parameter ``fwhm`` (constrained by
-``sigma``) giving the full width at half maximum and a parameter ``height``
-(constrained by ``sigma`` and ``amplitude``) to give the maximum peak
-height.
+a parameter called ``amplitude`` that represents the overall intensity (or
+area of) a peak or function and a ``sigma`` parameter that gives a
+characteristic width.
 
 After a list of built-in models, a few examples of their use are given.
 
 Peak-like models
 -------------------
 
 There are many peak-like models available.  These include
-:class:`GaussianModel`, :class:`LorentzianModel`, :class:`VoigtModel` and
-some less commonly used variations.  The :meth:`guess`
-methods for all of these make a fairly crude guess for the value of
-``amplitude``, but also set a lower bound of 0 on the value of ``sigma``.
+:class:`GaussianModel`, :class:`LorentzianModel`, :class:`VoigtModel`,
+:class:`PseudoVoigtModel`, and some less commonly used variations.  Most of
+these models are *unit-normalized* and share the same parameter names so
+that you can easily switch between models and interpret the results.  The
+``amplitude`` parameter is the multiplicative factor for the
+unit-normalized peak lineshape, and so will represent the strength of that
+peak or the area under that curve.  The ``center`` parameter will be the
+centroid ``x`` value.  The ``sigma`` parameter is the characteristic width
+of the peak, with many functions using :math:`(x-\mu)/\sigma` where
+:math:`\mu` is the centroid value.  Most of these peak functions will have
+two additional parameters derived from and constrained by the other
+parameters. The first of these is ``fwhm`` which will hold the estimated
+"Full Width at Half Max" for the peak, which is often easier to compare
+between different models than ``sigma``.  The second of these is ``height``
+which will contain the maximum value of the peak, typically the value at
+:math:`x = \mu`.  Finally, each of these models has a :meth:`guess` method
+that uses data to make a fairly crude but usually sufficient guess for the
+value of ``amplitude``, ``center``, and ``sigma``, and sets a lower bound
+of 0 on the value of ``sigma``.
 
 :class:`GaussianModel`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/confidence.rst

@@ -106,15 +106,20 @@ parameters and set it manually:
         result.params[p].stderr = abs(result.params[p].value * 0.1)
 
 
-An advanced example
--------------------
+..  _label-confidence-advanced:
+
+An advanced example for evaluating confidence intervals
+---------------------------------------------------------
 
 Now we look at a problem where calculating the error from approximated
-covariance can lead to misleading result -- two decaying exponentials.  In
-fact such a problem is particularly hard for the Levenberg-Marquardt
-method, so we first estimate the results using the slower but robust
-Nelder-Mead  method, and *then* use Levenberg-Marquardt to estimate the
-uncertainties and correlations.
+covariance can lead to misleading result -- the same double exponential
+problem shown in :ref:`label-emcee`.  In fact such a problem is particularly
+hard for the Levenberg-Marquardt method, so we first estimate the results
+using the slower but robust Nelder-Mead method.  We can then compare the
+uncertainties computed (if the ``numdifftools`` package is installed) with
+those estimated using Levenberg-Marquardt around the previously found
+solution.  We can also compare to the results of using ``emcee``.
+
 
 .. jupyter-execute::
     :hide-code:
@@ -168,7 +173,13 @@ Plots of the confidence region are shown in the figures below for ``a1`` and
     plt.show()
 
 Neither of these plots is very much like an ellipse, which is implicitly
-assumed by the approach using the covariance matrix.
+assumed by the approach using the covariance matrix.  The plots actually
+look quite a bit like those found with MCMC and shown in the "corner plot"
+in :ref:`label-emcee`.  In fact, comparing the confidence interval results
+here with the results for the 1- and 2-:math:`\sigma` error estimated with
+``emcee``, we can see that the agreement is pretty good and that the
+asymmetry in the parameter distributions are reflected well in the
+asymmetry of the uncertainties
 
 The trace returned as the optional second argument from
 :func:`conf_interval` contains a dictionary for each variable parameter.