utils.stats

Statistical helpers: monotonicity, outliers, line fits, bad-pixel interpolation.

kpfpipe.utils.stats.flag_outliers(x, sigma, axis=None, kernel_size=None, method='median')

Flag elements of x more than sigma robust deviations from their peers.

axis selects the axis along which each element is compared to its peers:

  • method="median" computes the median and MAD reducing over axis, so each element is judged against the others sharing its remaining indices (e.g. axis=0 on a (frame, row, col) cube flags, per pixel, the frames that deviate across the stack).

  • method="trend" smooths x along axis (see _smooth_filter) and judges each element against that local trend, so it tolerates structure that varies smoothly along axis (e.g. illumination along dispersion).

axis=None compares every element to a single global statistic.

kpfpipe.utils.stats.interpolate_bad_pixels(data, mask, method='local', fill_outside=True)

Interpolate over bad pixels of a 2D image, replacing each with a value inferred from its good neighbors.

Parameters:

  • data (ndarray) – 2D image; bad pixels are filled, good pixels pass through unchanged. Not modified in place (a copy is returned).

  • mask (ndarray) – Good-pixel mask broadcastable to data, truthy where a pixel is good. Its logical complement marks the pixels to interpolate.

  • method ({'local', 'global'}, default 'local') –

    • 'local': fill each bad pixel from a 3x3 weighted mean of its good neighbors (assumes isolated bad pixels).

    • 'global': bilinearly interpolate every bad pixel from the full good grid (robust to clumps of adjacent bad pixels).

  • fill_outside (bool, default True) – Fill any bad pixels the chosen method leaves unset – 'local' pixels with no good neighbor in their 3x3 window, 'global' pixels outside the good-data convex hull – with the value of the nearest filled pixel (a Euclidean distance-transform lookup). If False, such pixels are left untouched: they keep their original value under 'local' and become NaN under 'global'.

Returns:

Copy of data with bad pixels interpolated.

Return type:

ndarray

Raises:

ValueError – If method is not ‘local’ or ‘global’.

kpfpipe.utils.stats.optimize_lsq(x, y, linemodel)

Fit a 1D line model to (x, y) by non-linear least squares.

Looks up the model function, analytic Jacobian, and initial-guess generator registered under linemodel, then fits via MINPACK’s lmder (scipy.optimize.leastsq, not least_squares – see the implementation note below), and maps the solution back with the model’s untransform.

Parameters:

  • x (ndarray) – 1D independent variable (e.g. velocity or pixel grid).

  • y (ndarray) – 1D dependent variable to fit, same shape as x.

  • linemodel (str) – Registered line-profile name. Currently only ‘gaussian’ is supported; an unknown name raises.

Returns:

  • theta (ndarray) – Fitted parameters in the model’s reported convention. For ‘gaussian’: [b, a, mu, sigma] (baseline, amplitude, center, positive width).

  • rms (float) – RMS of the fit residuals (std of model - y at the solution).

Raises:

ValueError – If linemodel is not a registered line-profile name.

kpfpipe.utils.stats.strictly_increasing(x)

Return True if the 1D array is strictly increasing.