hispecdrp.primitives.nonlinear_correction.make_nonlin_primitive
Functions
|
Batch-solve for the smallest admissible real root x, independently for each column ix, where the polynomial P_ix(x) is defined by coefficients in |
|
Fit for the nonlinearity polynomial coefficients on a per pixel basis. |
|
Helper function for parallelization fitting the gain and readnoise per detector row. |
|
Worker function for multiprocessing. |
|
Initialize shared global variables for the multiprocessing pool. |
|
Fit for the detector nonlinearity polynomial coefficients. |
Classes
|
This primitive computes the coefficients of a polynomial nonlinearity correction model from raw up-the-ramp (UTR) detector data |
- class MakeNonLinPrimitive(dataset=None, config=None, context=None, log_config=None, parent=None, **kwargs)[source]
Bases:
BasePrimitiveThis primitive computes the coefficients of a polynomial nonlinearity correction model from raw up-the-ramp (UTR) detector data
Thresholds are also computed to characterize the onset and maximum extent of correctable nonlinearity (eg, 1% and 10% deviation from linearity).
The primitive uses the algorithm described in Brandt (2025; PASP, 137, 125005). The fitted model characterizes the deviation of the measured signal from an ideal linear ramp and is intended to be applied later by the nonlinearity correction step. No science data are modified by this primitive; instead, a nonlinearity calibration model is produced.
Use saturated flat fields to derive the nonlinearity correction model.
The non-linearity correction is assumed to follow:
P(DN) = a0 + a1*DN + a2*DN^2 + … + an*DN^n where P(DN) is the corrected signal, DN is the measured signal, and
a0, a1, …, an are the polynomial coefficients derived in this primitive. Note that the ordering of the coefficients in the calibration file is from lowest order to highest order, which is the reverse of the usual numpy.polyval ordering.
Polynomial fits may be carried out either in the standard power basis or in a Legendre polynomial basis. Reads that exceed a specified fraction of the saturation level are excluded from the fit.
The fitting may be performed on a per-pixel basis or using a single model for the full detector. Although the full detector mode is only for testing since there are too many pixels on a normal detector and the matrix becomes too large with so many ramps.
- Parameters:
input (list of str or list of RampModel) – List of input file paths or ramp models to process.
max_cores (int, optional) – Maximum number of CPU cores to use for the fitting. Default is 1.
mode ({'per_pixel', 'channel', 'full_detector'}, optional) – Mode used to fit the nonlinearity parameters.
'per_pixel'fits an independent model for each pixel.'full_detector'fits a single model to the entire detector.'channel'is reserved for future implementation.use_legendre (bool, optional) – If True, perform the polynomial fit using a Legendre polynomial basis. If False, use the standard power basis. Default is True.
order (int, optional) – Order of the polynomial used to model the detector nonlinearity. Default is 5.
readstart (int, optional) – Index (zero-based) of the first read to include in the fit. Default is 0.
satval_frac (float, optional) – Fraction of the saturation level beyond which reads are excluded from the fit. Default is 0.95.
criterion_for_nonlin_thresh (float, optional) – Fractional deviation from a linear ramp used to define the nonlinearity threshold, above which data are considered non-linear but still correctable. Default is 0.01.
criterion_for_nonlin_max (float, optional) – Fractional deviation from a linear ramp used to define the maximum nonlinearity, above which data are considered too non-linear to be corrected accurately. Default is 0.05.
- Calibrations:
gain (GainModel) –
selector:
GainSelector
rn (ReadNoiseModel) –
selector:
ReadNoiseSelector
saturation (SaturationModel) –
selector:
SaturationSelector
bias (BiasModel) –
selector:
BiasSelector
- Returns:
output (DataModel) – Nonlinearity correction calibration model containing the fitted polynomial coefficients and associated nonlinearity thresholds.
References
Brandt, T. D. (2025), A Classic Nonlinearity Correction Algorithm for Detectors Read Out Up-the-ramp, PASP, 137, 125005. https://ui.adsabs.harvard.edu/abs/2025PASP..137l5005B/abstract
Roman calibration pipeline reference: https://github.com/spacetelescope/romancal
Notes
Relevant HISPEC DRP requirement: REQ-3-DRP-183: The DRP shall correct for the detector non-linearity to better than 1% when deriving pixel fluxes.
- fit_nonlin_coefs(ramps, dq_raw, gain, rn, order=5, satval=None, mode='per_pixel', use_legendre='quad', readstart=0, criterion_for_nonlin_thresh=0.01, criterion_for_nonlin_max=0.1, max_cores=1)[source]
Fit for the detector nonlinearity polynomial coefficients.
- Parameters:
ramps (np.ndarray) – 4D array of input rates. Size n_files x nreads x ny x nx.
dq_raw (np.ndarray) – 4D array of input UTR data quality flags. Size n_files x nreads x ny x nx.
gain (np.ndarray) – gain map (ny,nx) (e-/ADU).
rn (np.ndarray) – read noise map (ny,nx) (in DN).
order (int = 5) – Order of polynomial to fit for the nonlinearity correction.
satval (np.ndarray | None) – Map of values beyond which reads will be ignored in the fit (ny,nx) (in DN). Default is 64000
mode (str) – ‘full_detector’ to fit a single gain and read noise for the entire detector, ‘per_pixel’ to fit gain and read noise for each pixel independently.
use_legendre (bool) – If True, fit in the Legendre polynomial basis.
readstart (int) – First read (indexed from zero) that we use.
criterion_for_nonlin_thresh (float) – Criterion to define the nonlinearity threshold. ie, if the data DN deviates from a linear ramp by more than this fraction, it is considered non-linear, but it can be corrected reasonably accurately.
criterion_for_nonlin_max (float) – Criterion to define the nonlinearity maximum. ie, if the data DN deviates from a linear ramp by more than this fraction, it is considered too non-linear and cannot be corrected accurately.
max_cores (int, optional) – Number of cores for parallelization. Default is 1 (no parallelization). Not used for mode == ‘full_detector’.
- Returns:
nonlin_coefs (np.ndarray) – Nonlinearity coefficients. Size (order+1, ny, nx) if mode is ‘per_pixel’, else (order+1,).
nonlin_thresh (np.ndarray) – Nonlinearity threshold map (ny,nx) (in DN).
nonlin_max (np.ndarray) – Nonlinearity maximum map (ny,nx) (in DN).