liger_iris_sim.utr.create_ramp

Functions

`compute_channel_psds`(cube[, n_channels, ...])	Compute one power spectral density (PSD) per readout channel from a 3D up-the-ramp datacube by flattening each channel into a 1D readout-ordered time series.
`compute_psd`(x[, dt, detrend, onesided])	Compute the power spectral density (PSD) of a time series using an FFT periodogram.
`create_ramp`(source[, readtime, n_reads, ...])	Simulate a detector up-the-ramp (UTR) readout sequence for a given source image.
`generate_1overf_noise`(n[, dt, std, seed, ...])	Generate a 1/f (pink) noise time series using frequency-domain synthesis.
`generate_1overf_noise_integrated`(n[, dt, ...])	Generate a 1/f (pink) noise time series sampled at dt and convolved with a top-hat (boxcar) kernel of width `readtime` to emulate finite integration time.
`generate_1overf_noise_map`(shape_3d[, ...])	Generate a 3D array of 1/f (pink) noise assuming same noise in each readout channel.
`utr_variable_rate_cube`(source, flux_scaling, ...)	Build a (n_reads-1, ny, nx) cube of per-read average electron rates for a time-variable UTR ramp, conserving total flux.

compute_channel_psds(cube, n_channels=1, vertical=True, clock_rate=1.0, detrend=False, onesided=True)[source]

Compute one power spectral density (PSD) per readout channel from a 3D up-the-ramp datacube by flattening each channel into a 1D readout-ordered time series.

This implementation effectively assumes that no signal is present in the data other than noise.

For each readout channel, the data are reshaped into a single 1D array using NumPy’s default (C-order) memory layout, such that the ordering of samples matches the implicit readout order used when generating channel- correlated 1/f noise. The PSD of this 1D sequence is then computed using compute_psd.

Parameters:

cube (ndarray, shape (n_reads, ny, nx)) – Up-the-ramp datacube.
n_channels (int, optional) – Number of detector readout channels. The detector dimension corresponding to the channel direction must be divisible by n_channels.
vertical (bool, optional) – If True, channels are assumed to be vertical stripes along the x dimension. If False, channels are assumed to be horizontal stripes along the y dimension.
clock_rate (float, optional) – Clock rate in Hz (samples per second).
detrend (bool, optional) – If True, subtract the mean of each channel time series before computing the PSD.
onesided (bool, optional) – If True, compute a one-sided PSD appropriate for real-valued data.

Returns:

freqs (ndarray) – Fourier frequency grid corresponding to the PSD.
psd_channels (ndarray, shape (n_channels, n_freq)) – Power spectral density for each readout channel, computed from the flattened channel data.

compute_psd(x, dt=1.0, detrend=False, onesided=True)[source]

Compute the power spectral density (PSD) of a time series using an FFT periodogram.

Notes: generated from ChatGPT

Parameters:

x (array_like, shape (n,)) – Input time series.
dt (float, optional) – Time sampling interval.
detrend (bool, optional) – If True, subtract the mean before computing the PSD.
onesided (bool, optional) – If True, return the one-sided PSD (recommended for real signals).

Returns:

freqs (ndarray) – Fourier frequencies.
psd (ndarray) – Power spectral density corresponding to freqs.

create_ramp(source: ndarray, readtime: float = 1.7, n_reads: int = 10, gain: ndarray | float = 1.0, flat: ndarray | None = None, bias: ndarray | float = 1000, dark: ndarray | float = 0, read_noise: float | None = 3, kTC_noise: float | None = 50, nonlin_coeffs: ndarray | None = None, poisson_noise: bool = True, mjd_start: float = 60577.0, convert_to_uint16: bool = True, clip_ramps: bool = True, max_cores: int = 1, block_size: int | None = None, std_1overf: float | None = None, n_channels: int | None = None, vertical: bool = True, flux_scaling: ndarray | None = None, flux_scaling_times: ndarray | None = None) → dict[str, ndarray][source]

Simulate a detector up-the-ramp (UTR) readout sequence for a given source image.

Parameters:

source (np.ndarray) – 2D array of source signal (e-/s/pixel) including all sources.
readtime (float) – Time between reads (seconds).
n_reads (int) – Number of reads in the ramp sequence (default: 10).
gain (None or float or np.ndarray) – Gain of the detector (e-/ADU).
flat (None or float or np.ndarray, optional) – Flat field array (default: None). We assume that flats have been corrected for gain variations already. In this function the gain is applied after the flat, but in the data reduction pipeline the gain correction should be applied first.
bias (None or float or np.ndarray, optional) – Bias level to add to the first read (default: 1000 e-).
dark (None or flat or np.ndarray, optional) – Dark current level to add to each read (e-/s/pixel) (default: 0) The flat field is applied BEFORE adding the dark current. This is because dark subtraction is typically done before the flat fielding step.
read_noise (None or float or np.ndarray, optional) – Standard deviation of read noise (e-) for each read (default: 3 e-).
kTC_noise (None or float or np.ndarray, optional) – kTC noise parameter (e-) to add to the first read (default: 50 e-).
nonlin_coeffs (np.ndarray or None, optional) – Nonlinearity correction coefficients (default: None). Applies as data = np.polyval(nonlin_coeffs, data).
poisson_noise (bool, optional) – If True, apply Poisson noise to the signal (default: True).
mjd_start (float, optional) – Modified Julian Date for the start time (default: 60577.0).
convert_to_uint16 (bool, optional) – If True, round and convert the output data to np.uint16 (default: True).
clip_ramps (bool, optional) – If True, clip_ramps the output data to the range of np.uint16 (0 to 65535) (default: True).
max_cores (int, optional) – Maximum number of CPU cores to use for parallel processing (default: 1).
block_size (int or None, optional) – Number of rows to process in each block when using multiple cores (default: None).
std_1overf (float or None, optional) – Standard deviation of 1/f noise in ADU (ie, DN). If None, 1/f noise is not added (default: None).
n_channels (n_channels,) – Number of readout channels. If None, assume 1 channel (default: None).
vertical (bool, optional) – If True, channels are vertical; if False, channels are horizontal (default: True).
flux_scaling (np.ndarray or None, optional) – Timeseries of flux to model variability centered on unity (default: None). Should match length of flux_scaling_times.
flux_scaling_times (np.ndarray or None, optional) – Times corresponding to flux_scaling array (seconds) (default: None).

Returns:

dict[str, np.ndarray] –

Dictionary containing:

‘times’: astropy.table.Table of read numbers, times, and exptimes
‘data’: 3D array (n_reads, ny, nx) of ramp data
‘dq’: 3D array (n_reads, ny, nx) of data quality flags

Raises:

ValueError – If any value in the output ‘data’ array is negative.

generate_1overf_noise(n, dt=1.0, std=1.0, seed=None, return_time=False)[source]

Generate a 1/f (pink) noise time series using frequency-domain synthesis.

Notes

Generated from ChatGPT.

Parameters:

n (int) – Number of samples in the time series.
dt (float, optional) – Time sampling interval.
std (float, optional) – Desired standard deviation of the output time series.
seed (int or None, optional) – Random seed for reproducibility.
return_time (bool, optional) – If True, also return the time sampling vector.

Returns:

noise (ndarray, shape (n,)) – Real-valued 1/f noise time series.
t (ndarray, shape (n,), optional) – Time sampling vector (returned if return_time=True).

generate_1overf_noise_integrated(n, dt=1.0, readtime=1.0, std=1.0, seed=None, return_time=False, mode='same')[source]

Generate a 1/f (pink) noise time series sampled at dt and convolved with a top-hat (boxcar) kernel of width readtime to emulate finite integration time.

Conceptually, this produces a time-averaged version of the underlying 1/f noise: y(t) = (1/readtime) Integral_{t-readtime/2}^{t+readtime/2} x(u) du when using a centered boxcar and mode="same".

Notes

Generated from ChatGPT.

Parameters:

n (int) – Number of samples in the output time series (sampled at dt).
dt (float, optional) – Time sampling interval of the generated series. Should satisfy dt << readtime for a good approximation of continuous-time integration.
readtime (float, optional) – Integration time (width of the top-hat) in the same time units as dt.
std (float, optional) – Desired standard deviation of the final (convolved) output time series.
seed (int or None, optional) – Random seed for reproducibility.
return_time (bool, optional) – If True, also return the time sampling vector.
mode ({"same","full","valid"}, optional) – Convolution mode passed to np.convolve. Default “same” returns length n.

Returns:

noise_int (ndarray) – The convolved (time-averaged) 1/f noise series. Length depends on mode (“same” -> n).
t (ndarray, optional) – Time vector corresponding to the returned samples (returned if return_time=True).

Notes

The top-hat kernel is normalized (sum=1), so it implements a moving average over approximately readtime.
The output is normalized to have standard deviation std after convolution.
Edge behavior depends on mode. For “same”, the result uses the implicit zero-padding behavior of np.convolve; if you want different boundary handling (reflect/nearest), you can pad manually before convolution.

generate_1overf_noise_map(shape_3d, n_channels=1, vertical=True, clock_rate=1.0, std_1overf=1.0, seed=None)[source]

Generate a 3D array of 1/f (pink) noise assuming same noise in each readout channel.

Parameters:

shape_3d (tuple of int) – Shape of the output array (n_reads, ny, nx).
n_channels (int, optional) – Number of readout channels (default: 1).
vertical (bool, optional) – If True, channels are vertical; if False, channels are horizontal.
clock_rate (float, optional) – Clock rate in Hz (samples per second).
std_1overf (float, optional) – Desired standard deviation of the output time series.
seed (int or None, optional) – Random seed for reproducibility.

Returns:

ndarray – 3D array of shape (n_reads, ny, nx) containing 1/f noise with the same noise pattern in each readout channel.

utr_variable_rate_cube(source: ndarray, flux_scaling: ndarray, flux_scaling_times: ndarray, n_reads: int, readtime: float, t0: float = 0.0)[source]

Build a (n_reads-1, ny, nx) cube of per-read average electron rates for a time-variable UTR ramp, conserving total flux.

Parameters:

source (ndarray, shape (ny, nx)) – Average electron rate map (e-/s), averaged over the full exposure.
flux_scaling (ndarray, shape (nt,)) – Dimensionless flux scaling vs time (mean ~ 1).
flux_scaling_times (ndarray, shape (nt,)) – Time samples in seconds (assumed monotonic).
n_reads (int) – Total number of reads (including the first zero-count read).
readtime (float) – Time between reads in seconds.
t0 (float, optional) – Start time of the ramp.

Returns:

rate_cube (ndarray, shape (n_reads-1, ny, nx)) – Average e-/s rate map for each read interval.
scaling_mean_per_read (ndarray, shape (n_reads-1,)) – Mean flux scaling applied during each interval.