hispecdrp.primitives.gain.make_gain_primitive
Functions
|
Fit the gain and read noise for each pixel on the detector using either quadratic approximation or maximum likelihood grid search. |
|
Helper function for parallelization fitting the gain and readnoise per detector row. |
|
Worker function for multiprocessing. |
|
Fit the gain and read noise using a grid search maximum likelihood. |
|
Fit the gain and read noise for each pixel on the detector using a quadratic approximation. |
|
Estimate best-fit (gain, read-noise) and an approximate covariance matrix. |
|
Fit y = a*x^2 + b*x + c through exactly three points (xi, yi), without explicit matrix inversion. |
|
Initialize shared global variables for the multiprocessing pool. |
|
Fit for the detector gain and/or read noise. |
|
Plot a 2D log-likelihood map (shifted by max) with confidence contours, and optionally a 1D marginalized gain posterior. |
Classes
|
Estimate the detector electronic gain (and optionally read noise) from up-the-ramp data. |
- class MakeGainPrimitive(dataset=None, config=None, context=None, log_config=None, parent=None, **kwargs)[source]
Bases:
BasePrimitiveEstimate the detector electronic gain (and optionally read noise) from up-the-ramp data.
This primitive fits detector gain and, optionally, read noise parameters from raw up-the-ramp (UTR) ramps using the maximum-likelihood framework described in Brandt (2025; PASP, 137, 125006). Three fitting strategies are supported: a grid-based maximum-likelihood search, a local quadratic approximation, or a hybrid approach that uses the grid search to locate the optimum and then refines it with a quadratic approximation.
Initial gain and read-noise values may be provided explicitly (e.g., as arrays defining a search grid). If not provided, the primitive is expected to obtain appropriate defaults from the calibration database. Optional arguments allow fixing the read noise while fitting only the gain, and treating all ramps as having identical count rates.
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.
- 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 parallel processing. Default is 1.
init_gain (None or array-like, optional) – Initial gain value(s) used to define the maximum-likelihood grid search. If None, obtain an initial value from the calibration database. If provided, this may be a scalar or an array defining the gain sampling (e.g.,
np.linspace(0.1, 10, 101)).init_RN (None or array-like, optional) – Initial read noise value(s) used to define the maximum-likelihood grid search. If None, obtain an initial value from the calibration database. If provided, this may be a scalar or an array defining the read-noise sampling (e.g.,
np.linspace(1, 20, 101)).mode ({'per_pixel', 'channel', 'full_detector'}, optional) – Mode used to fit the parameters.
'per_pixel'fits independent parameters for each pixel.'full_detector'fits a single set of parameters for the detector.'channel'is reserved for future implementation.method ({'quad', 'grid', 'both'}, optional) – Fitting strategy.
'grid'performs a maximum-likelihood grid search.'quad'uses a quadratic approximation around the initial parameters.'both'runs a grid search first and then refines the solution with a quadratic approximation.init_delta_gains (array-like or None, optional) – Gain grid offsets used for the maximum-likelihood grid search. The gain sampling is defined as
init_gain + init_delta_gains.init_delta_RNs (array-like or None, optional) – Read-noise grid offsets used for the maximum-likelihood grid search. The read-noise sampling is defined as
init_RN + init_delta_RNs.quad_delta_gain (float, optional) – Only used when
method='quad'. Defines the initial gain step size aroundinit_gainfor the quadratic approximation. Default is 0.2.quad_delta_RN (float, optional) – Only used when
method='quad'. Defines the initial read-noise step size aroundinit_RNfor the quadratic approximation. Default is 0.5.fix_RN (bool, optional) – If True, fix the read noise to
init_RNand fit only the gain. Default is False.countratesidentical (bool, optional) – If True, assume all ramps have identical count rates. Default is False.
- Calibrations:
gain_init (GainModel) –
selector:
GainSelector
rn_init (ReadNoiseModel) –
selector:
ReadNoiseSelector
- Returns:
output (GainModel) – Data model containing the fitted gain (and, if applicable, read noise) parameters and associated fit diagnostics.
References
Brandt, T. D. (2025), Computing the Electronic Gain for Detectors Read Out Up-the-ramp, PASP, 137, 125006. https://ui.adsabs.harvard.edu/abs/2025PASP..137l5006B/abstract
Roman calibration pipeline reference: https://github.com/spacetelescope/romancal
- fit_gain_and_readnoise(readtimes, ramps, dq_raw, center_gains, center_rns, delta_gains=None, delta_RNs=None, countratesidentical=False, mode='per_pixel', method='quad', max_cores=1)[source]
Fit for the detector gain and/or read noise.
- Parameters:
readtimes (np.ndarray) – 1D array of read times.
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.
center_gains (np.ndarray | float) – Initial center guess for gain (e-/ADU).
center_rns (np.ndarray | float) – Initial center guess for read noise (in DN).
delta_gains (np.ndarray) – The grid sampling is defined as center_gains[i,j] + delta_gains for the maximum likelihood grid search. If None, only fit for read noise while fixing gain to this value. If method is ‘quad’, should be three elements [left, 0, right].
delta_RNs (np.ndarray) – The grid sampling is defined as center_rns[i,j] + delta_RNs for the maximum likelihood grid search. If None, only fit for gain while fixing read noise to this value. If method is ‘quad’, should be three elements [left, 0, right].
countratesidentical (bool) – If True, assume all ramps have identical count rates.
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.
method (str) – Method to use for fitting. Options are ‘quad’ for quadratic approximation, ‘grid’ for maximum likelihood grid search, ‘both’ for grid search followed by quadratic approximation.
max_cores (int, optional) – Number of cores for parallelization. Default is 1 (no parallelization). Not used for mode == ‘full_detector’.
- Returns:
gain (np.ndarray) – Best fit Gain (e-/ADU). Singleton if mode is ‘full_detector’, 2D array if mode is ‘per_pixel’.
rn (np.ndarray) – Best fit read noise (in DN). Singleton if mode is ‘full_detector’, 2D array if mode is ‘per_pixel’.
cov (np.ndarray) – Covariance matrix of the fit. 2D matrix if mode is ‘full_detector’, 4D array if mode is ‘per_pixel’.
- plot_2d_posterior(likelihoods, gains_init, rns_init, *, aspect=0.4, vmin=-20, vmax=0, cmap='bone_r', contour_deltas=(5.9, 3.1, 1.15), contour_color='r', contour_lw=2, cbar_label='$\\log {\\cal L}/{\\cal L}_{\\rm max}$', xlabel='Gain ($e^-$/DN)', ylabel='Read Noise (DN)', title_2d=None, title_1d=None, show=False)[source]
Plot a 2D log-likelihood map (shifted by max) with confidence contours, and optionally a 1D marginalized gain posterior.
- Parameters:
likelihoods ((Nr, Ng) array) – Log-likelihood values on the (rns_init, gains_init) grid. Assumes axis-0 corresponds to rns_init and axis-1 corresponds to gains_init.
gains_init ((Ng,) array) – Gain grid (x-axis).
rns_init ((Nr,) array) – Read-noise grid (y-axis).
show (bool) – If True, calls plt.show() at the end.
- Returns:
figs (dict) – {“2d”: fig2d, “1d”: fig1d_or_None}
axes (dict) – {“2d”: ax2d, “1d”: ax1d_or_None}