corgidrp.photon_counting#

Photon count a stack of analog images and return a mean expected electron count array with photometric corrections.

Exceptions#

PhotonCountException

Exception class for photon_count module.

Functions#

varL23(g, L, T, N)

Expected variance after photometric correction.

photon_count(e_image, thresh)

Convert an analog image into a photon-counted image.

get_pc_mean(input_dataset[, pc_master_dark, T_factor, ...])

Take a stack of images, frames of the same exposure

corr_photon_count(nobs, nfr, t, g, mask_indices[, niter])

Correct photon counted images.

calc_lam_approx(nobs, nfr, t, g)

Approximate lambda calculation.

lam_newton_fit(nobs, nfr, t, g, lam0, niter, mask_indices)

Newton fit for finding lambda.

Module Contents#

corgidrp.photon_counting.varL23(g, L, T, N)[source]#

Expected variance after photometric correction. See https://doi.org/10.1117/1.JATIS.9.4.048006 for details.

Parameters:

  • g (scalar) – EM gain

  • L (2-D array) – mean expected number of electrons

  • T (scalar) – threshold

  • N (2-D array) – number of frames

Returns:

variance from photon counting and the photometric correction

Return type:

(float)

exception corgidrp.photon_counting.PhotonCountException[source]#

Bases: Exception

Exception class for photon_count module.

corgidrp.photon_counting.photon_count(e_image, thresh)[source]#

Convert an analog image into a photon-counted image.

Parameters:

  • e_image (array_like, float) – Analog image (e-).

  • thresh (float) – Photon counting threshold (e-). Values > thresh will be assigned a 1, values <= thresh will be assigned a 0.

Returns:

Output digital image in units of photons.

Return type:

pc_image (array_like, float)

B Nemati and S Miller - UAH - 06-Aug-2018

corgidrp.photon_counting.get_pc_mean(input_dataset, pc_master_dark=None, T_factor=None, pc_ecount_max=None, niter=2, mask_filepath=None, safemode=True, inputmode='illuminated', bin_size=None, dataset_copy=True)[source]#

Take a stack of images, frames of the same exposure time, k gain, read noise, and EM gain, and return the mean expected value per pixel. The frames are taken in photon-counting mode, which means high EM gain and very low exposure time.

The frames in each stack should be SCI image (1024x1024) frames that have had some of the L2b steps applied:

  • have had their bias subtracted

  • have had masks made for cosmic rays

  • have been corrected for nonlinearity (These first 3 steps make the frames L2a.)

  • have been frame-selected (to weed out bad frames)

  • have been converted from DN to e-

This algorithm will photon count each frame individually, then co-add the photon-counted frames. The co-added frame is then averaged and corrected for thresholding and coincidence loss, returning the mean expected array in units of photoelectrons if dark-subtracted (detected electrons if not dark-subtracted). The threshold is determined by the input “T_factor”, and the value stored in DetectorParams is used if this input is None.

This function can be used for photon-counting illuminated and dark datasets (see Args below).

Parameters:

  • input_dataset (corgidrp.data.Dataset) – This is an instance of corgidrp.data.Dataset containing the frames to photon-count. All the frames must have the same exposure time, EM gain, k gain, and read noise. If the input dataset’s header key ‘VISTYPE’ is equal to ‘DARK’, a photon-counted master dark calibration product will be produced. Otherwise, the input dataset is assumed to consist of illuminated frames intended for photon-counting. If Dataset has metadata only (as in RAM-heavy case), each frame is read in from its filepath one at a time. If Dataset has its data, then all the frames are processed at once.

  • pc_master_dark (corgidrp.data.Dark) – Dark containing photon-counted master dark(s) to be used for dark subtraction. There is a 3-D cube of master darks, 1 2-D slice per subset of frames specified by the input bin_size (see below). If None, no dark subtraction is done.

  • T_factor (float) – The number of read noise standard deviations at which to set the threshold for photon counting. If None, the value is drawn from corgidrp.data.DetectorParams. Defaults to None.

  • pc_ecount_max (float) – Maximum allowed electrons/pixel/frame for photon counting. If None, the value is drawn from corgidrp.data.DetectorParams. Defaults to None.

  • niter (int, optional) – Number of Newton’s method iterations (used for photometric correction). Defaults to 2.

  • mask_filepath (str) – Filepath to a .fits file with a pixel mask in the default HDU. The mask should be an array of the same shape as that found in each frame of the input_dataset, and the mask should be 0 where the region of interest is and 1 for pixels to be masked (not considered).

  • safemode (bool) – If False, the function does not halt due to an exception (useful for the iterative process of digging the dark hole). If True, the function halts with an exception if the mean intensity of the unmasked pixels (or all pixels if no mask provided) is greater than pc_ecount_max or if the minimum photon-counted pixel value is negative. If False, the function gives a warning for these instead. Defaults to True.

  • inputmode (str) – If ‘illuminated’, the frames are assumed to be illuminated frames. If ‘darks’, frames are assumed to be dark frames input for creation of a photon-counted master dark. This flag shows the user’s intention with the input, and this input is checked against the file type of the dataset for compatibility (e.g., if this input is ‘darks’ while ‘VISTYPE’ is not equal to ‘DARK’, an exception is raised).

  • bin_size (int) – If one wishes to break up the input dataset into subsets of frames to photon-count separately (e.g., for testing the balancing act between good SNR with many frames vs countering speckle time variability with fewer frames), one specifies this number for the size of each subset. If the number does not evenly divide the number of frames in input_dataset, the remainder frames are ignored. The output is the a dataset containing the more than 1 photon-counted mean-combined frame. Defaults to None, in which case the entire input dataset is used, and the output dataset consists of one frame.

  • dataset_copy (bool) – flag indicating whether the input dataset will be preserved after this function is executed or not. If False, the output dataset will be the input dataset modified, and the input and output datasets will be identical. This is useful when handling a large dataset and when the input dataset is not needed afterwards. Defaults to True.

Returns:

If If the input dataset’s header key ‘VISTYPE’ is not equal to ‘CGIVST_CAL_DRK’,

corgidrp.data.Dataset is the output type, and the output is the processed illuminated set, whether dark subtraction happened or not. Contains mean expected array (detected electrons if not dark-subtracted, photoelectrons if dark-subtracted). If the input dataset’s header key ‘VISTYPE’ is equal to ‘CGIVST_CAL_DRK’, corgidrp.data.Dark is the output type, and the output is the processed dark set. Contains mean expected array (detected electrons).

Return type:

corgidrp.data.Dataset or corgidrp.data.Dark

References

[1] https://www.spiedigitallibrary.org/conference-proceedings-of-spie/11443/114435F/Photon-counting-and-precision-photometry-for-the-Roman-Space-Telescope/10.1117/12.2575983.full [2] https://doi.org/10.1117/1.JATIS.9.4.048006

B Nemati, S Miller - UAH - 13-Dec-2020 Kevin Ludwick - UAH - 2023

corgidrp.photon_counting.corr_photon_count(nobs, nfr, t, g, mask_indices, niter=2)[source]#

Correct photon counted images.

Parameters:

  • nobs (array_like) – Number of observations (Co-added photon-counted frame).

  • nfr (int) – Number of coadded frames, accounting for masked pixels in the frames.

  • t (float) – Photon-counting threshold.

  • g (float) – EM gain.

  • mask_indices (array-like) – indices of pixel positions to use.

  • niter (int, optional) – Number of Newton’s method iterations. Defaults to 2.

Returns:

Mean expeted electrons per pixel (lambda).

Return type:

lam (array_like)

corgidrp.photon_counting.calc_lam_approx(nobs, nfr, t, g)[source]#

Approximate lambda calculation.

This will calculate the first order approximation of lambda, and for values that are out of bounds (e.g. from statistical fluctuations) it will revert to the zeroth order.

Parameters:

  • nobs (array_like) – Number of observations (Co-added photon counted frame).

  • nfr (int) – Number of coadded frames.

  • t (float) – Photon counting threshold.

  • g (float) – EM gain used when taking images.

Returns:

Mean expected (lambda).

Return type:

lam1 (array_like)

corgidrp.photon_counting.lam_newton_fit(nobs, nfr, t, g, lam0, niter, mask_indices)[source]#

Newton fit for finding lambda.

Parameters:

  • nobs (array_like) – Number of observations (Co-added photon counted frame).

  • nfr (int) – Number of coadded frames.

  • t (float) – Photon counting threshold.

  • g (float) – EM gain used when taking images.

  • lam0 (array_like) – Initial guess for lambda.

  • niter (int) – Number of Newton’s fit iterations to take.

  • mask_indices (array-like) – indices of pixel positions to use.

Returns:

Mean expected (lambda).

Return type:

lam (array_like)