vis133m.py API

bh_molecule.instruments.vis133m

Classes

FCPShape

Bases: NamedTuple

Attributes

C: int instance-attribute

F: int instance-attribute

P: int instance-attribute

Vis133M

Minimal loader/processor for VIS-1.33 m data with per-channel wavecal.

This class wraps a FITS data cube produced by the VIS-1.33 m instrument and a per-channel wavelength calibration CSV. It provides convenient accessors and plotting helpers for frames, channels and pixels, plus simple dark subtraction and time-axis helpers.

Parameters:

Name	Type	Description	Default
fits_path	str	Path to a FITS file containing a 3D data cube with shape (F, C, P) (frames, channels, pixels).	required
wavecal_csv	str	Path to a CSV file containing per-channel wavelength calibration. The first column must contain channel indices (0-based preferred, 1-based accepted). Remaining columns are interpreted as wavelength values [nm] for each pixel.	required
scale	float	Multiplicative scale factor applied to the cube data (default 1.0).	1.0

Attributes:

Name	Type	Description
cube	ndarray	The data cube of shape (F, C, P).
wl_nm	ndarray	Per-channel wavelength array with shape (C, P) in nanometres.
header	dict	FITS header converted to a dict.
exptime	float | None	Exposure time read from the FITS header when available.
time_s	ndarray | None	Optional time vector in seconds of length F. If unset, frame indices are used for plotting/time axes.

Attributes

axis_legend: dict[str, str] property

Mapping of axis short names to human-readable descriptions.

Returns:

Type	Description
dict	Mapping with keys 'F', 'C', 'P' describing the axes.

cube = cube instance-attribute

exptime = self.header.get('EXPTIME') or self.header.get('EXPOSURE') instance-attribute

filename = fits_path instance-attribute

header = dict(hdu.header) instance-attribute

scale = float(scale) instance-attribute

shape property

Return the shape of the internal data cube.

Returns:

Type	Description
tuple	Shape (F, C, P) where F is frames, C is channels and P is pixels (wavelength samples).

shape_fcp: FCPShape property

Named shape with axis meanings.

Returns:

Type	Description
FCPShape	Named tuple containing F, C and P describing the number of frames, channels and pixels respectively.

time_s = None instance-attribute

wl_nm = wl instance-attribute

Functions

band(nm_range: tuple[float, float], subtract_dark: bool = True) -> np.ndarray

Sum signal within a wavelength band (per-channel) returning an image of shape (F, C).

Parameters:

Name	Type	Description	Default
nm_range	tuple of float	(lo, hi) wavelength range in nanometres (inclusive).	required
subtract_dark	bool	If True and a dark is configured via set_dark, subtract the dark from the resulting image (default True).	True

Returns:

Type	Description
ndarray	Summed image of shape (F, C) in the same units as the cube multiplied by the current scale.

channel_stack(channel: int, *, zero_min: bool | None = None) -> np.ndarray

Return the time×pixel stack for a single channel.

Parameters:

Name	Type	Description	Default
channel	int	Channel index (0-based).	required

Returns:

Type	Description
ndarray	Array of shape (F, P) containing the stack for the channel.

explain() -> None

Print a short human-readable description of the data axes.

This helper is convenient in interactive sessions or notebooks.

frame_image(frame: int, *, zero_min: bool | None = None) -> np.ndarray

Return the channel×pixel image for a single frame.

Parameters:

Name	Type	Description	Default
frame	int	Frame index (0-based).	required

Returns:

Type	Description
ndarray	Array of shape (C, P) corresponding to the requested frame.

map_band(nm_range: tuple[float, float], *, subtract_dark: bool = True) -> np.ndarray

Sum signal within a wavelength band (per-channel) returning (F, C).

Parameters:

Name	Type	Description	Default
nm_range	tuple of float	(lo, hi) wavelength range in nanometres (inclusive).	required
subtract_dark	bool	If True subtract a configured dark (default True).	True

Returns:

Type	Description
ndarray	Summed image of shape (F, C).

map_pixel_range(start: int, stop: int, *, subtract_dark: bool = True) -> np.ndarray

Sum over a pixel window returning an (F, C) image.

Parameters:

Name	Type	Description	Default
start	int	Start pixel index (inclusive).	required
stop	int	Stop pixel index (exclusive).	required
subtract_dark	bool	If True subtract a configured dark (default True).	True

Returns:

Type	Description
ndarray	Summed image of shape (F, C).

pixel_map(pixel: int) -> np.ndarray

Return the frame×channel map at a fixed detector pixel.

Parameters:

Name	Type	Description	Default
pixel	int	Pixel index (0-based).	required

Returns:

Type	Description
ndarray	Array of shape (F, C) containing values at the given pixel.

plot_band_map(nm_range: tuple[float, float], *, ax=None, cmap=None, cbar_label='intensity', channel_line: int | None = None, require_time: bool = False, subtract_dark: bool = True, log_scale: bool = False, vmin: float | None = None, vmax: float | None = None)

Plot the result of map_band(nm_range).

Parameters:

Name	Type	Description	Default
nm_range	tuple of float	(lo, hi) wavelength range in nanometres.	required

Returns:

Type	Description
Axes	The axes containing the image.
See Also map_band, _plot_fc

plot_channel_stack(channel: int, *, ax=None, cmap=None, cbar_label='intensity', time_line: float | None = None, require_time: bool = False, log_scale: bool = False, vmin: float | None = None, vmax: float | None = None)

Plot a channel stack (time × wavelength) as an image.

Parameters:

Name	Type	Description	Default
channel	int	Channel index (0-based) to plot.	required
ax	Axes | None	Axes to plot into. If None the current axes are used.	None
cmap	str | Colormap | None	Colormap to use for the image.	None
cbar_label	str	Label for the colorbar (default "intensity").	'intensity'
time_line	float | None	Optional vertical line (x coordinate in time units) to indicate a time-of-interest.	None
require_time	bool	If True require an explicit time vector (raise if unset).	False

Returns:

Type	Description
Axes	The axes containing the image.

plot_pixel_map(pixel: int, *, ax=None, cmap=None, cbar_label='intensity', channel_line: int | None = None, require_time: bool = False, log_scale: bool = False, vmin: float | None = None, vmax: float | None = None)

Plot a frame×channel image for a fixed pixel index.

Parameters:

Name	Type	Description	Default
pixel	int	Pixel index (0-based).	required
ax	Axes | None	Axes to plot into. If None the current axes are used.	None
cmap	str | Colormap | None	Colormap to use for the image.	None
cbar_label	str	Label for the colorbar (default "intensity").	'intensity'
channel_line	int | None	Optional horizontal line indicating a channel of interest.	None
require_time	bool	If True require an explicit time vector (raise if unset).	False

Returns:

Type	Description
Axes	The axes containing the image.

plot_pixel_range(start: int, stop: int, *, ax=None, cmap=None, cbar_label='intensity', channel_line: int | None = None, require_time: bool = False, subtract_dark: bool = True, log_scale: bool = False, vmin: float | None = None, vmax: float | None = None)

Plot the result of map_pixel_range(start, stop).

Parameters:

Name	Type	Description	Default
start	int	Start pixel index (inclusive).	required
stop	int	Stop pixel index (exclusive).	required

Returns:

Type	Description
Axes	The axes containing the image.

plot_spectrum(frame: int, channel: int, ax=None, *, zero_min: bool | None = None)

Plot the spectrum at a given frame and channel using Matplotlib.

Parameters:

Name	Type	Description	Default
frame	int	Frame index (0-based).	required
channel	int	Channel index (0-based).	required
ax	Axes | None	Axes to plot into. If None the current axes are used.	None

Returns:

Type	Description
Axes	The axes containing the plot.

plot_spectrum_plotly(frame: int, channel: int, *, sort_wavelength: bool = True, line_shape: str = 'linear', zero_min: bool | None = None, theme: str | None = None, bg: str = '#44423e', fg: str = '#eaeaea')

Return an interactive Plotly figure for a spectrum.

Parameters:

Name	Type	Description	Default
frame	int	Frame index (0-based).	required
channel	int	Channel index (0-based).	required
sort_wavelength	bool	If True, sort the wavelength vector to be monotonic for better interactive behaviour (default True).	True
line_shape	str	Plotly line shape (e.g. 'linear', 'spline').	'linear'
theme	(dark, light, None)	If "dark", apply a dark layout to the figure. If None, inherit Plotly's default.	"dark","light",None
bg	str	Background color for dark theme.	'#44423e'
fg	str	Foreground color for dark theme.	'#eaeaea'

Returns:

Type	Description
Figure	Interactive figure containing the spectrum.

Raises:

Type	Description
ImportError	If Plotly is not available.

Example

fig = s26.plot_spectrum_plotly(38, 36) fig.show()

set_baseline_zero(enable: bool = True) -> None

Enable/disable per-spectrum minimum subtraction.

When enabled, each spectrum row (across pixels) will be shifted so its minimum is zero in methods that return spectra-like arrays.

Parameters:

Name	Type	Description	Default
enable	bool	If True, subtract per-row minima from spectra results. If False, disable this behaviour.	True

set_dark(*, frame: int | None = None, channel: int | None = None, vector=None, value: float | None = None)

Configure dark subtraction behaviour.

Dark can be specified in several ways: - vector: an array-like that will be used directly as the dark correction (broadcasting rules apply). - value: a scalar dark value subtracted from all pixels. - frame and channel: record a reference index; subtraction will subtract the value found at that (frame, channel) location when applied.

Parameters:

Name	Type	Description	Default
frame	int | None	Frame index used for index-based dark (with channel).	None
channel	int | None	Channel index used for index-based dark (with frame).	None
vector	array - like | None	Direct dark vector/array to use for subtraction.	None
value	float | None	Scalar dark value to subtract.	None

set_scale(scale: float)

Set the global multiplicative scale applied to the cube.

Parameters:

Name	Type	Description	Default
scale	float	New scale factor.	required

set_time(t)

Set an explicit time vector for the frames.

Parameters:

Name	Type	Description	Default
t	array - like	Time vector (seconds) of length F where F is the number of frames in the cube. Must be non-decreasing and contain finite values.	required

Raises:

Type	Description
ValueError	If the vector length does not match F, contains non-finite values, or is not non-decreasing.

set_time_linspace(start_s: float, stop_s: float)

Set time_s to a linearly spaced vector between two times.

Parameters:

Name	Type	Description	Default
start_s	float	Start time in seconds.	required
stop_s	float	Stop time in seconds.	required

set_time_period(period_s: float, start_s: float = 0.0)

Set time_s assuming a constant frame period.

Parameters:

Name	Type	Description	Default
period_s	float	Time between successive frames in seconds.	required
start_s	float	Time of the first frame (default 0.0 s).	0.0

spectrum(frame: int, channel: int, *, zero_min: bool | None = None) -> tuple[np.ndarray, np.ndarray]

Return wavelength and signal arrays for a given (frame, channel).

Parameters:

Name	Type	Description	Default
frame	int	Frame index (0-based).	required
channel	int	Channel index (0-based).	required

Returns:

Type	Description
tuple of ndarray	(wavelengths, signal) where both arrays have shape (P,) and wavelengths are in nanometres. signal is scaled by the current scale attribute.

Raises:

Type	Description
IndexError	If frame or channel are out of range.

A short API reference for the Vis133M loader/processor.