lezargus.library.container.detector module

Simulation code for modeling a detector.

We constrain ourselves to model CCD and H2RG detectors; or, more specifically, we design the model off of simple CCD detectors and constrain H2RG parameters to model that of a CCD-like detector.

class lezargus.library.container.detector.DetectorArray(detector_shape: tuple, pixel_size: float, detector_gain: float = 1, nondestructive_reads: int = 1, random_state_seed: int | None = None)

Bases: object

The detector class.

__init__(detector_shape: tuple, pixel_size: float, detector_gain: float = 1, nondestructive_reads: int = 1, random_state_seed: int | None = None) → None

Initialize the detector simulator.

Parameters:

• detector_shape (tuple) – The shape of the detector, in pixels. Typically they are squares so the shape may be the same.

• pixel_size (float) – The length or size of a pixel, in meters. Note, we assume square pixels.

• detector_gain (float, default = 1) – The gain value of the detector, stored for later usage.

• nondestructive_reads (int, default = 1) – The number of nondestructive reads the detector does for typical exposures. If a CCD, use 1.

• random_state_seed (int, default = None) – The random state seed for the random number generator. If None, we just pick one at random.

add_bias_frame(bias_frame: hint.NDArray) → None

Add a detector bias frame to the simulated detector.

Parameters:

bias_frame (NDArray) – The bias frame which we are going to add.

Return type:

None

add_cosmic_ray_rates(cosmic_ray_rate: float, cosmic_ray_value: float | None = None) → None

Add the rate of cosmic rays hitting the detector’s pixels.

Parameters:

• cosmic_ray_rate (float) – The rate that cosmic rays are hitting the detector. The units are cosmic ray per second per square meter.

• cosmic_ray_value (float, default = None) – If a cosmic ray does hit the detector, then we add this value; the expected detector value a cosmic ray imparts on the detector. If None, then we assume an arbitrary high value.

Return type:

None

add_dark_current_frame(dark_current_frame: hint.NDArray) → None

Add a detector dark current frame to the simulated detector.

Parameters:

dark_current_frame (NDArray) – The dark current frame which we are going to add.

Return type:

None

add_dead_pixel_map(dead_pixel_map: hint.NDArray, dead_pixel_value: float | None) → None

Add the detector dead pixel map to the simulated detector.

Parameters:

• dead_pixel_map (NDArray) – The dead pixel map as a boolean array. Where True, the pixel is considered dead.

• dead_pixel_value (float, default = None) – The dead pixel value, used when a pixel is dead. If not provided, we default to the current dead pixel value.

Return type:

None

add_efficiency_function(efficiency_function: hint.Callable[[float], float]) → None

Add an efficiency function to the simulated detector.

The efficiency function is a function of the efficiency of the detector over wavelength. The efficiency of the detector is typically due to the quantum efficiency function of the detector but it nessecilarily need not be limited to it. Any efficiency detriment is provided here.

Parameters:

efficiency_function (NDArray) – The efficiency function which we are going to add. The input of

Return type:

None

add_flat_frame(flat_frame: hint.NDArray) → None

Add a detector flat frame to the simulated detector.

Parameters:

flat_frame (NDArray) – The flat frame which we are going to add.

Return type:

None

add_hot_pixel_map(hot_pixel_map: hint.NDArray, hot_pixel_value: float | None) → None

Add the detector hot pixel map to the simulated detector.

Parameters:

• hot_pixel_map (NDArray) – The hot pixel map as a boolean array. Where True, the pixel is considered hot.

• hot_pixel_value (float, default = None) – The hot pixel value, used when a pixel is hot. If not provided, we default to the current hot pixel value.

Return type:

None

add_linearity_function(linearity_function: hint.Callable[[float], float]) → None

Add a detector linearity function to the simulated detector.

Parameters:

linearity_function (NDArray) – The linearity function which we are going to add.

Return type:

None

add_read_noise(read_noise: float, read_noise_stddev: float = 0) → None

Add the detector read noise to the simulated detector.

Parameters:

• read_noise (float) – The read noise of a given pixel within the simulated detector.

• read_noise_stddev (float, default = 0) – The standard deviation of the read noise of a single pixel within the simulated detector.

Return type:

None

bias_frame: hint.NDArray

The averaged bias frame for the detector. This value is typically computed from the provided raw bias frames.

bias_stddev_frame: hint.NDArray

The standard deviation of the average bias frame. This value is typically computed from the provided raw bias frames.

cosmic_ray_rate: float = 0

The rate that cosmic rays hit the surface of the Earth/detector. This is used to compute a cosmic ray pixel map for where cosmic rays hit the pixels. This is in cosmic rays per second per square meter.

cosmic_ray_value: float = inf

The detector value for when a cosmic ray hits the detector. Though we assume a near typical high value, given the variance of cosmic rays.

dark_current_frame: hint.NDArray

The averaged dark current frame for the detector. This value is typically computed from the provided raw dark current frames.

dark_current_stddev_frame: hint.NDArray

The standard deviation of the average dark current frame. This value is typically computed from the provided raw dark current frames.

dead_pixel_map: hint.NDArray

The dead pixel map of the detector. Where True, the pixel is considered a “dead” pixel, and will have its value substituted by the typical dead pixel value. If None, we assume no dead pixels at all.

dead_pixel_value: float = 0

The value of a dead pixel, where the hot pixel map determines which are hot. The value is in ADUs. By default, we assume 0, but there should be much better values.

detector_gain: float = 1

The detector gain value.

detector_shape: tuple

The shape of the detector, described as a tuple shape of the number of pixels.

efficiency_function(wavelength: hint.NDArray) → hint.NDArray

Compute the efficiency of the detector.

The efficiency function of the detector. This is the function which determines the efficiency of the detector at a provided wavelength. The quantum efficiency function should be contained within this function along with any other wavelength-dependent efficiency considerations. If no raw efficiency function has been provided, :py:method:`add_efficiency_function`, then we default to a perfect efficiency function.

Parameters:

wavelength (NDArray) – The wavelength to determine the efficiency of the detector at, as a function of wavelength. The units of the wavelength should be in meters.

Returns:

efficiency – The output efficiency per the detector.

Return type:

NDArray

efficiency_spectrum(wavelength: hint.NDArray, **kwargs: hint.Any) → hint.LezargusSpectrum

Efficiency function of the detector, as a spectrum class.

As a convenience function, we package the efficiency data as a full LezargusSpectrum.

Parameters:

• wavelength (NDArray) – The wavelength to determine the efficiency of the detector at, as a function of wavelength. The units of the wavelength should be in meters.

• **kwargs (Any) – Any additional keywords are passed to LezargusSpectrum. Note, the uncertainty, units, and masks are already handled and duplicate entries will raise an error.

Returns:

efficiency_spectrum – The efficiency data, except as a spectrum.

Return type:

LezargusSpectrum

flat_frame: hint.NDArray

The averaged flat frame for the detector. This value is typically computed from the provided raw flat frames.

flat_stddev_frame: hint.NDArray

The standard deviation of the average flat frame. This value is typically computed from the provided raw flat frames.

get_random_state() → int

Get the random state seed for processing.

This function acts as a middleman where if the random state is set, we just use that, otherwise, we make sure that random numbers can continue to be random numbers.

Parameters:

None

Returns:

random_state – The random state to use.

Return type:

int

hot_pixel_map: hint.NDArray

The hot pixel map of the detector. Where True, the pixel is considered a “hot” pixel, and will have its value substituted by the typical hot pixel value.

hot_pixel_value: float = inf

The value of a hot pixel, where the hot pixel map determines which are hot. The value is in ADUs. By default, we just use infinity, but there should be much better values.

linearity_function(counts: hint.NDArray) → hint.NDArray

Compute the linearity response of the detector.

The linearity function of the detector is used to determine actual ADUs from an expected ADU input, given the lack of linearity at very low and very high values. If no raw linearity function has been provided, :py:method:`add_linearity_function`, then we default to a perfect linearity function.

Parameters:

counts (NDArray) – The input counts which we will use to determine the real output counts on the detector.

Returns:

output – The output counts after the detector linearity has been taken into account.

Return type:

NDArray

nondestructive_reads: int = 1

The number of nondestructive reads made to obtain a given observation. This value is intrinsic to the detector and it mostly affects read noise. Though this is valid for only H2RG-based detectors, for CCDs a value of 1 is appropriate.

pixel_size: float

The length or the size of the pixels, in meters. We assume the pixels are square and so only one measurement is needed.

random_state_seed: int | None = None

The random state seed for all of the functions which need to have a random number generator used. This is mostly for generating new detector frames. If None, which is suggested, we always use a different random state.

raw_bias_frames: list[hint.NDArray] | None = None

The list of bias frames added to the detector to derive simulated bias values from. If None, should no bias frames be provided, we default to a zero bias frame for calculations. The bias is in ADUs.

raw_dark_current_frames: list[hint.NDArray] | None = None

The list of dark current frames added to the detector to derive simulated dark current values from. If None, should no dark current frames be provided, we default to a zero dark current frame for calculations. The dark current is in ADUs per second.

raw_dead_pixel_maps: list[hint.NDArray] | None = None

The list of raw dead pixel maps added to the detector to derive the simulated dead pixel map. If None, we assume no dead pixels at all.

raw_efficiency_function: hint.Callable[[hint.NDArray], hint.NDArray] | None = None

The added efficiency function of the detector. This is the function which determines the efficiency of the detector at a provided wavelength. If not provided, this is None, and we default to a perfect, 1, efficiency function.

raw_flat_frames: list[hint.NDArray] | None = None

The list of flat frames added to the detector to derive simulated flat values from. If None, should no flat frames be provided, we default to a unity flat frame for calculations. The flat is unit-less, as an efficiency factor.

raw_hot_pixel_maps: list[hint.NDArray] | None = None

The list of raw hot pixel maps added to the detector to derive the simulated hot pixel map. If None, we assume no hot pixels at all.

raw_linearity_function: hint.Callable[[hint.NDArray], hint.NDArray] | None = None

The added linearity of the detector. If not provided, this is None, and we default to a linear linearity function.

read_noise: float = 0

The read noise of the detector’s pixels. If not otherwise provided, we default to a zero read noise detector.

read_noise_stddev: float = 0

The standard deviation of the read noise of the detector’s pixels. If not otherwise provided, we default to a zero read noise detector (thus the standard deviation is also zero).

recalculate_detector() → None

Recalculate the detector frames from the input raw frames.

Typically, only the average frame data is needed. However, we do not want to always recalculate the average frame data from the raw data every time. It would take too much time and it would also not allow any overwrites. So, we do it here.

Parameters:

None

Return type:

None

simulate_bias_frame() → hint.NDArray

Generate a new simulated bias frame.

Parameters:

None

Returns:

bias_frame – The simulated bias frame.

Return type:

NDArray

simulate_cosmic_ray_frame(exposure_time: float) → hint.NDArray

Generate a new simulated cosmic ray frame, detailing where rays hit.

Note, cosmic rays often hit multiple pixels at once. We currently do not simulate this. The cosmic ray map is created by simulate_cosmic_ray_map(), while this function applies the cosmic ray values to this map and returns the additive component of cosmic rays to the detector frame data.

Parameters:

exposure_time (float) – The exposure time, in seconds. This is pertinent as cosmic rays are a rate and if one hit or not depends on the integration time.

Returns:

cosmic_ray_frame – The simulated cosmic ray frame based on the map.

Return type:

NDArray

simulate_cosmic_ray_map(exposure_time: float) → hint.NDArray

Generate a new simulated cosmic ray map, detailing where rays hit.

Note, cosmic rays often hit multiple pixels at once. We currently do not simulate this. The cosmic ray map is created by this function, while the simulate_cosmic_ray_frame() function applies the cosmic ray values of this map and returns the additive component of cosmic rays to the detector frame data.

Parameters:

exposure_time (float) – The exposure time, in seconds. This is pertinent as cosmic rays are a rate and if one hit or not depends on the integration time.

Returns:

cosmic_ray_map – The simulated cosmic ray map.

Return type:

NDArray

simulate_dark_current_frame() → hint.NDArray

Generate a new simulated dark current frame.

Parameters:

None

Returns:

dark_current_frame – The simulated dark current frame.

Return type:

NDArray

simulate_flat_frame() → hint.NDArray

Generate a new simulated flat frame.

Parameters:

None

Returns:

flat_frame – The simulated flat frame.

Return type:

NDArray

simulate_read_noise_frame() → hint.NDArray

Generate a new simulated read noise frame.

Parameters:

None

Returns:

read_noise_frame – The simulated read noise frame.

Return type:

NDArray