solarwindpy.fitfunctions.core

Base classes used to implement specific fit functions.

The FitFunction abstract base class handles selecting the observations to include in a fit, running SciPy optimizers and providing convenient plotting helpers. Subclasses need only define the functional form and an initial parameter guess.

Classes

`ChisqPerDegreeOfFreedom`(linear, robust)
`FitBounds`(lower, upper)
`FitFunction`(xobs, yobs[, xmin, xmax, ...])	Assuming that you don't want special formatting, call order is:
`FitFunctionMeta`(name, bases, namespace, /, ...)	Metaclass combining ABC and docstring inheritance.
`InitialGuessInfo`(p0, bounds)
`Observations`(x, y, w)
`UsedRawObs`(used, raw, tk_observed)

Exceptions

`FitFailedError`	Raised when the fitting algorithm fails to converge.
`FitFunctionError`	Base exception for fit function errors.
`InsufficientDataError`	Raised when there is insufficient data to perform the fit.
`InvalidParameterError`	Raised when invalid parameters are provided to fit functions.

class Observations(x, y, w)

Bases: tuple

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=sys.maxsize, /)

Return first index of value.

Raises ValueError if the value is not present.

w: Alias for field number 2

x: Alias for field number 0

y: Alias for field number 1

class UsedRawObs(used, raw, tk_observed)

Bases: tuple

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=sys.maxsize, /)

Return first index of value.

Raises ValueError if the value is not present.

raw: Alias for field number 1

tk_observed: Alias for field number 2

used: Alias for field number 0

class InitialGuessInfo(p0, bounds)

Bases: tuple

bounds: Alias for field number 1

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=sys.maxsize, /)

Return first index of value.

Raises ValueError if the value is not present.

p0: Alias for field number 0

class ChisqPerDegreeOfFreedom(linear, robust)

Bases: tuple

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=sys.maxsize, /)

Return first index of value.

Raises ValueError if the value is not present.

linear: Alias for field number 0

robust: Alias for field number 1

class FitBounds(lower, upper)

Bases: tuple

count(value, /): Return number of occurrences of value.

index(value, start=0, stop=sys.maxsize, /)

Return first index of value.

Raises ValueError if the value is not present.

lower: Alias for field number 0

upper: Alias for field number 1

exception FitFunctionError[source]

Bases: Exception

Base exception for fit function errors.

__init__(*args, **kwargs)

add_note(): Exception.add_note(note) – add a note to the exception

args

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception InsufficientDataError[source]

Bases: FitFunctionError

Raised when there is insufficient data to perform the fit.

__init__(*args, **kwargs)

add_note(): Exception.add_note(note) – add a note to the exception

args

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception FitFailedError[source]

Bases: FitFunctionError

Raised when the fitting algorithm fails to converge.

__init__(*args, **kwargs)

add_note(): Exception.add_note(note) – add a note to the exception

args

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

exception InvalidParameterError[source]

Bases: FitFunctionError

Raised when invalid parameters are provided to fit functions.

__init__(*args, **kwargs)

add_note(): Exception.add_note(note) – add a note to the exception

args

with_traceback(): Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.

class FitFunctionMeta(name, bases, namespace, /, **kwargs)[source]

Bases: NumpyDocstringInheritanceMeta, ABCMeta

Metaclass combining ABC and docstring inheritance.

__init__(class_name: str, class_bases: tuple[type], class_dict: dict[str, Any]) → None

mro(/): Return a type’s method resolution order.

register(subclass)

Register a virtual subclass of an ABC.

Returns the subclass, to allow usage as a class decorator.

class FitFunction(xobs, yobs, xmin=None, xmax=None, xoutside=None, ymin=None, ymax=None, youtside=None, weights=None, wmin=None, wmax=None, logx=False, logy=False)[source]

Bases: ABC

Assuming that you don’t want special formatting, call order is:

fit_function = FitFunction(function, TeX_string) fit_function.make_fit()

Instances are callable. If the fit fails, calling the instance will return an array of NaNs the same shape as the x-values.

__init__(xobs, yobs, xmin=None, xmax=None, xoutside=None, ymin=None, ymax=None, youtside=None, weights=None, wmin=None, wmax=None, logx=False, logy=False)[source]

Initialize fit function with observed data.

Parameters:

xobs (array-like) – Observed x values (independent variable). Shape must match yobs.
yobs (array-like) – Observed y values (dependent variable). Shape must match xobs.
xmin (float, optional) – Range limits for x used in fitting. Values outside this range are excluded from the fit. All boundaries are inclusive (>= or <=).
xmax (float, optional) – Range limits for x used in fitting. Values outside this range are excluded from the fit. All boundaries are inclusive (>= or <=).
xmax – The description is missing.
xoutside (tuple(float, float), optional) – Include only data outside this range in the fit. Useful for excluding a central region. Format: (lower, upper) where lower < upper.
ymin (float, optional) – Range limits for y used in fitting. Values outside this range are excluded from the fit.
ymax (float, optional) – Range limits for y used in fitting. Values outside this range are excluded from the fit.
ymax – The description is missing.
youtside (tuple(float, float), optional) – Include only data outside this range. Format: (lower, upper) where lower < upper.
weights (array-like, optional) – Uncertainties (1-sigma) associated with y values. Used for weighted least squares fitting. If 1-d array, interpreted as diagonal covariance matrix. If 2-d, must be positive definite covariance matrix.
wmin (float, optional) – Weight limits. Observations with weights outside this range are excluded from the fit.
wmax (float, optional) – Weight limits. Observations with weights outside this range are excluded from the fit.
wmax – The description is missing.
logx (bool, default False) – Whether to interpret x or y on a log10 scale. If logy=True, weight selection uses w/(y*ln(10)) for proper error propagation in log space.
logy (bool, default False) – Whether to interpret x or y on a log10 scale. If logy=True, weight selection uses w/(y*ln(10)) for proper error propagation in log space.
logy – The description is missing.

Notes

The fitting procedure uses scipy.optimize.least_squares with robust loss functions (Huber by default) to handle outliers. The initial parameter guess is provided by the p0 property, which must be implemented by subclasses.

All subclasses inherit this documentation automatically through the docstring-inheritance metaclass.

Examples

>>> import numpy as np
>>> from solarwindpy.fitfunctions import Gaussian
>>> x = np.linspace(-5, 5, 100)
>>> y = 3 * np.exp(-0.5 * x**2) + np.random.normal(0, 0.1, 100)
>>> fit = Gaussian(x, y, xmin=-3, xmax=3)
>>> fit.make_fit()
>>> print(f"Fitted mu: {fit.popt['mu']:.3f}")

See also

make_fit: Execute the fitting procedure
popt: Access optimized parameters
rsq: Calculate coefficient of determination

property logger

abstract property function

Get the function that`curve_fit` fits.

The function is set at instantiation. It doesn’t make sense to change it unless you redefine the entire FitFunction, so there is no new kwarg.

abstract property p0: The initial guess for the FitFunction.

abstract property TeX_function: Function written in LaTeX.

property argnames: The names of the actual function arguments pulled by getfullargspec.

property fit_bounds: Bounds used when running the fit.

property chisq_dof

Chisq per degree of freedom \(\chi^2_\nu\).

If None, not calculated by make_fit_old. If np.nan, fit failed.

property dof: Degrees of freedom in the fit.

property fit_result

property initial_guess_info

property nobs: The total number of observations used in the fit.

property observations

property plotter

property popt: Optimized fit parameters.

property psigma

property combined_popt_psigma

Return optimized parameters and uncertainties as a DataFrame.

Returns:: DataFrame with columns ‘popt’ and ‘psigma’, indexed by parameter names. Relative uncertainty can be computed as: df[‘psigma’] / df[‘popt’]
Return type:: pd.DataFrame

property pcov: Returns a copy so that the matrix isn’t accidentally edited.

property rsq

Coefficient of determination.

Source: <en.wikipedia.org/wiki/Coefficient_of_determination#Definitions>

property sufficient_data: Ensure that we can fit the data before doing any computations.

property TeX_info

build_plotter()[source]

build_TeX_info()[source]

residuals(pct=False, use_all=False)[source]

Calculate fit residuals.

Parameters:

pct (bool, default=False) – If True, return percentage residuals.
use_all (bool, default=False) – If True, calculate residuals for all input data including points excluded by constraints (xmin, xmax, etc.) passed during initialization. If False (default), calculate only for points used in fit.

Returns:

Residuals as observed - fitted.

Return type:

numpy.ndarray

Examples

>>> # Create FitFunction with constraints
>>> ff = Gaussian(x, y, xmin=3, xmax=7)
>>> ff.make_fit()
>>>
>>> # Residuals for fitted region only
>>> r_fit = ff.residuals()
>>>
>>> # Residuals for all original data
>>> r_all = ff.residuals(use_all=True)
>>>
>>> # Percentage residuals
>>> r_pct = ff.residuals(pct=True)

Notes

Addresses TODO: “calculate with all values…including those excluded by set_extrema” (though set_extrema doesn’t exist - constraints are passed in __init__).

set_fit_obs(xobs_raw, yobs_raw, weights_raw, xmin=None, xmax=None, xoutside=None, ymin=None, ymax=None, youtside=None, wmin=None, wmax=None, logx=False, logy=False)[source]

Set the observed values we’ll actually use in the fit.

By applying limits to xobs_raw and yobs_raw and checking for finite values.

All boundaries are inclusive <= or >=.

If logy, then make selection of wmin and wmax based on \(w/(y \ln(10))\).

Parameters:

xobs_raw – The description is missing.
yobs_raw – The description is missing.
weights_raw – The description is missing.
xmin – The description is missing.
xmax – The description is missing.
xoutside – The description is missing.
ymin – The description is missing.
ymax – The description is missing.
youtside – The description is missing.
wmin – The description is missing.
wmax – The description is missing.
logx – The description is missing.
logy – The description is missing.

make_fit(return_exception=False, **kwargs)[source]

Fit the function with the independent xobs and dependent yobs.

Uses least_squares and returns the OptimizeResult object, but treats weights as in curve_fit.

Parameters:

return_exception (bool) – If True, return exceptions from fitting routine, instead of raising. This is useful when looping through many fits and wanting to identify failed fits after the fact.
**kwargs – The description is missing.