corgidrp.calibrate_kgain#

Attributes#

kgain_params_default

Exceptions#

CalKgainException

Exception class for calibrate_kgain.

Functions#

check_kgain_params(kgain_params)

Checks integrity of kgain parameters in the dictionary kgain_params.

ptc_bin2(frame_in, mean_frame, binwidth, max_DN)

frame_in is a bias-corrected frame trimmed to the ROI. mean_frame is

diff2std(diff_frame[, detector_regions])

calculate the standard deviation of the frame difference,

gauss(x, A, mean, sigma)

Gauss function. Called by sgaussfit.

sgaussfit(xdata, ydata, gaussinp)

Find fitting parameters to Gauss function. Called by Single_peakfit.

Single_peakfit(xdata, ydata)

Fit Gauss function to x, y data. Returns mean and sigma. Only sigma

histc_roi(frame, rn_bins[, detector_regions])

Histogram of pixel values of frame within the ROI and bins defined in

calculate_mode(arr)

calculates histogram of an array

sigma_clip(data[, sigma, max_iters])

Perform sigma-clipping on the data.

calibrate_kgain(dataset_kgain[, n_cal, n_mean, ...])

kgain (e-/DN) is calculated from the means and variances

kgain_dataset_2_list(dataset[, apply_dq])

Casts the CORGIDRP Dataset object for K-gain calibration into a list of

Module Contents#

corgidrp.calibrate_kgain.kgain_params_default[source]#
corgidrp.calibrate_kgain.check_kgain_params(kgain_params)[source]#

Checks integrity of kgain parameters in the dictionary kgain_params.

Parameters:

kgain_params (dict) – Dictionary of parameters used for calibrating the k gain.

exception corgidrp.calibrate_kgain.CalKgainException[source]#

Bases: Exception

Exception class for calibrate_kgain.

corgidrp.calibrate_kgain.ptc_bin2(frame_in, mean_frame, binwidth, max_DN)[source]#

frame_in is a bias-corrected frame trimmed to the ROI. mean_frame is the scaled high SNR mean frame made from the >=30 frames of uniform exposure time, binwidth is an integer equal to the width of each bin, max_DN is an integer equal to the maximum DN value to be included in the bins.

Parameters:

  • frame_in (np.array) – bias corrected frame

  • mean_frame (np.array) – mean frame of uniform exposure time

  • binwidth (int) – width of each bin

  • max_DN (int) – maximum DN value

Returns:

mean array np.array: mean array

Return type:

np.array

corgidrp.calibrate_kgain.diff2std(diff_frame, detector_regions=None)[source]#

calculate the standard deviation of the frame difference, diff_frame within the ROI row and column boundaries.

Parameters:

  • diff_frame (np.array) – frame diffference

  • detector_regions (dict) – a dictionary of detector geometry properties. Keys should be as found in detector_areas in detector.py. Defaults to that dictionary.

Returns:

standard deviation of frame difference

Return type:

np.array

corgidrp.calibrate_kgain.gauss(x, A, mean, sigma)[source]#

Gauss function. Called by sgaussfit.

Parameters:

  • x (np.array) – input array

  • A (float) – amplitude

  • mean (float) – mean value

  • sigma (float) – sigma

Returns:

Gauss function

Return type:

np.array

corgidrp.calibrate_kgain.sgaussfit(xdata, ydata, gaussinp)[source]#

Find fitting parameters to Gauss function. Called by Single_peakfit. gaussinp is an array containing initial values of A, mean, sigma.

Parameters:

  • xdata (np.array) – input x array

  • ydata (np.array) – input y array

  • gaussinp (np.array) – initial guess array

Returns:

fit parameters np.array: fit parameters

Return type:

np.array

corgidrp.calibrate_kgain.Single_peakfit(xdata, ydata)[source]#

Fit Gauss function to x, y data. Returns mean and sigma. Only sigma is used in main code call.

Parameters:

  • xdata (np.array) – x data

  • ydata (np.array) – y data

Returns:

sigma

Return type:

float

corgidrp.calibrate_kgain.histc_roi(frame, rn_bins, detector_regions=None)[source]#

Histogram of pixel values of frame within the ROI and bins defined in rn_bins. Returns the counts in each bin.

Parameters:

  • frame (np.array) – frame

  • rn_bins (int) – histogram bins

  • detector_regions (dict) – a dictionary of detector geometry properties. Keys should be as found in detector_areas in detector.py. Defaults to that dictionary.

Returns:

counts in each bin

Return type:

np.array

corgidrp.calibrate_kgain.calculate_mode(arr)[source]#

calculates histogram of an array

Parameters:

arr (np.array) – input array

Returns:

bin center values np.array: bin center counts

Return type:

np.array

corgidrp.calibrate_kgain.sigma_clip(data, sigma=2.5, max_iters=6)[source]#

Perform sigma-clipping on the data.

Parameters:

  • data (np.array) – The input data to be sigma-clipped.

  • sigma (float) – The number of standard deviations to use for clipping.

  • max_iters (int) – The maximum number of iterations to perform.

Returns:

The sigma-clipped data. np.ndarray: A boolean mask where True indicates a clipped value.

Return type:

np.ndarray

corgidrp.calibrate_kgain.calibrate_kgain(dataset_kgain, n_cal=10, n_mean=30, min_val=800, max_val=3000, binwidth=68, make_plot=False, plot_outdir='figures', show_plot=False, logspace_start=-1, logspace_stop=4, logspace_num=200, verbose=False, detector_regions=None, kgain_params=None, apply_dq=True, dataset_copy=True)[source]#

kgain (e-/DN) is calculated from the means and variances within the defined minimum and maximum mean values. A photon transfer curve is plotted from the std dev and mean values from the bins.

Parameters:

  • dataset_kgain (corgidrp.Dataset) – The frames in the dataset are bias-subtracted. The dataset contains frames belonging to two different sets – Mean frame and a large array of unity gain frames. Mean frame: Unity gain frames with constant exposure time. These frames are used to create a mean pupil image. The mean frame is used to select pixels in each frame of the large array of unity gain frames (see next) to calculate its mean signal. In general, it is expected that at least 30 frames or more will be taken for this set. In TVAC, 30 frames, each with an exposure time of 5.0 sec were taken. Large array of unity gain frames: Set of unity gain frames with subsets of equal exposure times. Data for each subset should be taken sequentially: Each subset must have at least 5 frames. All frames for a subset are taken before moving to the next subset. Two of the subsets have the same (repeated) exposure time. These two subsets are not contiguous: The first subset is taken near the start of the data collection and the second one is taken at the end of the data collection (see TVAC example below). Two subsets with the same exposure time are not strictly needed for k gain calibration, but they are needed for nonlinearity calibration, and the same visit will be used to cover both k gain and nonlinearity calibrations, so there should be two unity gain frame subsets with the same exposure time. The mean signal of these two subsets is used to correct for illumination brightness/sensor sensitivity drifts in nonlinearity calibration for all the frames in the whole set, depending on when the frames were taken. There should be no other repeated exposure time among the subsets. In TVAC, a total of 110 frames were taken within this category. The 110 frames consisted of 22 subsets, each with 5 frames. All 5 frames had the same exposure time. The exposure times in TVAC in seconds were, each repeated 5 times to collect 5 frames in each subset – 0.077, 0.770, 1.538, 2.308, 3.077, 3.846, 4.615, 5.385, 6.154, 6.923, 7.692, 8.462, 9.231, 10.000, 11.538, 10.769, 12.308, 13.077, 13.846, 14.615, 15.385, and 1.538 (again).

  • n_cal (int) – Minimum number of sub-stacks used to calibrate K-Gain. The default value is 10.

  • n_mean (int) – Minimum number of frames used to generate the mean frame. The default value is 30.

  • min_val (int) – Minimum value (in DN) of mean values from sub-stacks to use in calculating kgain. (> 400 recommended)

  • max_val (int) – Maximum value (in DN) of mean values from sub-stacks to use in calculating kgain. Choose value that avoids large deviations from linearity at high counts. (< 6,000 recommended)

  • binwidth (int) – (Optional) Width of each bin for calculating std devs and means from each sub-stack in dataset_kgain. Maximum value of binwidth is 800. Notice that small values increase computation time. (minimum 10; binwidth between 65 and 75 recommended)

  • make_plot (bool) – (Optional) generate and store plots. Default is True.

  • plot_outdir (str) – (Optional) Output directory to store figues. Default is ‘figures’. The default directory is not tracked by git.

  • show_plot (bool) – (Optional) display the plots. Default is False.

  • logspace_start (int) – log plot min value in np.logspace.

  • logspace_stop (int) – log plot max value in np.logspace.

  • logspace_num (int) – Number of elements in np.logspace.

  • verbose (bool) – (Optional) display various diagnostic print messages. Default is False.

  • detector_regions (dict) – a dictionary of detector geometry properties. Keys should be as found in detector_areas in detector.py. Defaults to that dictionary.

  • kgain_params (dict) – (Optional) Dictionary containing row and col specifications for the region of interest (indicated by ‘rowroi1’,’rowroi2’,’colroi1’,and ‘colroi2’). The ‘roi’ needs one square region specified, and ‘back’ needs two square regions, where a ‘1’ ending indicates the smaller of two values, and a ‘2’ ending indicates the larger of two values. The coordinates of the square region are specified by matching up as follows: (rowroi1, colroi1), (rowroi2, colroi1), etc. Also must contain: ‘rn_bins1’: lower bound of counts histogram for fitting or read noise ‘rn_bins2’: upper bound of counts histogram for fitting or read noise ‘max_DN_val’: maximum DN value to be included in photon transfer curve (PTC) ‘signal_bins_N’: number of bins in the signal variables of PTC curve Defaults to kgain_params_default included in this file.

  • apply_dq (bool) – consider the dq mask (from cosmic ray detection) or not

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

kgain estimate from the least-squares fit to the photon

transfer curve (in e-/DN). The expected value of kgain for EXCAM with flight readout sequence should be between 8 and 9 e-/DN

Return type:

corgidrp.data.KGain

corgidrp.calibrate_kgain.kgain_dataset_2_list(dataset, apply_dq=True)[source]#

Casts the CORGIDRP Dataset object for K-gain calibration into a list of numpy arrays sharing the same exposure time. It also returns the list of unique EM values and set of exposure times used with each EM. Note: EM gain is the commanded values: EMGAIN_C.

This function also performs a set of tests about the data type and values in dataset.

Parameters:

  • dataset (corgidrp.Dataset) – Dataset with a set of of EXCAM illuminated

  • frames (pupil L1 SCI)

  • apply_dq (bool) – consider the dq mask (from cosmic ray detection) or not

Returns:

list with stack of stacks of data array associated with each frame array of exposure times associated with each frame array of datetimes associated with each frame