polyfitnd

sofia_redux.toolkit.fitting.polynomial.polyfitnd(*args, error=1, mask=None, covar=False, solver='linear', set_exponents=False, model=False, stats=None, robust=0, eps=0.01, maxiter=10, **kwargs)

Fits polynomial coefficients to N-dimensional data.

Parameters:

argsN-tuple of array_like

args[-1]int or array_like of int

The polynomial order for all dimensions, or the polynomial order for each dimension supplied in the same order as the independent values.

args[-2]array_like

The dependent data values.

args[:-2]N-tuple of array_like

The independent data values for each dimension.

errorint or float or array_like, optional

Error values for the dependent values. If supplied as an array, the shape must match those supplied as arguments.

maskarray_like of bool, optional

If supplied, must match the shape of the input arguments. False entries will be excluded from any fitting while True entries will be included in the fit.

covarbool, optional

If True, calculate the covariance of the fit parameters. Doing so will return the covariance in addition to the coefficients.

solverstr, optional

One of {‘linear’, ‘nonlinear’, ‘gaussj’}. Defines the algorithm by which to solve for x in the linear equation Ax=B as returned by polysys.

set_exponentsbool, optional

If True, indicates that the user has supplied their own set of polynomial terms in args[-1]. For example, if 2 dimensional independent values were supplied in the (x, y) order, args[-1] = [[0, 0], [1, 2]] would solve for c_0 and c_1 in the equation: fit = c_0 + c_1.x.y^2.

modelbool, optional

If True, return the Polyfit model solution. No other return values will occur such as the covariance or statistics. However, covariance and statistics will still be calculated if covar=True or stats=True and can be accessed through those model attributes.

statsbool, optional

If True, return the statistics on the fit as a Namespace.

robustint or float, optional

If > 0, taken as the sigma threshold above which to identify outliers. Outliers are those identified as |x_i - x_med| / MAD > robust, where x is the residual of (data - fit) x_med is the median, MAD is the median absolute deviation defined as 1.482 * median(abs(x_i - x_med)). The fit will be iterated upon until the set of identified outliers does not change, or any change in the relative RMS is less than eps, or maxiter iterations have occurred.

epsint or float, optional

Termination criterion of (|delta_rms| / rms) < eps for the robust outlier rejection iteration.

maxiterint, optional

Maximum number of iterations for robust outlier rejection.

kwargsdict, optional

Additional keyword arguments to pass into the Polyfit class during initialization.

Returns:

(coefficients, [covariance], [stats]) or Polyfit

The values return depend on the use of the covariance, stats, and model keyword values.

Notes

Order of Arguments and return value order:

The arguments supplied must be provided as:

(X0, [X1, X2, …, XN], Y, order)

where X0 denotes the independent values for the first dimension, and so on, up to dimension N. Y are the dependent values, and order gives the polynomial order to fit to all, or each dimension. All arrays (X and Y) must be of the same shape.

A single value for order applies a redundancy controlled polynomial fit across all dimensions in which:

c_i = 0 if sum(exponents_i) > order

where c_i if the polynomial coefficient for term i. If an array is given for the order argument, no such redundancy control will occur, and a polynomial coefficient will be calculated for each term. i.e., for 2-dimensional x,y data, order=2 would calculate coefficients for the following terms:

C, x, x^2, y, x.y, y^2

while order = [2, 2] would calculate coefficients for the full set of terms:

C, x, x^2, y, x.y, x^2.y, y^2, x.y^2, x^2.y^2

Alternatively, the user may define their own coefficients if set_exponents=True. For example, order=[[0, 0], [1, 2]] would result in the terms:

C, x.y^2

The coefficients returned will be given as an array of N-dimensions with a size of order+1 in each dimension such that coefficients[1, 2] would give the coefficient for the x.y^2 term (if arguments were supplied in the (x, y) order). However, if set_exponents=True, coefficients will be returned in the same order as the terms supplied (1-dimensional array).

If covariance is also returned, it is an (NC x NC) array where NC if the number of coefficients. Coefficients are ordered lexographically along each axis. For example, in 2 dimensions each axis will consist of the following terms in the order:

x^0.y^0, x^0.y^1, …, x^0.y^order, x^1.y^0,…, x^order.y^order

Examples

>>> from sofia_redux.toolkit.fitting.polynomial import polyfitnd
>>> import numpy as np
>>> y, x = np.mgrid[:5, :5]
>>> z = 1 + (2 * x * y) + (0.5 * x ** 2)  # f(x) = 1 + 2xy + 0.5x^2
>>> coefficients = polyfitnd(x, y, z, 2)  # fit a 2nd order polynomial
>>> print(coefficients.round(decimals=2) + 0)
[[1.   0.   0.5]
 [0.   2.   0. ]
 [0.   0.   0. ]]