AbstractFitFunction

class plasmapy.analysis.fit_functions.AbstractFitFunction(params: Optional[Tuple[float, ...]] = None, param_errors: Optional[Tuple[float, ...]] = None)

Bases: abc.ABC

Abstract class for defining fit functions \(f(x)\) and the tools for fitting the function to a set of data.

Parameters
  • params (Tuple[float, ...], optional) – Tuple of values for the function parameters. Equal in size to param_names.

  • param_errors (Tuple[float, ...], optional) – Tuple of values for the errors associated with the function parameters. Equal in size to param_names.

Attributes Summary

FitParamTuple

A namedtuple used for attributes params and param_errors.

curve_fit_results

The results returned by the curve fitting routine used by curve_fit.

latex_str

LaTeX friendly representation of the fit function.

param_errors

The associated errors of the fitted params.

param_names

Names of the fitted parameters.

params

The fitted parameters for the fit function.

rsq

Coefficient of determination (r-squared) value of the fit.

Methods Summary

__call__(x[, x_err, reterr])

Direct call of the fit function \(f(x)\).

curve_fit(xdata, ydata, **kwargs)

Use a non-linear least squares method to fit the fit function to (xdata, ydata), using scipy.optimize.curve_fit.

func(x, *args)

The fit function.

func_err(x[, x_err, rety])

Calculate dependent variable uncertainties \(\delta y\) for dependent variables \(y=f(x)\).

root_solve(x0)

Solve for the root of the fit function (i.e.

Attributes Documentation

FitParamTuple

A namedtuple used for attributes params and param_errors. The attribute parameter_names defines the tuple field names.

curve_fit_results

The results returned by the curve fitting routine used by curve_fit. This is typically from scipy.stats.linregress or scipy.optimize.curve_fit.

latex_str

LaTeX friendly representation of the fit function.

param_errors

The associated errors of the fitted params.

param_names

Names of the fitted parameters.

params

The fitted parameters for the fit function.

rsq

Coefficient of determination (r-squared) value of the fit.

\[ \begin{align}\begin{aligned}r^2 &= 1 - \frac{SS_{res}}{SS_{tot}}\\SS_{res} &= \sum\limits_{i} (y_i - f(x_i))^2\\SS_{tot} &= \sum\limits_{i} (y_i - \bar{y})^2\end{aligned}\end{align} \]

where \((x_i, y_i)\) are the sample data pairs, \(f(x_i)\) is the fitted dependent variable corresponding to \(x_i\), and \(\bar{y}\) is the average of the \(y_i\) values.

The \(r^2\) value is an indicator of how close the points \((x_i, y_i)\) lie to the model \(f(x)\). \(r^2\) values range between 0 and 1. Values close to 0 indicate that the points are uncorrelated and have little tendency to lie close to the model, whereas, values close to 1 indicate a high correlation to the model.

Methods Documentation

__call__(x, x_err=None, reterr=False)

Direct call of the fit function \(f(x)\).

Parameters
  • x (array_like) – Dependent variables.

  • x_err (array_like, optional) – Errors associated with the independent variables x. Must be of size one or equal to the size of x.

  • reterr (bool, optional) – (Default: False) If True, return an array of uncertainties associated with the calculated independent variables

Returns

  • y (numpy.ndarray) – Corresponding dependent variables \(y=f(x)\) of the independent variables x.

  • y_err (numpy.ndarray) – Uncertainties associated with the calculated dependent variables \(\delta y\)

curve_fit(xdata, ydata, **kwargs) None

Use a non-linear least squares method to fit the fit function to (xdata, ydata), using scipy.optimize.curve_fit. This will set the attributes parameters, parameters_err, and rsq.

The results of scipy.optimize.curve_fit can be obtained via curve_fit_results.

Parameters
  • xdata (array_like) – The independent variable where data is measured. Should be 1D of length M.

  • ydata (array_like) – The dependent data associated with xdata.

  • **kwargs – Any keywords accepted by scipy.optimize.curve_fit.

Raises
  • ValueError – if either ydata or xdata contain numpy.nan’s, or if incompatible options are used.

  • RuntimeError – if the least-squares minimization fails.

  • OptimizeWarning – if covariance of the parameters can not be estimated.

abstract func(x, *args)

The fit function. This signature of the function must first take the independent variable followed by the parameters to be fitted as separate arguments.

Parameters
  • x (array_like) – Independent variables to be passed to the fit function.

  • *args (Tuple[Union[float, int],...]) – The parameters that will be adjusted to make the fit.

Returns

The calculated dependent variables of the independent variables x.

Return type

numpy.ndarray

Notes

  • When sub-classing the definition should look something like:

    def func(self, x, a, b, c):
        x = self._check_x(x)
        self._check_params(a, b, c)
    
        return a * x ** 2 + b * x + c
    
abstract func_err(x, x_err=None, rety=False)

Calculate dependent variable uncertainties \(\delta y\) for dependent variables \(y=f(x)\).

Parameters
  • x (array_like) – Independent variables to be passed to the fit function.

  • x_err (array_like, optional) – Errors associated with the independent variables x. Must be of size one or equal to the size of x.

  • rety (bool) – Set True to also return the associated dependent variables \(y = f(x)\).

Returns

  • err (numpy.ndarray) – The calculated uncertainties \(\delta y\) of the dependent variables (\(y = f(x)\)) of the independent variables x.

  • y (numpy.ndarray, optional) – (if rety == True) The associated dependent variables \(y = f(x)\).

Notes

  • A good reference for formulating propagation of uncertainty expressions is:

    J. R. Taylor. An Introduction to Error Analysis: The Study of Uncertainties in Physical Measurements. University Science Books, second edition, August 1996 (ISBN: 093570275X)

  • When sub-classing the definition should look something like:

    @modify_docstring(append=AbstractFitFunction.func_err.__original_doc__)
    def func_err(self, x, x_err=None, rety=False):
        '''
        A simple docstring giving the equation for error propagation, but
        excluding the parameter descriptions.  The @modify_docstring
        decorator will append the docstring from the parent class.
        '''
        x, x_err = self._check_func_err_params(x, x_err)
    
        a, b, c = self.params
        a_err, b_err, c_err = self.param_errors
    
        # calculate error
    
        if rety:
            y = self.func(x, a, b, c)
            return err, y
    
        return err
    
root_solve(x0)

Solve for the root of the fit function (i.e. \(f(x_r) = 0\)). This mehtod used scipy.optimize.fsolve to find the function roots.

Parameters

x0 (ndarray) – The starting estimate for the roots of \(f(x_r) = 0\).

Returns

  • x (ndarray) – The solution (or the result of the last iteration for an unsuccessful call).

  • x_err (ndarray) – The uncertainty associated with the root calculation. Currently this returns an array of numpy.nan values equal in shape to x , since there is no determined way to calculate the uncertainties.

Notes

If the full output of scipy.optimize.fsolve is desired then one can do:

>>> func = Linear()
>>> func.params = (1.0, 5.0)
>>> func.param_errors = (0.0, 0.0)
>>> roots = fsolve(func, -4.0, full_output=True)
>>> roots
(array([-5.]),
 {'nfev': 4,
  'fjac': array([[-1.]]),
  'r': array([-1.]),
  'qtf': array([2.18...e-12]),
  'fvec': 0.0},
 1,
 'The solution converged.')