romanimpreprocess.utils.ipc_linearity

IPC and linearity utilities.

Classes

IL

IPC+Inverse linearity class.

Functions

ipc_fwd

Carries out an IPC operation on the image.

ipc_rev

Inverse IPC operation, to the given order.

correct_cube

IPC corrects a full data cube (data) in place.

_lin

Helper function to evaluate Legendre-based function.

linearity

Performs a linearity correction.

multilin

Performs a linearity correction, but with multiple groups.

invlinearity

Calculates the inverse linearity. (This is most likely to be used in simulations.)

Classes

IL

IPC+Inverse linearity class.

Functions

ipc_fwd(image, kernel[, gain])

Carries out an IPC operation on the image.

ipc_rev(image, kernel[, order, gain])

Inverse IPC operation, to the given order.

correct_cube(data, ipc_file, mylog[, gain_file])

IPC corrects a full data cube (data) in place.

_lin(z, coefs[, linextrap])

Helper function to evaluate Legendre-based function.

linearity(S, linearity_file[, origin])

Performs a linearity correction.

multilin(S, linearity_file[, origin, ...])

Performs a linearity correction, but with multiple groups.

invlinearity(Slin, linearity_file[, origin])

Calculates the inverse linearity. (This is most likely to be used in simulations.)

Module Contents

ipc_fwd(image, kernel, gain=None)[source]

Carries out an IPC operation on the image.

Parameters:

  • image (np.array) – 2D numpy array of size (ny,nx).

  • kernel (np.array) – 4D numpy array of size (3,3,ny,nx).

  • gain (np.array or None, optional) – If not None, the input gain map (in e/DN).

Returns:

output – 2D numpy array, same shape as image, IPC-convolved.

Return type:

np.array

See also

ipc_rev

Inverse function.

Notes

The output image, in psuedocode, is:

output[y,x] = sum_{dy,dx} input[y-dy,x-dx] kernel[1+dy,1+dx,y-dy,x-dx]

This function natively works in electrons, but if gain is provided then works in DN (does g^-1 K g).

ipc_rev(image, kernel, order=2, gain=None)[source]

Inverse IPC operation, to the given order.

Grows the footprint of each pixel to (2*order+1,2*order+1).

If `gain `is provided, then does g^-1 K^-1 g image instead of K^-1 image. (Equivalent: operate on DN instead of e.)

Parameters:

  • image (np.array) – 2D numpy array of size (ny,nx).

  • kernel (np.array) – 4D numpy array of size (3,3,ny,nx).

  • order (int, optional) – The order of IPC inversion; default is 2nd order (correct to next-to-next-to-neighbor pixel). Error is of order alpha**(order+1).

  • gain (np.array or None, optional) – If not None, the input gain map (in e/DN).

Returns:

output – 2D numpy array, same shape as image, IPC-convolved.

Return type:

np.array

See also

ipc_fwd

Forward function.

correct_cube(data, ipc_file, mylog, gain_file=None)[source]

IPC corrects a full data cube (data) in place.

Operates in electrons if gain_file is None or missing, but operates in DN if gain_file is provided.

Parameters:

  • data (np.array) – 3D data cube, shape (ngrp, ny, nx).

  • ipc_file (str) – Location of ASDF ipc4d calibration reference file.

  • mylog (romanimpreprocess.utils.processlog.ProcessLog) – Processing log.

  • gain_file (str or None, optional) – If not none, the ASDF gain calibration reference file.

_lin(z, coefs, linextrap=True)[source]

Helper function to evaluate Legendre-based function.

Parameters:

  • z (np.array) – Rescaled signal (modified DN), shape (ny,nx).

  • coefs (np.array) – Legendre polynomial coefficients, shape (p_order+1,ny,nx).

  • linextrap (bool, optional) – Linearly extrapolate beyond end of range? (Default = True is better behaved.)

Returns:

  • phi (np.array) – The linearized signal, `` sum_l coefs_l P_p(z)``, shape (ny,nx)

  • exflag (np.array of bool) – Extrapolated beyond |z|=1?, shape (ny,nx)

linearity(S, linearity_file, origin=(0, 0))[source]

Performs a linearity correction.

Parameters:

  • S (np.array) – 2D data array in DN_raw.

  • linearity_file (str) – ASDF file with linearity data.

  • origin ((int, int), optional) – The (x,y) position of the lower-left corner of S in the convention of the file.

Returns:

  • Slin (np.array) – 2D data array in DN_lin. Same shape as S.

  • dq (np.array of uint32) – 2D flag array. Same shape as S.

Notes

The coordinate convention is that if you have a block S that corresponds to region [128:132,256:260], then you would give origin=(256,128).

multilin(S, linearity_file, origin=(0, 0), do_not_flag_first=True, attempt_corr=None)[source]

Performs a linearity correction, but with multiple groups.

Parameters:

  • S (np.array) – Input data as a 3D numpy array, shape (ngrp, ny, nx).

  • linearity_file (str) – ASDF calibration reference file with linearity data.

  • origin ((int, int), optional) – The (x,y) position of the lower-left corner of S in the convention of the file.

  • do_not_flag_first (bool, optional) – Don’t flag the first read if it is out of range (True by default for reset-read frames that we won’t use anyway).

  • attempt_corr (np.array of bool, optional) – If provided, an array of the same shape as S that is True if we want to try the correction and False otherwise (the idea is that we want to be able to not flag a pixel that is saturated). Default is to attempt to correct everything.

Returns:

  • Slin (np.array) – Linearized data, shape (ngrp,ny,nx), in DN_lin.

  • dq (np.array of uint32) – Flag array (2D).

Notes

The coordinate convention is that if you have a block S that corresponds to region [128:132,256:260], then you would give origin=(256,128). This is in 2D, so origin has only 2 entries (no offset is given on the time axis).

Slin=0 corresponding to the bias level Sref in the calibration reference file.

invlinearity(Slin, linearity_file, origin=(0, 0))[source]

Calculates the inverse linearity. (This is most likely to be used in simulations.)

Parameters:

  • Slin (np.array) – 2D input data, shape (ny,nx), in DN_lin.

  • linearity_file (str) – ASDF calibration reference file with linearity data.

  • origin ((int, int), optional) – The (x,y) position of the lower-left corner of S in the convention of the calibration file.

Returns:

  • S (np.array) – 2D array, same shape as Slin, in DN_raw.

  • exflag (np.array of bool) – Extrapolation flag.

Notes

This function works by bisection. It is the slowest step in the simulation -> Level 1 workflow, so we plan to implement a more advanced algorithm in the future.

class IL(linearity_file, gain_file, ipc_file, start_e=0.0)[source]

IPC+Inverse linearity class.

This exists to wrap the IPC and inverse-linearity operations in a way that is consistent with romanisim.

Parameters:

  • linearity_file (str) – The ASDF linearity calibration reference file.

  • gain_file (str) – The ASDF gain calibration reference file.

  • ipc_file (str or None) – The ASDF ipc4d calibration reference file. If None, skips the IPC.

  • start_e (np.array or float, optional) – If provided, starts with some number of electrons (start_e, number or array) in the well. Useful for reset noise.

__init__()[source]

Constructor

set_dq()[source]

Sets the 3D data quality flags.

apply()[source]

Converts a linearized signal to a non-linear, IPC-convolved signal.

linearity_file[source]
gain_file[source]
ipc_file[source]
start_e = 0.0[source]
set_dq(ngroup=1, nborder=4)[source]

Sets the 3D data quality flags.

This is so that the data quality flags can be propagated.

Parameters:

  • ngroup (int, optional) – Number of groups to initialize.

  • nborder (int, optional) – Number of border reference pixels.

Return type:

None

apply(counts, electrons=False, electrons_out=False)[source]

Converts a linearized signal to a non-linear signal.

Parameters:

  • counts (np.array) – 2D array of counts.

  • electrons (bool, optional) – Is input in electrons (True) or DN_lin (False, default).

  • electrons_out (bool, optional) – Is output in electrons (True) or DN_raw (False, default).