Modeling Data and Curve Fitting¶
A common use of least-squares minimization is curve fitting, where one
has a parametrized model function meant to explain some phenomena and wants
to adjust the numerical values for the model so that it most closely
matches some data. With scipy
, such problems are typically solved
with scipy.optimize.curve_fit, which is a wrapper around
scipy.optimize.leastsq. Since lmfit’s
minimize()
is also a high-level wrapper around
scipy.optimize.leastsq it can be used for curve-fitting problems.
While it offers many benefits over scipy.optimize.leastsq, using
minimize()
for many curve-fitting problems still
requires more effort than using scipy.optimize.curve_fit.
The Model
class in lmfit provides a simple and flexible approach
to curve-fitting problems. Like scipy.optimize.curve_fit, a
Model
uses a model function – a function that is meant to
calculate a model for some phenomenon – and then uses that to best match
an array of supplied data. Beyond that similarity, its interface is rather
different from scipy.optimize.curve_fit, for example in that it uses
Parameters
, but also offers several other
important advantages.
In addition to allowing you to turn any model function into a curve-fitting
method, lmfit also provides canonical definitions for many known lineshapes
such as Gaussian or Lorentzian peaks and Exponential decays that are widely
used in many scientific domains. These are available in the models
module that will be discussed in more detail in the next chapter
(Built-in Fitting Models in the models module). We mention it here as you may want to
consult that list before writing your own model. For now, we focus on
turning Python functions into high-level fitting models with the
Model
class, and using these to fit data.
Motivation and simple example: Fit data to Gaussian profile¶
Let’s start with a simple and common example of fitting data to a Gaussian
peak. As we will see, there is a built-in GaussianModel
class that
can help do this, but here we’ll build our own. We start with a simple
definition of the model function:
We want to use this function to fit to data \(y(x)\) represented by the
arrays y
and x
. With scipy.optimize.curve_fit, this would be:
That is, we create data, make an initial guess of the model values, and run scipy.optimize.curve_fit with the model function, data arrays, and initial guesses. The results returned are the optimal values for the parameters and the covariance matrix. It’s simple and useful, but it misses the benefits of lmfit.
With lmfit, we create a Model
that wraps the gaussian
model
function, which automatically generates the appropriate residual function,
and determines the corresponding parameter names from the function
signature itself:
As you can see, the Model gmodel
determined the names of the parameters
and the independent variables. By default, the first argument of the
function is taken as the independent variable, held in
independent_vars
, and the rest of the functions positional
arguments (and, in certain cases, keyword arguments – see below) are used
for Parameter names. Thus, for the gaussian
function above, the
independent variable is x
, and the parameters are named amp
,
cen
, and wid
, and – all taken directly from the signature of the
model function. As we will see below, you can modify the default
assignment of independent variable / arguments and specify yourself what
the independent variable is and which function arguments should be identified
as parameter names.
Parameters
are not created when the model is
created. The model knows what the parameters should be named, but nothing about
the scale and range of your data. To help you create Parameters for a Model,
each model has a make_params()
method that will generate parameters with
the expected names. You will have to do this, or make Parameters some other way
(say, with create_params()
), and assign initial values
for all Parameters. You can also assign other attributes when doing this:
This creates the Parameters
but does not
automatically give them initial values since it has no idea what the scale
should be. If left unspecified, the initial values will be -Inf
, which will
generally fail to give useful results. You can set initial values for
parameters with keyword arguments to make_params()
:
or assign them (and other parameter properties) after the
Parameters
class has been created.
A Model
has several methods associated with it. For example, one
can use the eval()
method to evaluate the model or the fit()
method to fit data to this model with a Parameter
object. Both of
these methods can take explicit keyword arguments for the parameter values.
For example, one could use eval()
to calculate the predicted
function:
or with:
Admittedly, this a slightly long-winded way to calculate a Gaussian
function, given that you could have called your gaussian
function
directly. But now that the model is set up, we can use its fit()
method to fit this model to data, as with:
or with:
Putting everything together, included in the examples
folder with the
source code, is:
which is pretty compact and to the point. The returned result
will be
a ModelResult
object. As we will see below, this has many
components, including a fit_report()
method, which will show:
As the script shows, the result will also have init_fit
for the fit
with the initial parameter values and a best_fit
for the fit with
the best fit parameter values. These can be used to generate the following
plot:
which shows the data in blue dots, the best fit as a solid green line, and the initial fit as a dashed orange line.
Note that the model fitting was really performed with:
These lines clearly express that we want to turn the gaussian
function
into a fitting model, and then fit the \(y(x)\) data to this model,
starting with values of 5 for amp
, 5 for cen
and 1 for wid
. In
addition, all the other features of lmfit are included:
Parameters
can have bounds and constraints and
the result is a rich object that can be reused to explore the model fit in
detail.
The Model
class¶
The Model
class provides a general way to wrap a pre-defined
function as a fitting model.
- class Model(func, independent_vars=None, param_names=None, nan_policy='raise', prefix='', name=None, **kws)¶
Create a model from a user-supplied model function.
The model function will normally take an independent variable (generally, the first argument) and a series of arguments that are meant to be parameters for the model. It will return an array of data to model some data as for a curve-fitting problem.
- Parameters:
func (callable) – Function to be wrapped.
independent_vars (
list
ofstr
, optional) – Arguments to func that are independent variables (default is None).param_names (
list
ofstr
, optional) – Names of arguments to func that are to be made into parameters (default is None).nan_policy ({'raise', 'propagate', 'omit'}, optional) – How to handle NaN and missing values in data. See Notes below.
prefix (str, optional) – Prefix used for the model.
name (str, optional) – Name for the model. When None (default) the name is the same as the model function (func).
**kws (dict, optional) – Additional keyword arguments to pass to model function.
Notes
1. Parameter names are inferred from the function arguments, and a residual function is automatically constructed.
2. The model function must return an array that will be the same size as the data being modeled.
3. nan_policy sets what to do when a NaN or missing value is seen in the data. Should be one of:
‘raise’ : raise a ValueError (default)
‘propagate’ : do nothing
‘omit’ : drop missing data
Examples
The model function will normally take an independent variable (generally, the first argument) and a series of arguments that are meant to be parameters for the model. Thus, a simple peak using a Gaussian defined as:
>>> import numpy as np >>> def gaussian(x, amp, cen, wid): ... return amp * np.exp(-(x-cen)**2 / wid)
can be turned into a Model with:
>>> gmodel = Model(gaussian)
this will automatically discover the names of the independent variables and parameters:
>>> print(gmodel.param_names, gmodel.independent_vars) ['amp', 'cen', 'wid'], ['x']
Model
class Methods¶
- Model.eval(params=None, **kwargs)¶
Evaluate the model with supplied parameters and keyword arguments.
- Parameters:
params (Parameters, optional) – Parameters to use in Model.
**kwargs (optional) – Additional keyword arguments to pass to model function.
- Returns:
Value of model given the parameters and other arguments.
- Return type:
numpy.ndarray, float, int or complex
Notes
1. if params is None, the values for all parameters are expected to be provided as keyword arguments.
2. If params is given, and a keyword argument for a parameter value is also given, the keyword argument will be used in place of the value in the value in params.
3. all non-parameter arguments for the model function, including all the independent variables will need to be passed in using keyword arguments.
4. The return types are generally numpy.ndarray, but may depends on the model function and input independent variables. That is, return values may be Python float, int, or complex values.
- Model.fit(data, params=None, weights=None, method='leastsq', iter_cb=None, scale_covar=True, verbose=False, fit_kws=None, nan_policy=None, calc_covar=True, max_nfev=None, **kwargs)¶
Fit the model to the data using the supplied Parameters.
- Parameters:
data (array_like) – Array of data to be fit.
params (Parameters, optional) – Parameters to use in fit (default is None).
weights (array_like, optional) – Weights to use for the calculation of the fit residual [i.e., weights*(data-fit)]. Default is None; must have the same size as data.
method (str, optional) – Name of fitting method to use (default is ‘leastsq’).
iter_cb (callable, optional) – Callback function to call at each iteration (default is None).
scale_covar (bool, optional) – Whether to automatically scale the covariance matrix when calculating uncertainties (default is True).
verbose (bool, optional) – Whether to print a message when a new parameter is added because of a hint (default is True).
fit_kws (dict, optional) – Options to pass to the minimizer being used.
nan_policy ({'raise', 'propagate', 'omit'}, optional) – What to do when encountering NaNs when fitting Model.
calc_covar (bool, optional) – Whether to calculate the covariance matrix (default is True) for solvers other than ‘leastsq’ and ‘least_squares’. Requires the
numdifftools
package to be installed.max_nfev (int or None, optional) – Maximum number of function evaluations (default is None). The default value depends on the fitting method.
**kwargs (optional) – Arguments to pass to the model function, possibly overriding parameters.
- Return type:
Notes
1. if params is None, the values for all parameters are expected to be provided as keyword arguments. Mixing params and keyword arguments is deprecated (see Model.eval).
2. all non-parameter arguments for the model function, including all the independent variables will need to be passed in using keyword arguments.
3. Parameters are copied on input, so that the original Parameter objects are unchanged, and the updated values are in the returned ModelResult.
Examples
Take
t
to be the independent variable and data to be the curve we will fit. Use keyword arguments to set initial guesses:>>> result = my_model.fit(data, tau=5, N=3, t=t)
Or, for more control, pass a Parameters object.
>>> result = my_model.fit(data, params, t=t)
- Model.guess(data, x, **kws)¶
Guess starting values for the parameters of a Model.
This is not implemented for all models, but is available for many of the built-in models.
- Parameters:
data (array_like) – Array of data (i.e., y-values) to use to guess parameter values.
x (array_like) – Array of values for the independent variable (i.e., x-values).
**kws (optional) – Additional keyword arguments, passed to model function.
- Returns:
Initial, guessed values for the parameters of a Model.
- Return type:
- Raises:
NotImplementedError – If the guess method is not implemented for a Model.
Notes
Should be implemented for each model subclass to run self.make_params(), update starting values and return a Parameters object.
Changed in version 1.0.3: Argument
x
is now explicitly required to estimate starting values.
- Model.make_params(verbose=False, **kwargs)¶
Create a Parameters object for a Model.
- Parameters:
verbose (bool, optional) – Whether to print out messages (default is False).
**kwargs (optional) –
- Parameter names and initial values or dictionaries of
values and attributes.
- Returns:
params – Parameters object for the Model.
- Return type:
Notes
Parameter values can be numbers (floats or ints) to set the parameter value, or dictionaries with any of the following keywords:
value
,vary
,min
,max
,expr
,brute_step
,is_init_value
to set those parameter attributes.This method will also apply any default values or parameter hints that may have been defined for the model.
Example
>>> gmodel = GaussianModel(prefix='peak_') + LinearModel(prefix='bkg_') >>> gmodel.make_params(peak_center=3200, bkg_offset=0, bkg_slope=0, ... peak_amplitdue=dict(value=100, min=2), ... peak_sigma=dict(value=25, min=0, max=1000))
- Model.set_param_hint(name, **kwargs)¶
Set hints to use when creating parameters with make_params().
The given hint can include optional bounds and constraints
(value, vary, min, max, expr)
, which will be used by Model.make_params() when building default parameters.While this can be used to set initial values, Model.make_params or the function create_params should be preferred for creating parameters with initial values.
The intended use here is to control how a Model should create parameters, such as setting bounds that are required by the mathematics of the model (for example, that a peak width cannot be negative), or to define common constrained parameters.
- Parameters:
name (str) – Parameter name, can include the models prefix or not.
**kwargs (optional) –
Arbitrary keyword arguments, needs to be a Parameter attribute. Can be any of the following:
- valuefloat, optional
Numerical Parameter value.
- varybool, optional
Whether the Parameter is varied during a fit (default is True).
- minfloat, optional
Lower bound for value (default is
-numpy.inf
, no lower bound).
- maxfloat, optional
Upper bound for value (default is
numpy.inf
, no upper bound).
- exprstr, optional
Mathematical expression used to constrain the value during the fit.
Example
>>> model = GaussianModel() >>> model.set_param_hint('sigma', min=0)
Model
class Attributes¶
- func¶
The model function used to calculate the model.
- independent_vars¶
List of strings for names of the independent variables.
- nan_policy¶
Describes what to do for NaNs that indicate missing values in the data. The choices are:
'raise'
: Raise aValueError
(default)'propagate'
: Do not check for NaNs or missing values. The fit will try to ignore them.'omit'
: Remove NaNs or missing observations in data. If pandas is installed,pandas.isnull()
is used, otherwisenumpy.isnan()
is used.
- name¶
Name of the model, used only in the string representation of the model. By default this will be taken from the model function.
- opts¶
Extra keyword arguments to pass to model function. Normally this will be determined internally and should not be changed.
- param_hints¶
Dictionary of parameter hints. See Using parameter hints.
- param_names¶
List of strings of parameter names.
- prefix¶
Prefix used for name-mangling of parameter names. The default is
''
. If a particularModel
has argumentsamplitude
,center
, andsigma
, these would become the parameter names. Using a prefix of'g1_'
would convert these parameter names tog1_amplitude
,g1_center
, andg1_sigma
. This can be essential to avoid name collision in composite models.
Determining parameter names and independent variables for a function¶
The Model
created from the supplied function func
will create a
Parameters
object, and names are inferred from the
function` arguments, and a residual function is automatically constructed.
By default, the independent variable is taken as the first argument to the function. You can, of course, explicitly set this, and will need to do so if the independent variable is not first in the list, or if there is actually more than one independent variable.
If not specified, Parameters are constructed from all positional arguments and all keyword arguments that have a default value that is numerical, except the independent variable, of course. Importantly, the Parameters can be modified after creation. In fact, you will have to do this because none of the parameters have valid initial values. In addition, one can place bounds and constraints on Parameters, or fix their values.
Explicitly specifying independent_vars
¶
As we saw for the Gaussian example above, creating a Model
from a
function is fairly easy. Let’s try another one:
Here, t
is assumed to be the independent variable because it is the
first argument to the function. The other function arguments are used to
create parameters for the model.
If you want tau
to be the independent variable in the above example,
you can say so:
You can also supply multiple values for multi-dimensional functions with multiple independent variables. In fact, the meaning of independent variable here is simple, and based on how it treats arguments of the function you are modeling:
- independent variable
A function argument that is not a parameter or otherwise part of the model, and that will be required to be explicitly provided as a keyword argument for each fit with
Model.fit()
or evaluation withModel.eval()
.
Note that independent variables are not required to be arrays, or even floating point numbers.
Functions with keyword arguments¶
If the model function had keyword parameters, these would be turned into
Parameters if the supplied default value was a valid number (but not
None
, True
, or False
).
Here, even though N
is a keyword argument to the function, it is turned
into a parameter, with the default numerical value as its initial value.
By default, it is permitted to be varied in the fit – the 10 is taken as
an initial value, not a fixed value. On the other hand, the
check_positive
keyword argument, was not converted to a parameter
because it has a boolean default value. In some sense,
check_positive
becomes like an independent variable to the model.
However, because it has a default value it is not required to be given for
each model evaluation or fit, as independent variables are.
Defining a prefix
for the Parameters¶
As we will see in the next chapter when combining models, it is sometimes
necessary to decorate the parameter names in the model, but still have them
be correctly used in the underlying model function. This would be
necessary, for example, if two parameters in a composite model (see
Composite Models : adding (or multiplying) Models or examples in the next chapter) would have
the same name. To avoid this, we can add a prefix
to the
Model
which will automatically do this mapping for us.
You would refer to these parameters as f1_amplitude
and so forth, and
the model will know to map these to the amplitude
argument of myfunc
.
Initializing model parameter values¶
As mentioned above, creating a model does not automatically create the
corresponding Parameters
. These can be created with
either the create_params()
function, or the Model.make_params()
method of the corresponding instance of Model
.
When creating Parameters, each parameter is created with invalid initial value
of -Inf
if it is not set explicitly. That is to say, parameter values
must be initialized in order for the model to evaluate a finite result or
used in a fit. There are a few different ways to do this:
You can supply initial values in the definition of the model function.
You can initialize the parameters when creating parameters with
Model.make_params()
.You can create a Parameters object with
Parameters
orcreate_params()
.You can supply initial values for the parameters when calling
Model.eval()
orModel.fit()
methods.
Generally, using the Model.make_params()
method is recommended. The methods
described above can be mixed, allowing you to overwrite initial values at any point
in the process of defining and using the model.
Initializing values in the function definition¶
To supply initial values for parameters in the definition of the model function, you can simply supply a default value:
instead of using:
This has the advantage of working at the function level – all parameters with keywords can be treated as options. It also means that some default initial value will always be available for the parameter.
Initializing values with Model.make_params()
¶
When creating parameters with Model.make_params()
you can specify initial
values. To do this, use keyword arguments for the parameter names. You can
either set initial values as numbers (floats or ints) or as dictionaries with
keywords of (value
, vary
, min
, max
, expr
, brute_step
,
and is_init_value
) to specify these parameter attributes.
Creating a Parameters
object directly¶
You can also create your own Parameters directly using create_params()
.
This is independent of using the Model
class, but is essentially
equivalent to Model.make_params()
except with less checking of errors for
model prefixes and so on.
Because less error checking is done, Model.make_params()
should probably
be preferred when using Models.
Initializing parameter values for a model with keyword arguments¶
Finally, you can explicitly supply initial values when using a model. That
is, as with Model.make_params()
, you can include values as keyword
arguments to either the Model.eval()
or Model.fit()
methods:
These approaches to initialization provide many opportunities for setting
initial values for parameters. The methods can be combined, so that you
can set parameter hints but then change the initial value explicitly with
Model.fit()
.
Using parameter hints¶
After a model has been created, but prior to creating parameters with
Model.make_params()
, you can define parameter hints for that model. This
allows you to set other parameter attributes for bounds, whether it is varied in
the fit, or set a default constraint expression for a parameter. You can also
set the initial value, but that is not really the intention of the method,
which is to really to let you say that about the idealized Model, for example
that some values may not make sense for some parameters, or that some parameters
might be a small change from another parameter and so be fixed or constrained
by default.
To set a parameter hint, you can use Model.set_param_hint()
,
as with:
Parameter hints are discussed in more detail in section Using parameter hints.
Parameter hints are stored in a model’s param_hints
attribute,
which is simply a nested dictionary:
You can change this dictionary directly or use the Model.set_param_hint()
method. Either way, these parameter hints are used by Model.make_params()
when making parameters.
Parameter hints also allow you to create new parameters. This can be useful to make derived parameters with constraint expressions. For example to get the full-width at half maximum of a Gaussian model, one could use a parameter hint of:
With that definition, the value (and uncertainty) of the fwhm
parameter
will be reported in the output of any fit done with that model.
Data Types for data and independent data with Model
¶
The model as defined by your model function will use the independent
variable(s) you specify to best match the data you provide. The model is meant
to be an abstract representation for data, but when you do a fit with
Model.fit()
, you really need to pass in values for the data to be modeled
and the independent data used to calculate that data.
The mathematical solvers used by lmfit
all work exclusively with
1-dimensional numpy arrays of datatype (dtype) float64
. The value of the
calculation (model-data)*weights
using the calculation of your model
function, and the data and weights you pass in will be coerced to an
1-dimensional ndarray with dtype float64
when it is passed to the solver.
If the data you pass to Model.fit()
is not an ndarray of dtype
float64
but is instead a tuples of numbers, a list of numbers, or a
pandas.Series
, it will be coerced into an ndarray. If your data is a list,
tuple, or Series of complex numbers, it will be coerced to an ndarray with
dtype complex128
.
If your data is a numpy array of dtype float32
, it will not be coerced to
float64
, as we assume this was an intentional choice. That may make all of
the calculations done in your model function be in single-precision which may
make fits less sensitive, but the values will be converted to float64
before being sent to the solver, so the fit should work.
The independent data for models using Model
are meant to be truly
independent, and not not required to be strictly numerical or objects that
are easily converted to arrays of numbers. That is, independent data for a
model could be a dictionary, an instance of a user-defined class, or other type
of structured data. You can use independent data any way you want in your
model function.
But, as with almost all the examples given here, independent data is often also
a 1-dimensonal array of values, say x
, and a simple view of the fit would be
to plot the data as y
as a function of x
. Again, this is not required, but
it is very common. Because of this very common usage, if your independent data
is a tuple or list of numbers or pandas.Series
, it will be coerced to be
an ndarray of dtype float64
. But as with the primary data, if your
independent data is an ndarray of some different dtype (float32
,
uint16
, etc), it will not be coerced to float64
, as we assume this
was intentional.
Note
Data and independent data that are tuples or lists of numbers, or
panda.Series
will be coerced to an ndarray of dtype float64
before
passing to the model function. Data with other dtypes (or independent data
of other object types such as dicts) will not be coerced to float64
.
Saving and Loading Models¶
New in version 0.9.8.
It is sometimes desirable to save a Model
for later use outside of
the code used to define the model. Lmfit provides a save_model()
function that will save a Model
to a file. There is also a
companion load_model()
function that can read this file and
reconstruct a Model
from it.
Saving a model turns out to be somewhat challenging. The main issue is that
Python is not normally able to serialize a function (such as the model
function making up the heart of the Model) in a way that can be
reconstructed into a callable Python object. The dill
package can
sometimes serialize functions, but with the limitation that it can be used
only in the same version of Python. In addition, class methods used as
model functions will not retain the rest of the class attributes and
methods, and so may not be usable. With all those warnings, it should be
emphasized that if you are willing to save or reuse the definition of the
model function as Python code, then saving the Parameters and rest of the
components that make up a model presents no problem.
If the dill
package is installed, the model function will also be saved
using it. But because saving the model function is not always reliable,
saving a model will always save the name of the model function. The
load_model()
takes an optional funcdefs
argument that can
contain a dictionary of function definitions with the function names as
keys and function objects as values. If one of the dictionary keys matches
the saved name, the corresponding function object will be used as the model
function. If it is not found by name, and if dill
was used to save
the model, and if dill
is available at run-time, the dill
-encoded
function will try to be used. Note that this approach will generally allow
you to save a model that can be used by another installation of the
same version of Python, but may not work across Python versions. For preserving
fits for extended periods of time (say, archiving for documentation of
scientific results), we strongly encourage you to save the full Python code
used for the model function and fit process.
- save_model(model, fname)¶
Save a Model to a file.
- load_model(fname, funcdefs=None)¶
Load a saved Model from a file.
As a simple example, one can save a model as:
To load that later, one might do:
See also Saving and Loading ModelResults.
The ModelResult
class¶
A ModelResult
(which had been called ModelFit
prior to version
0.9) is the object returned by Model.fit()
. It is a subclass of
Minimizer
, and so contains many of the fit results.
Of course, it knows the Model
and the set of
Parameters
used in the fit, and it has methods to
evaluate the model, to fit the data (or re-fit the data with changes to
the parameters, or fit with different or modified data) and to print out a
report for that fit.
While a Model
encapsulates your model function, it is fairly
abstract and does not contain the parameters or data used in a particular
fit. A ModelResult
does contain parameters and data as well as
methods to alter and re-do fits. Thus the Model
is the idealized
model while the ModelResult
is the messier, more complex (but perhaps
more useful) object that represents a fit with a set of parameters to data
with a model.
A ModelResult
has several attributes holding values for fit
results, and several methods for working with fits. These include
statistics inherited from Minimizer
useful for
comparing different models, including chisqr
, redchi
, aic
,
and bic
.
- class ModelResult(model, params, data=None, weights=None, method='leastsq', fcn_args=None, fcn_kws=None, iter_cb=None, scale_covar=True, nan_policy='raise', calc_covar=True, max_nfev=None, **fit_kws)¶
Result from the Model fit.
This has many attributes and methods for viewing and working with the results of a fit using Model. It inherits from Minimizer, so that it can be used to modify and re-run the fit for the Model.
- Parameters:
model (Model) – Model to use.
params (Parameters) – Parameters with initial values for model.
data (array_like, optional) – Data to be modeled.
weights (array_like, optional) – Weights to multiply
(data-model)
for fit residual.method (str, optional) – Name of minimization method to use (default is ‘leastsq’).
fcn_args (sequence, optional) – Positional arguments to send to model function.
fcn_dict (dict, optional) – Keyword arguments to send to model function.
iter_cb (callable, optional) – Function to call on each iteration of fit.
scale_covar (bool, optional) – Whether to scale covariance matrix for uncertainty evaluation.
nan_policy ({'raise', 'propagate', 'omit'}, optional) – What to do when encountering NaNs when fitting Model.
calc_covar (bool, optional) – Whether to calculate the covariance matrix (default is True) for solvers other than ‘leastsq’ and ‘least_squares’. Requires the
numdifftools
package to be installed.max_nfev (int or None, optional) – Maximum number of function evaluations (default is None). The default value depends on the fitting method.
**fit_kws (optional) – Keyword arguments to send to minimization routine.
ModelResult
methods¶
- ModelResult.eval(params=None, **kwargs)¶
Evaluate model function.
- Parameters:
params (Parameters, optional) – Parameters to use.
**kwargs (optional) – Options to send to Model.eval().
- Returns:
Array or value for the evaluated model.
- Return type:
numpy.ndarray, float, int, or complex
- ModelResult.eval_components(params=None, **kwargs)¶
Evaluate each component of a composite model function.
- Parameters:
params (Parameters, optional) – Parameters, defaults to ModelResult.params.
**kwargs (optional) – Keyword arguments to pass to model function.
- Returns:
Keys are prefixes of component models, and values are the estimated model value for each component of the model.
- Return type:
- ModelResult.fit(data=None, params=None, weights=None, method=None, nan_policy=None, **kwargs)¶
Re-perform fit for a Model, given data and params.
- Parameters:
data (array_like, optional) – Data to be modeled.
params (Parameters, optional) – Parameters with initial values for model.
weights (array_like, optional) – Weights to multiply
(data-model)
for fit residual.method (str, optional) – Name of minimization method to use (default is ‘leastsq’).
nan_policy ({'raise', 'propagate', 'omit'}, optional) – What to do when encountering NaNs when fitting Model.
**kwargs (optional) – Keyword arguments to send to minimization routine.
- ModelResult.fit_report(modelpars=None, show_correl=True, min_correl=0.1, sort_pars=False, correl_mode='list')¶
Return a printable fit report.
The report contains fit statistics and best-fit values with uncertainties and correlations.
- Parameters:
modelpars (Parameters, optional) – Known Model Parameters.
show_correl (bool, optional) – Whether to show list of sorted correlations (default is True).
min_correl (float, optional) – Smallest correlation in absolute value to show (default is 0.1).
sort_pars (callable, optional) – Whether to show parameter names sorted in alphanumerical order (default is False). If False, then the parameters will be listed in the order as they were added to the Parameters dictionary. If callable, then this (one argument) function is used to extract a comparison key from each list element.
correl_mode ({'list', table'} str, optional) – Mode for how to show correlations. Can be either ‘list’ (default) to show a sorted (if
sort_pars
is True) list of correlation values, or ‘table’ to show a complete, formatted table of correlations.
- Returns:
Multi-line text of fit report.
- Return type:
- ModelResult.summary()¶
Return a dictionary with statistics and attributes of a ModelResult.
- Returns:
Dictionary of statistics and many attributes from a ModelResult.
- Return type:
Notes
values for data arrays are not included.
The result summary dictionary will include the following entries:
model
,method
,ndata
,nvarys
,nfree
,chisqr
,redchi
,aic
,bic
,rsquared
,nfev
,max_nfev
,aborted
,errorbars
,success
,message
,lmdif_message
,ier
,nan_policy
,scale_covar
,calc_covar
,ci_out
,col_deriv
,flatchain
,call_kws
,var_names
,user_options
,kws
,init_values
,best_values
, andparams
.where ‘params’ is a list of parameter “states”: tuples with entries of
(name, value, vary, expr, min, max, brute_step, stderr, correl, init_value, user_data)
.3. The result will include only plain Python objects, and so should be easily serializable with JSON or similar tools.
- ModelResult.conf_interval(**kwargs)¶
Calculate the confidence intervals for the variable parameters.
Confidence intervals are calculated using the
confidence.conf_interval()
function and keyword arguments (**kwargs) are passed to that function. The result is stored in theci_out
attribute so that it can be accessed without recalculating them.
- ModelResult.ci_report(with_offset=True, ndigits=5, **kwargs)¶
Return a formatted text report of the confidence intervals.
- Parameters:
- Returns:
Text of formatted report on confidence intervals.
- Return type:
- ModelResult.eval_uncertainty(params=None, sigma=1, **kwargs)¶
Evaluate the uncertainty of the model function.
This can be used to give confidence bands for the model from the uncertainties in the best-fit parameters.
- Parameters:
params (Parameters, optional) – Parameters, defaults to ModelResult.params.
sigma (float, optional) – Confidence level, i.e. how many sigma (default is 1).
**kwargs (optional) – Values of options, independent variables, etcetera.
- Returns:
Uncertainty at each value of the model.
- Return type:
Notes
This is based on the excellent and clear example from https://www.astro.rug.nl/software/kapteyn/kmpfittutorial.html#confidence-and-prediction-intervals, which references the original work of: J. Wolberg, Data Analysis Using the Method of Least Squares, 2006, Springer
The value of sigma is number of sigma values, and is converted to a probability. Values of 1, 2, or 3 give probabilities of 0.6827, 0.9545, and 0.9973, respectively. If the sigma value is < 1, it is interpreted as the probability itself. That is,
sigma=1
andsigma=0.6827
will give the same results, within precision errors.Also sets attributes of dely for the uncertainty of the model (which will be the same as the array returned by this method) and dely_comps, a dictionary of dely for each component.
Examples
>>> out = model.fit(data, params, x=x) >>> dely = out.eval_uncertainty(x=x) >>> plt.plot(x, data) >>> plt.plot(x, out.best_fit) >>> plt.fill_between(x, out.best_fit-dely, ... out.best_fit+dely, color='#888888')
- ModelResult.plot(datafmt='o', fitfmt='-', initfmt='--', xlabel=None, ylabel=None, yerr=None, numpoints=None, fig=None, data_kws=None, fit_kws=None, init_kws=None, ax_res_kws=None, ax_fit_kws=None, fig_kws=None, show_init=False, parse_complex='abs', title=None)¶
Plot the fit results and residuals using matplotlib.
The method will produce a matplotlib figure (if package available) with both results of the fit and the residuals plotted. If the fit model included weights, errorbars will also be plotted. To show the initial conditions for the fit, pass the argument
show_init=True
.- Parameters:
datafmt (str, optional) – Matplotlib format string for data points.
fitfmt (str, optional) – Matplotlib format string for fitted curve.
initfmt (str, optional) – Matplotlib format string for initial conditions for the fit.
xlabel (str, optional) – Matplotlib format string for labeling the x-axis.
ylabel (str, optional) – Matplotlib format string for labeling the y-axis.
yerr (numpy.ndarray, optional) – Array of uncertainties for data array.
numpoints (int, optional) – If provided, the final and initial fit curves are evaluated not only at data points, but refined to contain numpoints points in total.
fig (matplotlib.figure.Figure, optional) – The figure to plot on. The default is None, which means use the current pyplot figure or create one if there is none.
data_kws (dict, optional) – Keyword arguments passed to the plot function for data points.
fit_kws (dict, optional) – Keyword arguments passed to the plot function for fitted curve.
init_kws (dict, optional) – Keyword arguments passed to the plot function for the initial conditions of the fit.
ax_res_kws (dict, optional) – Keyword arguments for the axes for the residuals plot.
ax_fit_kws (dict, optional) – Keyword arguments for the axes for the fit plot.
fig_kws (dict, optional) – Keyword arguments for a new figure, if a new one is created.
show_init (bool, optional) – Whether to show the initial conditions for the fit (default is False).
parse_complex ({'abs', 'real', 'imag', 'angle'}, optional) – How to reduce complex data for plotting. Options are one of: ‘abs’ (default), ‘real’, ‘imag’, or ‘angle’, which correspond to the NumPy functions with the same name.
title (str, optional) – Matplotlib format string for figure title.
- Return type:
See also
ModelResult.plot_fit
Plot the fit results using matplotlib.
ModelResult.plot_residuals
Plot the fit residuals using matplotlib.
Notes
The method combines ModelResult.plot_fit and ModelResult.plot_residuals.
If yerr is specified or if the fit model included weights, then matplotlib.axes.Axes.errorbar is used to plot the data. If yerr is not specified and the fit includes weights, yerr set to
1/self.weights
.If model returns complex data, yerr is treated the same way that weights are in this case.
If fig is None then matplotlib.pyplot.figure(**fig_kws) is called, otherwise fig_kws is ignored.
- ModelResult.plot_fit(ax=None, datafmt='o', fitfmt='-', initfmt='--', xlabel=None, ylabel=None, yerr=None, numpoints=None, data_kws=None, fit_kws=None, init_kws=None, ax_kws=None, show_init=False, parse_complex='abs', title=None)¶
Plot the fit results using matplotlib, if available.
The plot will include the data points, the initial fit curve (optional, with
show_init=True
), and the best-fit curve. If the fit model included weights or if yerr is specified, errorbars will also be plotted.- Parameters:
ax (matplotlib.axes.Axes, optional) – The axes to plot on. The default in None, which means use the current pyplot axis or create one if there is none.
datafmt (str, optional) – Matplotlib format string for data points.
fitfmt (str, optional) – Matplotlib format string for fitted curve.
initfmt (str, optional) – Matplotlib format string for initial conditions for the fit.
xlabel (str, optional) – Matplotlib format string for labeling the x-axis.
ylabel (str, optional) – Matplotlib format string for labeling the y-axis.
yerr (numpy.ndarray, optional) – Array of uncertainties for data array.
numpoints (int, optional) – If provided, the final and initial fit curves are evaluated not only at data points, but refined to contain numpoints points in total.
data_kws (dict, optional) – Keyword arguments passed to the plot function for data points.
fit_kws (dict, optional) – Keyword arguments passed to the plot function for fitted curve.
init_kws (dict, optional) – Keyword arguments passed to the plot function for the initial conditions of the fit.
ax_kws (dict, optional) – Keyword arguments for a new axis, if a new one is created.
show_init (bool, optional) – Whether to show the initial conditions for the fit (default is False).
parse_complex ({'abs', 'real', 'imag', 'angle'}, optional) – How to reduce complex data for plotting. Options are one of: ‘abs’ (default), ‘real’, ‘imag’, or ‘angle’, which correspond to the NumPy functions with the same name.
title (str, optional) – Matplotlib format string for figure title.
- Return type:
See also
ModelResult.plot_residuals
Plot the fit residuals using matplotlib.
ModelResult.plot
Plot the fit results and residuals using matplotlib.
Notes
For details about plot format strings and keyword arguments see documentation of matplotlib.axes.Axes.plot.
If yerr is specified or if the fit model included weights, then matplotlib.axes.Axes.errorbar is used to plot the data. If yerr is not specified and the fit includes weights, yerr set to
1/self.weights
.If model returns complex data, yerr is treated the same way that weights are in this case.
If ax is None then matplotlib.pyplot.gca(**ax_kws) is called.
- ModelResult.plot_residuals(ax=None, datafmt='o', yerr=None, data_kws=None, fit_kws=None, ax_kws=None, parse_complex='abs', title=None)¶
Plot the fit residuals using matplotlib, if available.
If yerr is supplied or if the model included weights, errorbars will also be plotted.
- Parameters:
ax (matplotlib.axes.Axes, optional) – The axes to plot on. The default in None, which means use the current pyplot axis or create one if there is none.
datafmt (str, optional) – Matplotlib format string for data points.
yerr (numpy.ndarray, optional) – Array of uncertainties for data array.
data_kws (dict, optional) – Keyword arguments passed to the plot function for data points.
fit_kws (dict, optional) – Keyword arguments passed to the plot function for fitted curve.
ax_kws (dict, optional) – Keyword arguments for a new axis, if a new one is created.
parse_complex ({'abs', 'real', 'imag', 'angle'}, optional) – How to reduce complex data for plotting. Options are one of: ‘abs’ (default), ‘real’, ‘imag’, or ‘angle’, which correspond to the NumPy functions with the same name.
title (str, optional) – Matplotlib format string for figure title.
- Return type:
See also
ModelResult.plot_fit
Plot the fit results using matplotlib.
ModelResult.plot
Plot the fit results and residuals using matplotlib.
Notes
For details about plot format strings and keyword arguments see documentation of matplotlib.axes.Axes.plot.
If yerr is specified or if the fit model included weights, then matplotlib.axes.Axes.errorbar is used to plot the data. If yerr is not specified and the fit includes weights, yerr set to
1/self.weights
.If model returns complex data, yerr is treated the same way that weights are in this case.
If ax is None then matplotlib.pyplot.gca(**ax_kws) is called.
ModelResult
attributes¶
- aic¶
Floating point best-fit Akaike Information Criterion statistic (see MinimizerResult – the optimization result).
- best_fit¶
numpy.ndarray result of model function, evaluated at provided independent variables and with best-fit parameters.
- best_values¶
Dictionary with parameter names as keys, and best-fit values as values.
- bic¶
Floating point best-fit Bayesian Information Criterion statistic (see MinimizerResult – the optimization result).
- chisqr¶
Floating point best-fit chi-square statistic (see MinimizerResult – the optimization result).
- ci_out¶
Confidence interval data (see Calculation of confidence intervals) or
None
if the confidence intervals have not been calculated.
- covar¶
numpy.ndarray (square) covariance matrix returned from fit.
- data¶
numpy.ndarray of data to compare to model.
- dely¶
numpy.ndarray of estimated uncertainties in the
y
values of the model fromModelResult.eval_uncertainty()
(see Calculating uncertainties in the model function).
- dely_comps¶
a dictionary of estimated uncertainties in the
y
values of the model components, fromModelResult.eval_uncertainty()
(see Calculating uncertainties in the model function).
- errorbars¶
Boolean for whether error bars were estimated by fit.
- ier¶
Integer returned code from scipy.optimize.leastsq.
- init_fit¶
numpy.ndarray result of model function, evaluated at provided independent variables and with initial parameters.
- init_params¶
Initial parameters.
- init_values¶
Dictionary with parameter names as keys, and initial values as values.
- iter_cb¶
Optional callable function, to be called at each fit iteration. This must take take arguments of
(params, iter, resid, *args, **kws)
, whereparams
will have the current parameter values,iter
the iteration,resid
the current residual array, and*args
and**kws
as passed to the objective function. See Using a Iteration Callback Function.
- jacfcn¶
Optional callable function, to be called to calculate Jacobian array.
- lmdif_message¶
String message returned from scipy.optimize.leastsq.
- message¶
String message returned from
minimize()
.
- method¶
String naming fitting method for
minimize()
.
- call_kws¶
Dict of keyword arguments actually send to underlying solver with
minimize()
.
- ndata¶
Integer number of data points.
- nfev¶
Integer number of function evaluations used for fit.
- nfree¶
Integer number of free parameters in fit.
- nvarys¶
Integer number of independent, freely varying variables in fit.
- params¶
Parameters used in fit; will contain the best-fit values.
- redchi¶
Floating point reduced chi-square statistic (see MinimizerResult – the optimization result).
- residual¶
numpy.ndarray for residual.
- rsquared¶
Floating point \(R^2\) statisic, defined for data \(y\) and best-fit model \(f\) as
- scale_covar¶
Boolean flag for whether to automatically scale covariance matrix.
- success¶
Boolean value of whether fit succeeded.
- userargs¶
positional arguments passed to
Model.fit()
, a tuple of (y
,weights
)
- userkws¶
keyword arguments passed to
Model.fit()
, a dict, which will have independent data arrays such asx
.
- weights¶
numpy.ndarray (or
None
) of weighting values to be used in fit. If notNone
, it will be used as a multiplicative factor of the residual array, so thatweights*(data - fit)
is minimized in the least-squares sense.
Calculating uncertainties in the model function¶
We return to the first example above and ask not only for the
uncertainties in the fitted parameters but for the range of values that
those uncertainties mean for the model function itself. We can use the
ModelResult.eval_uncertainty()
method of the model result object to
evaluate the uncertainty in the model with a specified level for
\(\sigma\).
That is, adding:
to the example fit to the Gaussian at the beginning of this chapter will give 3-\(\sigma\) bands for the best-fit Gaussian, and produce the figure below.
New in version 1.0.4.
If the model is a composite built from multiple components, the
ModelResult.eval_uncertainty()
method will evaluate the uncertainty of
both the full model (often the sum of multiple components) as well as the
uncertainty in each component. The uncertainty of the full model will be held in
result.dely
, and the uncertainties for each component will be held in the dictionary
result.dely_comps
, with keys that are the component prefixes.
An example script shows how the uncertainties in components of a composite model can be calculated and used:
Saving and Loading ModelResults¶
New in version 0.9.8.
As with saving models (see section Saving and Loading Models), it is
sometimes desirable to save a ModelResult
, either for later use or
to organize and compare different fit results. Lmfit provides a
save_modelresult()
function that will save a ModelResult
to
a file. There is also a companion load_modelresult()
function that
can read this file and reconstruct a ModelResult
from it.
As discussed in section Saving and Loading Models, there are challenges to
saving model functions that may make it difficult to restore a saved a
ModelResult
in a way that can be used to perform a fit.
Use of the optional funcdefs
argument is generally the most
reliable way to ensure that a loaded ModelResult
can be used to
evaluate the model function or redo the fit.
- save_modelresult(modelresult, fname)¶
Save a ModelResult to a file.
- Parameters:
modelresult (ModelResult) – ModelResult to be saved.
fname (str) – Name of file for saved ModelResult.
- load_modelresult(fname, funcdefs=None)¶
Load a saved ModelResult from a file.
- Parameters:
- Returns:
ModelResult object loaded from file.
- Return type:
An example of saving a ModelResult
is:
To load that later, one might do:
Composite Models : adding (or multiplying) Models¶
One of the more interesting features of the Model
class is that
Models can be added together or combined with basic algebraic operations
(add, subtract, multiply, and divide) to give a composite model. The
composite model will have parameters from each of the component models,
with all parameters being available to influence the whole model. This
ability to combine models will become even more useful in the next chapter,
when pre-built subclasses of Model
are discussed. For now, we’ll
consider a simple example, and build a model of a Gaussian plus a line, as
to model a peak with a background. For such a simple problem, we could just
build a model that included both components:
and use that with:
But we already had a function for a gaussian function, and maybe we’ll discover that a linear background isn’t sufficient which would mean the model function would have to be changed.
Instead, lmfit allows models to be combined into a CompositeModel
.
As an alternative to including a linear background in our model function,
we could define a linear function:
and build a composite model with just:
This model has parameters for both component models, and can be used as:
which prints out the results:
and shows the plot on the left.
On the left, data is shown in blue dots, the total fit is shown in solid green line, and the initial fit is shown as a orange dashed line. The figure on the right shows again the data in blue dots, the Gaussian component as a orange dashed line and the linear component as a green dashed line. It is created using the following code:
The components were generated after the fit using the
ModelResult.eval_components()
method of the result
, which returns
a dictionary of the components, using keys of the model name
(or prefix
if that is set). This will use the parameter values in
result.params
and the independent variables (x
) used during the
fit. Note that while the ModelResult
held in result
does store the
best parameters and the best estimate of the model in result.best_fit
,
the original model and parameters in pars
are left unaltered.
You can apply this composite model to other data sets, or evaluate the
model at other values of x
. You may want to do this to give a finer or
coarser spacing of data point, or to extrapolate the model outside the
fitting range. This can be done with:
In this example, the argument names for the model functions do not overlap.
If they had, the prefix
argument to Model
would have allowed
us to identify which parameter went with which component model. As we will
see in the next chapter, using composite models with the built-in models
provides a simple way to build up complex models.
- class CompositeModel(left, right, op[, **kws])¶
Combine two models (left and right) with binary operator (op).
Normally, one does not have to explicitly create a CompositeModel, but can use normal Python operators
+
,-
,*
, and/
to combine components as in:>>> mod = Model(fcn1) + Model(fcn2) * Model(fcn3)
- Parameters:
Notes
The two models can use different independent variables.
Note that when using built-in Python binary operators, a
CompositeModel
will automatically be constructed for you. That is,
doing:
will create a CompositeModel
. Here, left
will be Model(fcn1)
,
op
will be operator.add()
, and right
will be another
CompositeModel that has a left
attribute of Model(fcn2)
, an op
of
operator.mul()
, and a right
of Model(fcn3)
.
To use a binary operator other than +
, -
, *
, or /
you can
explicitly create a CompositeModel
with the appropriate binary
operator. For example, to convolve two models, you could define a simple
convolution function, perhaps as:
which extends the data in both directions so that the convolving kernel function gives a valid result over the data range. Because this function takes two array arguments and returns an array, it can be used as the binary operator. A full script using this technique is here:
which prints out the results:
and shows the plots:
Using composite models with built-in or custom operators allows you to build complex models from testable sub-components.