hispecdrp.primitives.gain.make_gain_primitive

Functions

_fit_gain_and_readnoise_per_pixel(readtimes, ...)

Fit the gain and read noise for each pixel on the detector using either quadratic approximation or maximum likelihood grid search.

_fit_gain_and_readnoise_row(indata)

Helper function for parallelization fitting the gain and readnoise per detector row.

_fit_gain_and_readnoise_worker(args)

Worker function for multiprocessing.

_fit_single_gain_readnoise(readtimes, ramps, ...)

Fit the gain and read noise using a grid search maximum likelihood.

_fit_single_gain_readnoise_quad_approx(...)

Fit the gain and read noise for each pixel on the detector using a quadratic approximation.

_fitquad_gain_rn(diffs_lin, diffs_quad, ...)

Estimate best-fit (gain, read-noise) and an approximate covariance matrix.

_quad_1d_through_3pts(x, y)

Fit y = a*x^2 + b*x + c through exactly three points (xi, yi), without explicit matrix inversion.

_tpool_init_fit_gain_readnoise(data, ...)

Initialize shared global variables for the multiprocessing pool.

fit_gain_and_readnoise(readtimes, ramps, ...)

Fit for the detector gain and/or read noise.

plot_2d_posterior(likelihoods, gains_init, ...)

Plot a 2D log-likelihood map (shifted by max) with confidence contours, and optionally a 1D marginalized gain posterior.

Classes

MakeGainPrimitive([dataset, config, ...])

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: BasePrimitive

Estimate 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 around init_gain for the quadratic approximation. Default is 0.2.

  • quad_delta_RN (float, optional) – Only used when method='quad'. Defines the initial read-noise step size around init_RN for the quadratic approximation. Default is 0.5.

  • fix_RN (bool, optional) – If True, fix the read noise to init_RN and fit only the gain. Default is False.

  • countratesidentical (bool, optional) – If True, assume all ramps have identical count rates. Default is False.

Calibrations:
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}