Source code for hispecdrp.primitives.jump_detection.jump_detection_difference

from ...datamodels.dqflags import DQ_FLAGS
from ...utils.parallelization_utils import numba_thread_scope

import numpy as np
from numba import njit, prange

__all__ = ['jump_detection_difference']

SATURATED_FLAG_uint8 = np.uint8(DQ_FLAGS["SATURATED"])
DO_NOT_USE_FLAG_uint8 = np.uint8(DQ_FLAGS["DO_NOT_USE"])
JUMP_DET_FLAG_uint8 = np.uint8(DQ_FLAGS["JUMP_DET"])

@njit(nogil=True, cache=True, inline='always')
def get_diffs(ramp_row):
    """Successive-read differences as float64 (avoid uint16 wraparound)."""
    n_reads, nx = ramp_row.shape
    diffs = np.empty((n_reads - 1, nx), dtype=np.float64)
    for i in range(n_reads - 1):
        for j in range(nx):
            diffs[i, j] = np.float64(ramp_row[i + 1, j]) - np.float64(ramp_row[i, j])
    return diffs


@njit(nogil=True, cache=True, inline='always')
def median_axis0_3d(ramp):
    """
    Median along axis=0 for a 3D array shaped (n_reads, ny, nx).
    Returns NumPy's median on integer inputs.
    """
    n, ny, nx = ramp.shape
    out = np.empty((ny, nx), dtype=np.float64)
    for y in range(ny):
        for x in range(nx):
            vec = np.empty(n, dtype=np.float64)
            for i in range(n):
                vec[i] = ramp[i, y, x]
            vec.sort()
            mid = n // 2
            if n % 2 == 0:
                out[y, x] = 0.5 * (vec[mid - 1] + vec[mid])
            else:
                out[y, x] = vec[mid]
    return out

@njit(nogil=True, parallel=True, cache=True)
def _jump_detection_difference_numba(ramp_data, dq_raw, dq, rdnoise, gain,rejection_threshold):
    n_reads, ny, nx = ramp_data.shape

    for i in prange(ny):
        for j in range(nx):
            # Find first saturated index; exclude it and everything after.
            n_use = 1
            for k in range(n_reads):
                # checking backward for saturation to speed up processing since saturation will be at the end of the ramp
                if (dq_raw[n_reads-k-1,i,j] & (SATURATED_FLAG_uint8 | DO_NOT_USE_FLAG_uint8)) == 0:
                    n_use = n_reads-k
                    break

            # Calculate differences between successive reads (float64 DN)
            diffs = get_diffs(ramp_data[0:n_use, i, j : j + 1])

            # Typical difference and noise in DN (rdnoise is DN/read)
            g = gain[i, j] if gain[i, j] > 0.0 else 1.0
            median_diff_dn = median_axis0_3d(diffs[:, None, :])[0, 0]
            photon_var_dn = np.abs(median_diff_dn) / g  # Poisson var of Δ in DN
            total_dn_var = (rdnoise[i, j] ** 2) * 2.0 + photon_var_dn
            sigma_diff = np.sqrt(total_dn_var) if total_dn_var > 0.0 else 0.0

            # Identify jumps
            thr = rejection_threshold * sigma_diff
            for t in range(diffs.shape[0]):
                if sigma_diff > 0.0 and np.abs(diffs[t, 0] - median_diff_dn) > thr:
                    dq_raw[t + 1, i, j] |= JUMP_DET_FLAG_uint8

    return

[docs] def jump_detection_difference( ramp_data: np.ndarray, dq_raw: np.ndarray, dq: np.ndarray, rdnoise : np.ndarray | None = None, gain: np.ndarray | None = None, rejection_threshold: float = 4.0, max_cores: int = 1, ) -> np.ndarray: """ Simple jump detection for a 3D array of up the ramp data. Modifies the input dq array (in-place) to flag where jumps are detected. Parameters ---------- ramp_data : np.ndarray 3D array of the UTR data with shape (Nreads, Ny, Nx). dq_raw : np.ndarray Input data quality flags for the UTR data with shape (Nreads, Ny, Nx). dq : np.ndarray Input data quality flags with shape (Ny, Nx). rdnoise : np.ndarray or None, optional Input read noise array with shape (Ny, Nx). Defaults to 0. gain : np.ndarray or None, optional Input gain array with shape (Ny, Nx). Defaults to 1. rejection_threshold : float, optional Sigma threshold for jump detection. Default is 4.0. max_cores : int, optional Maximum number of CPU cores to use for parallel processing (default: 1). """ n_reads, ny, nx = ramp_data.shape # TODO - determine how to use the input DQ flags to ignore bad data if rdnoise is None: # TODO - optimize read noise when array is not passed rdnoise = np.zeros((ny, nx), dtype=np.float32) if gain is None: # TODO - optimize gain when array is not passed gain = np.ones((ny, nx), dtype=np.float32) assert n_reads >= 2, "Need at least 2 reads to do jump detection." with numba_thread_scope(max_cores): _jump_detection_difference_numba(ramp_data, dq_raw, dq, rdnoise, gain, rejection_threshold)