UVIS_Bin#

Container class holding the result of a pixel binning operation. UVIS_Bin relies on the list_ndarray structure generated by the cassini_upyp.uvisutils.list_ndarray() function, which is used to store the indices of the pixels that belong to each bin.

class cassini_upyp.uvisdata.UVIS_Bin(shape, uvis_obs)#

Bases: object

Container holding the result of a pixel binning operation.

A UVIS_Bin instance stores:

  • the mapping between detector pixels and bins,

  • per-bin population statistics,

  • optional bin definitions (e.g., geometric boundaries),

  • per-bin geometric line-of-sight (LOS) properties,

  • references to the original unbinned observation arrays.

The class is agnostic to how bins are constructed: bins may result from automatic geometric binning or explicit manual pixel grouping.

Parameters:

  • shape (tuple of int) – Shape of the bin grid. Each element corresponds to the number of bins along one binning dimension. For manual binning this is typically (n_bins,).

  • uvis_obs (UVIS_Observation) – Parent observation providing the unbinned data arrays and geometry.

average()#

Compute per-bin mean spectra and uncertainties.

For each bin, this method computes [1]:

  • an unweighted mean spectrum, sample standard deviation (ddof=1), and corrected standard error of the mean,

  • a weighted mean spectrum using 1/σ² weights, where σ is the symmetric uncertainty (0.5*(sup+inf)),

  • propagated upper and lower uncertainties for the weighted mean for each wavelength.

Empty bins are left as NaN. Results are stored as attributes and self.bin_averaged is set to True.

Return type:

None

Variables:

  • bin_mean_spectrum (ndarray) – Unweighted mean spectrum per bin.

  • bin_stddev_spectrum (ndarray) – Unweighted standard deviation per bin.

  • bin_stderr_spectrum (ndarray) – Unweighted standard error per bin (with small-sample correction).

  • bin_wmean_spectrum (ndarray) – Weighted mean spectrum per bin.

  • bin_u_sup_spectrum (ndarray) – Propagated upper uncertainty of weighted mean per bin.

  • bin_u_inf_spectrum (ndarray) – Propagated lower uncertainty of weighted mean per bin.

References

[1] Le Guennic et al. (2026)

integrate(wl_range=None, uncertainty=True, method='simpson')#

Integrate spectra over a wavelength band and compute per-bin integrated products.

This method performs three integration tasks:

  • Integrates the raw pixel-level spectra and uncertainties [1].

  • Averages these integrated values within each bin.

  • If bins have already been averaged (via average()), also integrates the bin-averaged spectra.

Parameters:

  • wl_range (tuple of float, optional) – Integration bounds (min_wl, max_wl).

  • uncertainty (bool, optional) – If True (default), uncertainty spectra are propagated under the integral (see integrate_spectrum()).

  • method ({"simpson", "trapezoid", "trapz"}, optional) – Numerical integration method passed to integrate_spectrum(). trapz is an alias for trapezoid. Default is “simpson”.

Return type:

None

Variables:

  • integrated_data (ndarray) – Integrated spectrum for each pixel.

  • integrated_uncertainty_sup (ndarray) – Integrated upper uncertainty for each pixel.

  • integrated_uncertainty_inf (ndarray) – Integrated lower uncertainty for each pixel.

  • binned_integrated_data (ndarray) – Mean of integrated spectra of each pixel per bin.

  • binned_integrated_uncertainty_sup (ndarray) – Mean of integrated upper uncertainty of each pixel per bin.

  • binned_integrated_uncertainty_inf (ndarray) – Mean of integrated lower uncertainty of each pixel per bin.

  • bin_stddev (ndarray) – Standard deviation of integrated values per bin.

  • bin_stderr (ndarray) – Standard error of integrated values per bin.

  • integrated_avrg_data (ndarray) – Integration of unweighted bin-averaged spectra.

  • integrated_avrg_data_w (ndarray) – Integration of weighted bin-averaged spectra.

  • integrated_avrg_stddev (ndarray) – Integration of bin standard deviation spectrum.

  • integrated_avrg_stderr (ndarray) – Integration of bin standard error spectrum.

  • integrated_avrg_uncertainty_sup (ndarray) – Integration of bin upper uncertainty spectra.

  • integrated_avrg_uncertainty_inf (ndarray) – Integration of bin lower uncertainty spectra.

References

[1] Le Guennic et al. (2026)

plot_bin(show=True)#

Display a table visualization of the number of pixels per bin.

Creates a matplotlib table showing bin centers as row/column labels and the count of pixels in each bin as cell values. Empty bins are displayed as blank cells.

Parameters:

show (bool, optional) – If True (default), call plt.show(). The figure and axes are still returned.

Returns:

  • fig (matplotlib.figure.Figure) – The created figure.

  • ax (matplotlib.axes.Axes) – The created axes.

Raises:

ValueError – If the bin grid is not 2D.

Notes

  • Only works for 2D bin grids.

  • Bin centers are computed as midpoints of bin edges.

save(filepath, overwrite=False)#

Save the UVIS_Bin object to disk.

The file extension is set to “.uvisbin” if not provided.

Parameters:

  • filepath (str or Path) – Output path. If no “.uvisbin” suffix is provided, it is appended.

  • overwrite (bool, optional) – If True, existing files are overwritten without prompting. If False (default), the user is asked for confirmation.

Returns:

The original filepath argument.

Return type:

str or Path

Notes

The method uses the pickle module.

classmethod load(filepath)#

Load a UVIS_Bin object from a pickle file.

Parameters:

filepath (str or Path) – Path to the pickle file containing the serialized object.

Returns:

The deserialized UVIS_Bin object.

Return type:

UVIS_Bin

Raises:

  • FileNotFoundError – If the specified file does not exist.

  • pickle.UnpicklingError – If the file cannot be unpickled or is corrupted.