fit#

This module contains a collection of helper fit functions.

The functions extensively use the lmfit package.

To fit the azimuthal average of the image structure function:

import fastddm as fddm

# compute the image structure function and the azimuthal average (aa)
...

# import fit model and do fit
from fastddm.fit import fit_multik
from fastddm.fit_models import simple_exponential_model as model

# set the initial estimates for the reference k vector
k_ref = 20  # this is the k index
B_est, _ = fddm.noise_est.estimate_camera_noise(aa, mode='polyfit')
model.set_param_hint('A', value=2.0 * aa.var[k_ref] - B_est[k_ref])
model.set_param_hint('B', value=B_est[k_ref])
model.set_param_hint('Gamma', value=...)

result, model_results = fit_multik(aa,
                                   model,
                                   k_ref,
                                   use_err=True,
                                   return_model_results=True)

You can fix the parameters fit boundaries to some value, for instance:

A_max = 2.0 * aa.power_spec - B_est
A_min = 2.0 * aa.var - B_est

result, model_results = fit_multik(aa,
                                   model,
                                   k_ref,
                                   fixed_params_min={'A': A_min},
                                   fixed_params_max={'A': A_max})

Or you can fix the parameter directly, for instance:

result, model_results = fit_multik(aa,
                                   model,
                                   k_ref,
                                   fixed_params={'B': B_est})
fastddm.fit.fit(model: Model, xdata: ndarray, ydata: ndarray, params: Parameters | Parameter | None = None, estimate_simple_parameters: bool = False, verbose: bool = False, **fitargs: Any) → ModelResult#

A wrapper for fitting a given model to given data.

It is highly recommended to pass the weights argument for very noisy data. All keyword arguments in fitargs will directly be passed to the lmfit.model.Model.fit() method (like weights). If params is presented and estimate_simple_parameters is set to True, first the simple parameters are estimated and the default model parameters updated, then the resulting parameters are updated with the presented parameters again.

Parameters:
Returns:

The results of the fit.

Return type:

lmfit.model.ModelResult

fastddm.fit.fit_multik(data: AzimuthalAverage | IntermediateScatteringFunction, model: Model, ref: int, ref_params: Parameters | None = None, return_model_results: bool | None = False, use_err: bool | None = False, fixed_params: Dict[str, Sequence[float]] | None = None, fixed_params_min: Dict[str, Sequence[float]] | None = None, fixed_params_max: Dict[str, Sequence[float]] | None = None, fixed_params_expr: Dict[str, Sequence[str]] | None = None, **fitargs: Any) → Tuple[DataFrame, List[ModelResult] | None]#

A wrapper for fitting a given model to given data for multiple \(k\) vectors.

The initial parameters estimated for ref index should be set in the model or passed to the function (via ref_params or as keyword arguments). All keyword arguments in fitargs will directly be passed to the lmfit.model.Model.fit() method. See here for more information. It is highly recommended to pass the weights argument for very noisy data (must have the same size of data.tau). Alternatively, one can pass True to the use_err flag and provide a data input containing error values (in the data.err field).

The function starts the fitting process from the ref index and proceeds towards lower and higher indices using the fit parameters obtained from the previous iteration.

Note: If params is None, the values for all parameters relative to ref are expected to be provided as keyword arguments. If params is given, and a keyword argument for a parameter value is also given, the keyword argument will be used. If neither params nor keyword arguments are given, the values set in the model will be used.

Parameters:

  • data (Union[AzimuthalAverage, IntermediateScatteringFunction]) – The azimuthal average or intermediate scattering function object to be fitted.

  • model (lm.Model) – The model to be used for the fit. It must have one and one only independent variable (i.e., the time delay), the name is not important.

  • ref (int) – The index of the reference k vector (where the initial fit parameters are estimated).

  • ref_params (lmfit.parameter.Parameters, optional) – Parameters to use in fit in ref. Default is None.

  • return_model_results (bool, optional) – If True, the function also returns the complete list of lmfit.model.ModelResults obtained for each k vector. Default is False.

  • use_err (bool, optional) – If True, the error estimates in the AzimuthalAverage.err are used in place of weights. If the AzimuthalAverage has no computed err, the default weights are used.

  • fixed_params (Dict[str, Sequence[float]], optional) – Dictionary of {parameter_name: values_array} pairs of parameter values to fix during fitting. The values_array length must be equal to len(data.k). Default is None.

  • fixed_params_min (Dict[str, Sequence[float]], optional) – Dictionary of {parameter_name: values_array} pairs of parameter bounded min values to fix during fitting. The values_array length must be equal to len(data.k). Default is None.

  • fixed_params_max (Dict[str, Sequence[float]], optional) – Dictionary of {parameter_name: values_array} pairs of parameter bounded max values to fix during fitting. The values_array length must be equal to len(data.k). Default is None.

  • fixed_params_expr (Dict[str, Sequence[str]], optional) – Dictionary of {parameter_name: exprs_array} pairs of parameter expressions to fix during fitting. The values_array length must be equal to len(data.k). Default is None.

Returns:

The fit parameters obtained and the success boolean value as a pandas DataFrame. If return_model_results is True, the result is a tuple whose second value is the complete list of lmfit.model.ModelResults obtained.

Return type:

Tuple[pandas.DataFrame, Optional[List[lmfit.model.ModelResult]]]