ShepardIDWInterpolator#

class photutils.utils.ShepardIDWInterpolator(coordinates, values, weights=None, leafsize=10)[source]#

Bases: object

Class to perform Inverse Distance Weighted (IDW) interpolation.

This interpolator uses a modified version of Shepard’s method (see the Notes section for details).

Parameters:

coordinatesfloat, 1D array_like, or NxM array_like: Coordinates of the known data points. In general, it is expected that these coordinates are in a form of a NxM-like array where N is the number of points and M is dimension of the coordinate space. When M=1 (1D space), then the coordinates parameter may be entered as a 1D array or, if only one data point is available, coordinates can be a scalar number representing the 1D coordinate of the data point.

Note

If the dimensionality of coordinates is larger than 2, e.g., if it is of the form N1 x N2 x N3 x … x Nn x M, then it will be flattened to form an array of size NxM where N = N1 * N2 * … * Nn.
valuesfloat or 1D array_like: Values of the data points corresponding to each coordinate provided in coordinates. In general a 1D array is expected. When a single data point is available, then values can be a scalar number.

Note

If the dimensionality of values is larger than 1 then it will be flattened.
weightsfloat or 1D array_like, optional: Weights to be associated with each data value. These weights, if provided, will be combined with inverse distance weights (see the Notes section for details). When weights is None (default), then only inverse distance weights will be used. When provided, this input parameter must have the same form as values.
leafsizefloat, optional: The number of points at which the k-d tree algorithm switches over to brute-force. leafsize must be positive. See scipy.spatial.cKDTree for further information.

Notes

This interpolator uses a slightly modified version of Shepard’s method. The essential difference is the introduction of a “regularization” parameter (reg) that is used when computing the inverse distance weights:

\[w_i = 1 / (d(x, x_i)^{power} + r)\]

By supplying a positive regularization parameter one can avoid singularities at the locations of the data points as well as control the “smoothness” of the interpolation (e.g., make the weights of the neighbors less varied). The “smoothness” of interpolation can also be controlled by the power parameter (power).

Examples

This class can be instantiated using the following syntax:

>>> from photutils.utils import ShepardIDWInterpolator as idw

Example of interpolating 1D data:

>>> import numpy as np
>>> rng = np.random.default_rng(0)
>>> x = rng.random(100)  # 100 random values
>>> y = np.sin(x)
>>> f = idw(x, y)
>>> float(f(0.4))  
0.38937843420912366
>>> float(np.sin(0.4))  
0.3894183423086505

>>> xi = rng.random(4)  # 4 random values
>>> xi  
array([0.47998792, 0.23237292, 0.80188058, 0.92353016])
>>> f(xi)  
array([0.46577097, 0.22837422, 0.71856662, 0.80125391])
>>> np.sin(xi)  
array([0.46176846, 0.23028731, 0.71866503, 0.7977353 ])

NOTE: In the last example, xi may be a Nx1 array instead of a 1D vector.

Example of interpolating 2D data:

>>> rng = np.random.default_rng(0)
>>> pos = rng.random((1000, 2))
>>> val = np.sin(pos[:, 0] + pos[:, 1])
>>> f = idw(pos, val)
>>> float(f([0.5, 0.6]))  
0.8948257014687874
>>> float(np.sin(0.5 + 0.6))  
0.8912073600614354

Methods Summary

__call__(positions[, n_neighbors, eps, ...])

Evaluate the interpolator at the given positions.

Methods Documentation

__call__(positions, n_neighbors=8, eps=0.0, power=1.0, reg=0.0, conf_dist=1e-12, dtype=<class 'float'>)[source]#

Evaluate the interpolator at the given positions.

Parameters:

positionsfloat, 1D array_like, or NxM array_like: Coordinates of the position(s) at which the interpolator should be evaluated. In general, it is expected that these coordinates are in a form of a NxM-like array where N is the number of points and M is dimension of the coordinate space. When M=1 (1D space), then the positions parameter may be input as a 1D-like array or, if only one data point is available, positions can be a scalar number representing the 1D coordinate of the data point.

Note

If the dimensionality of the positions argument is larger than 2, e.g., if it is of the form N1 x N2 x N3 x … x Nn x M, then it will be flattened to form an array of size NxM where N = N1 * N2 * … * Nn.

Warning

The dimensionality of positions must match the dimensionality of the coordinates used during the initialization of the interpolator.
n_neighborsint, optional: The maximum number of nearest neighbors to use during the interpolation.
epsfloat, optional: Set to use approximate nearest neighbors; the kth neighbor is guaranteed to be no further than (1 + eps) times the distance to the real k-th nearest neighbor. See scipy.spatial.cKDTree.query for further information.
powerfloat, optional: The power of the inverse distance used for the interpolation weights. See the Notes section for more details.
regfloat, optional: The regularization parameter. It may be used to control the smoothness of the interpolator. See the Notes section for more details.
conf_distfloat, optional: The confusion distance below which the interpolator should use the value of the closest data point instead of attempting to interpolate. This is used to avoid singularities at the known data points, especially if reg is 0.0.
dtypedata-type, optional: The data type of the output interpolated values. If None then the type will be inferred from the type of the values parameter used during the initialization of the interpolator.