from ..base_primitive import BasePrimitive
from ... import datamodels
from ...calibrations import GainSelector,ReadNoiseSelector
import numpy as np
from typing import Sequence
from ...datamodels.dqflags import DQ_FLAGS
from ..gain.make_gain_primitive import fit_gain_and_readnoise
import logging
logger = logging.getLogger(__name__)
__all__ = ['MakeReadnoisePrimitive']
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"])
[docs]
class MakeReadnoisePrimitive(BasePrimitive):
"""
Estimate detector read noise from up-the-ramp data.
This primitive fits the detector read noise parameter from raw
**dark** up-the-ramp (UTR) ramps using the maximum-likelihood framework
described in Brandt (2025; PASP, 137, 125006). In this case, the gain is fixed and only the readnoise is fitted.
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.
An initial read-noise value may be provided explicitly (e.g., as an
array defining a search grid). If not provided, the primitive is
expected to obtain an appropriate default from the calibration database.
An optional argument allows treating all ramps for a given pixel 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. Use dark exposures.
max_cores : int, optional
Maximum number of CPU cores to use for parallel processing. Default
is 1.
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 an independent
read noise for each pixel. ``'full_detector'`` fits a single read
noise value 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
parameter. ``'both'`` runs a grid search first and then refines the
solution with a quadratic approximation.
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_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.
countratesidentical : bool, optional
If True, assume all ramps have identical count rates. Default is
False.
Calibrations
------------
gain : GainModel
- selector: :class:`~hispecdrp.calibrations.selectors.GainSelector`
rn_init : ReadNoiseModel
- selector: :class:`~hispecdrp.calibrations.selectors.ReadNoiseSelector`
Returns
-------
output : DataModel
Data model containing the fitted read noise parameter 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
"""
PARAMETERS = {
'init_RN' : None, # None | in, Define the initial readnoise value used for the maximum likelihood grid search.
# If None, use calibration database, otherwise specify a np.array (eg, np.linspace(1, 20, 101)).
'mode': 'per_pixel', # str, 'per_pixel' | 'channel' | 'full_detector', mode to fit the parameters.
# 'per_pixel' compute readnoise for each pixel independently,
# 'channel' (Not implemented yet) compute readnoise for each readout channel independently,
# 'full_detector' compute readnoise for the full detector at once. This can be used when a single exposure is available.
'method': 'quad',# str, 'quad' | 'grid' | 'both', method to fit the parameters.
# 'quad' uses quadratic approximation,
# 'grid' uses maximum likelihood grid search.
# 'both' start with grid search and then apply quadratic approximation.
'init_delta_RNs' : None, # np.array, the grid sampling is defined as init_RN + init_delta_RNs for the maximum likelihood grid search.
# specify a np.array (eg, np.linspace(1, 20, 101)).
'quad_delta_RN' : 0.5, # float, used only in 'quad' mode, defines the initial delta read noise around init_RN for the quadratic approximation.
'countratesidentical': False, # bool, if True, assume all ramps have identical count rates.
}
CALIBRATIONS = {
'gain': {
'selector': GainSelector,
'selector_kwargs': {}
},
'rn_init': {
'selector': ReadNoiseSelector,
'selector_kwargs': {}
}
}
def _perform(self):
if self.mode.lower() != 'full_detector' and self.mode.lower() != 'per_pixel':
raise NotImplementedError(
f"Only 'full_detector' and 'per_pixel' modes are implemented currently. Not {self.mode}")
if isinstance(self.dataset, (datamodels.DataModel, str)):
_input_list_tmp = [self.dataset]
if isinstance(self.dataset, Sequence):
_input_list_tmp = self.dataset
nfiles = len(_input_list_tmp)
logger.info(f"Deriving the detector readnoise from a list of {nfiles} inputs.")
input_models = [datamodels.open(f) for f in _input_list_tmp]
datamodel0 = input_models[0]
nreads, ny, nx = datamodel0.data.shape
gain, _ = self.get_calibration(datamodel0, 'gain')
gain_model = datamodels.open(gain)
gain_arr = gain_model.gain
if self.init_RN is None:
rn_cal_init, _ = self.get_calibration(datamodel0, 'rn_init')
rn_model_init = datamodels.open(rn_cal_init)
_init_center_RN = rn_model_init.RN
logger.info(f"Using {rn_cal_init} as initial read noise values with median value {np.nanmedian(_init_center_RN)} DN.")
elif isinstance(self.init_RN, float):
_init_center_RN = self.init_RN
logger.info(f"Using user-defined initial read noise values: {self.init_RN}.")
delta_readtimes = datamodel0.get_delta_readtimes()
if self.method == 'quad':
_init_delta_RNs = np.array([-self.quad_delta_RN,0,+self.quad_delta_RN])
elif self.method == 'grid' or self.method == 'both':
if self.init_delta_RNs is None:
_init_delta_RNs = np.linspace(-10,10, 51)
else:
_init_delta_RNs = self.init_delta_RNs
if self.mode.lower() == 'full_detector':
logger.info(
f"Running in full_detector mode. All detector pixels will be fitted jointly and a single gain and/or readnoise value will be returned for the entire chip.")
elif self.mode.lower() == 'per_pixel':
logger.info(
f"Running in single_pixel mode. Each detector pixel will be fitted independently and a map of gain and/or readnoise will be returned.")
# Define output model from inputs
output_detrn = self.get_output_model(input_models, "ReadNoiseModel")
# Make all ramps from all files into a big cube
ramp_arr = []
dq_raw_arr = []
for opened_input in input_models:
if nreads != opened_input.data.shape[0]:
raise ValueError("All input ramps must have the same number of reads.")
ramp_arr.append(opened_input.data)
dq_raw_arr.append(opened_input.dq_raw)
ramp_arr = np.array(ramp_arr)
dq_raw_arr = np.array(dq_raw_arr)
max_cores = self.max_cores or 1
_out = fit_gain_and_readnoise(
delta_readtimes, ramp_arr, dq_raw_arr, gain_arr, _init_center_RN, None, _init_delta_RNs,
countratesidentical=self.countratesidentical,
mode=self.mode,
method=self.method,
max_cores=max_cores
)
_, bestfit_rn, cov = _out
# Output
output_detrn.rn = bestfit_rn
output_detrn.rn_err = np.sqrt(cov[1,1])
output_detrn.dq = np.zeros(bestfit_rn.shape, dtype=np.uint32)
return dict(output=output_detrn)