Data utilities (cassini_upyp.uvisutils)#

This module contains the main data utilities to load and process Cassini/UVIS PDS3 products used in cassini_upyp.uvisdata module.

Uncertainty utilities#

cassini_upyp.uvisutils.poisson_error(x, bound, sigma=1.0)#

Return one Garwood bound (lower/upper) for Poisson counts.

Parameters:

  • x (int or array-like) – Observed counts (must be >= 0, finite).

  • bound ({"inf", "sup", "lower", "upper"}) – Which bound to return. Aliases: “lower”->”inf”, “upper”->”sup”.

  • sigma (float, optional) – Two-sided Gaussian-equivalent level for the central interval (default: 1.0).

Returns:

Requested bound with the same shape as x (float if scalar input).

Return type:

float or np.ndarray

Notes

Uses the Garwood (chi-square) construction:

U = 0.5 * chi2.ppf(1 - alpha/2, 2*(x+1))

L = 0.5 * chi2.ppf(alpha/2, 2*x) (with L=0 for x=0)

where alpha = 1 - (Phi(sigma) - Phi(-sigma)).

cassini_upyp.uvisutils.correction_factor(N, log=True)#

Return the bias-correction factor κ(N) for the sample standard deviation.

For N Gaussian samples, the usual sample standard deviation s (with denominator N - 1) underestimates the true σ. This function returns κ(N) such that κ(N) * s is an unbiased estimator of σ under the Gaussian assumption. As N → ∞, κ(N) → 1.

Parameters:

  • N (int or array-like of int) – Sample size(s), expected to be ≥ 2.

  • log (bool, optional) – If True (default), use the log-gamma function for numerical stability, especially for large values of N. If False, use the regular gamma.

Returns:

The correction factor κ(N), with the same shape as N. Returns a float if N is scalar.

Return type:

float or numpy.ndarray

Calibration utilities and I/O routines#

cassini_upyp.uvisutils.uvis_lab_calibration(channel, filename=None)#

Read laboratory calibration data for the specified UVIS channel and return sensitivity information.

The file contains the full-slit, low-resolution monochromatic extended-source sensitivity measured in the laboratory (1997, updated 1999), in units of (counts s-1) / (kilorayleigh).

Parameters:

  • channel ({"FUV", "EUV"}) – The UVIS channel for which to read the calibration data.

  • filename (str or pathlib.Path, optional) – Path to the calibration data file. If None (default), the file name is constructed as “{channel}_1999_Lab_Cal.dat” and looked up in the default calibration files directory.

Returns:

A dictionary with three 1D arrays: - “WAVELENGTH” : wavelength grid (Å), - “SENSITIVITY” : sensitivity (counts s⁻¹ / kR), - “SENSITIVITY_ERROR” : uncertainty on the sensitivity.

Return type:

dict of str -> numpy.ndarray

cassini_upyp.uvisutils.get_cal_time_variation(channel, sctime)#

Retrieve the spectral modulation array for a given UVIS channel and spacecraft time.

This function reads calibration trending data from the IDL ‘uvis_calibration_trending_v01_data.sav’ computed from IDL routine uvis_calibration_trending_v01.pro and computes the spectral modulation for the specified UVIS channel at a given spacecraft time (sctime).

The spectral modulation is interpolated linearly in time between the two closest calibration epochs.

Parameters:

  • channel ({"FUV", "EUV"}) – The UVIS channel for which to get the calibration time variation.

  • sctime (float) – The spacecraft time in seconds for which to compute the spectral modulation.

Returns:

Spectral modulation array of length 1024 for the requested channel and sctime.

Return type:

numpy.ndarray

Notes

  • The calibration trending data is read from ‘calibration_files/uvis_calibration_trending_v01_data.sav’.

  • If sctime is earlier than the first calibration time, an array of ones is returned.

  • If sctime is later than the last calibration time, the last available modulation ratio is used.

  • Between two calibration times, the modulation is interpolated linearly in time.

cassini_upyp.uvisutils.get_ff_time_variation(channel, sctime)#

Retrieve the flat-field (FF) time variation array for a given UVIS channel and spacecraft time.

This function loads flat-field modifier data files corresponding to different spacecraft times and computes the flat-field modifier array for the specified channel at the given spacecraft time (sctime). It interpolates between the two closest calibration times to compute the flat-field modifier array.

Parameters:

  • channel ({"FUV", "EUV"}) – The UVIS channel for which to get the calibration time variation. ‘FUV’ or ‘EUV’.

  • sctime (float) – The spacecraft time in seconds for which to compute the flat-field modifier.

Returns:

A NumPy array of shape (64, 1024) containing the flat-field modifier values, dtype float32.

Return type:

numpy.ndarray

Notes

  • Files are searched with the pattern f"*{channel}*ff_modifier*.dat" inside the calibration files directory.

  • Spacecraft times are extracted from the last 10 characters of the file name and interpreted as integers.

  • If sctime is earlier than the first available time, an array of ones is returned.

  • If sctime is later than the last available time, the modifier from the last available file is returned.

  • For times strictly within the calibration range, the modifier is obtained by linear interpolation between the two nearest files in time; in this case, the 62nd row is explicitly set to one (arrmod[61, :] = 1).

Raises:

FileNotFoundError – If no flat-field modifier files are found for the specified channel.

cassini_upyp.uvisutils.read_spica_ff(filename)#

Read a SPICA flat-field calibration file.

This reads flat-field maps derived from SPICA observations used to correct the UVIS detector after the starburn event, e.g. FLATFIELD_XUV_PREBURN.txt or FLATFIELD_XUV_POSTBURN.txt.

Parameters:

filename (str or pathlib.Path) – Path to the flat-field file.

Returns:

Flat-field array of shape (64, 1024), dtype float.

Return type:

numpy.ndarray

Data binning#

cassini_upyp.uvisutils.list_ndarray(shape)#

Create a NumPy array (dtype=object) where each cell is initialized as an independant empty list.

Parameters:

shape (tuple of int) – The shape of the array to create.

Returns:

A NumPy array of the specified shape where each cell is an empty Python list.

Return type:

np.ndarray

Examples

Create a 2D array of lists for two properties:

>>> from cassini_upyp.utils import list_ndarray
>>> shape = (3, 2)
>>> bins = list_ndarray(shape)
>>> bins.shape
(3, 2)

Append data points to a given bin:

>>> bins[0, 0].append(42.0)
>>> bins[0, 0]
[42.0]
cassini_upyp.uvisutils.find_bin_index(value, boundaries, mode='center', modulo=None)#

Determine the bin index for a given valueerty value (or array of values) relative to the provided boundaries.

In ‘center’ mode, ‘value’ is expected to be a scalar value. In ‘all’ mode, ‘value’ is expected to be an array; all values must fall within the same bin.

The binning convention is half-open: [edges[i], edges[i+1]), so the last edge is excluded.

Parameters:

  • value (scalar or array-like) – The valueerty value(s) for which to determine the bin index.

  • boundaries (sequence of float) – A sorted list of bin edges.

  • mode ({"center", "all"}, optional) – The mode of operation: - ‘center’: use a single representative value. - ‘all’: require that all values in the pixel fall within the same bin. Default is “center”.

  • modulo (float, optional) – If provided, a lower boundary that is higher than the upper boundary will be considered valid, and the binning will be treated as cyclic with the given period. For example, a boudary of [350, 10] with modulo=360 would mean that values in [350, 360) and [0, 10) belong to the same bin.

Returns:

The bin index if valid; otherwise, None.

Return type:

int or None