plotting API

bh_molecule.plotting

Functions

dark_theme(bg=_DEF_BG, fg=_DEF_FG)

export_band_maps_from_folder(folder, output_pdf, cw_nm, nm_range, pattern='*.fits', **kwargs)

Export band maps for all FITS files in a folder.

Example

export_band_maps_from_folder( folder, "bh_maps.pdf", cw_nm=431.91, nm_range=(431.0, 433.5), grid=(2, 3), )

export_band_maps_pdf(fits_files, output_pdf, cw_nm, nm_range, *, cmap=None, cbar_label='intensity', channel_line=None, require_time=False, subtract_dark=True, log_scale=False, grid=None, grid_figsize=(11, 8.5), show_axes=False, show_titles=True, title_fontsize=8, single_colorbar=True, show_spines=False, annotate=None, tight_layout=True, output_format='pdf')

Export per-file band-map plots to a multi-page PDF or PNG files.

Parameters:

Name	Type	Description	Default
fits_files	iterable	Iterable of FITS file paths.	required
output_pdf	path - like	Output PDF path.	required
cw_nm	float	Central wavelength (nm) to apply via Vis133M.apply_cw.	required
nm_range	tuple	(lo, hi) wavelength range in nanometres for Vis133M.plot_band_map.	required
cmap		Forwarded to Vis133M.plot_band_map.	None
cbar_label		Forwarded to Vis133M.plot_band_map.	None
channel_line		Forwarded to Vis133M.plot_band_map.	None
require_time		Forwarded to Vis133M.plot_band_map.	None
subtract_dark		Forwarded to Vis133M.plot_band_map.	None
log_scale		Forwarded to Vis133M.plot_band_map.	None
grid	tuple(rows, cols) | None	If set, render band maps in a contact-sheet grid; otherwise one per page.	None
grid_figsize	tuple	Figure size for grid pages.	(11, 8.5)
show_axes	bool	If False, remove xticks, yticks, xlabel, ylabel on grid subplots.	False
show_titles	bool	If True, show shot number (path.stem) as subplot title.	True
title_fontsize	int	Font size for subplot titles.	8
single_colorbar	bool	If True (default), one colorbar per page is drawn from the last subplot's image (all subplots share vmin/vmax). If False, each subplot gets its own colorbar.	True
show_spines	bool	If False, hide subplot borders (spines).	False
annotate	None | max | snr	If "max", show max intensity in the upper-left corner of each subplot.	None
tight_layout	bool	Unused for grid pages; grid uses constrained_layout=True instead.	True
output_format	(pdf, png)	If "pdf", write a single multi-page PDF. If "png", write one PNG per page (e.g. output_stem_001.png, output_stem_002.png, ...).	"pdf"

plot_grid(curves, *, nm_window, frames=None, channels=None, ncols=3, xlim=None, ylim=None, suptitle=None)

Plot a grid of fit curves.

Parameters:

Name	Type	Description	Default
curves	dict	Mapping from (frame, channel) to (x, y, yfit) tuples.	required
nm_window	tuple	Default x-axis window in nanometres when xlim is not provided.	required
frames	iterable	If provided, only include these frames.	None
channels	iterable	If provided, only include these channels.	None
ncols	int	Preferred number of columns in the plot grid.	3
xlim	tuple	Axis limits forwarded to each subplot.	None
ylim	tuple	Axis limits forwarded to each subplot.	None
suptitle	str	Optional figure-level title.	None

Returns:

Type	Description
fig, axes : tuple	Matplotlib figure and axes array for the created grid.

plot_overlay(curves, *, nm_window, frame, channels=None, xlim=None, ylim=None, title=None, cmap: str = 'tab10', line_width: float = 1.0, line_alpha: float = 0.95, scatter_size: float = 8.0, scatter_alpha: float = 0.35, legend_cols: int | None = None)

Overlay multiple channels for a single frame.

Parameters:

Name	Type	Description	Default
curves	dict	Mapping from (frame, channel) to (x, y, yfit) tuples.	required
nm_window	tuple	Default x-axis window in nanometres when xlim is not provided.	required
frame	int	Frame index to draw.	required
channels	iterable	If provided, only include these channels.	None
xlim	tuple	Axis limits.	None
ylim	tuple	Axis limits.	None
title	str	Axis title.	None
cmap	str	Matplotlib colormap name used to assign channel colors.	'tab10'
line_width	float	Width of the model lines.	1.0
line_alpha	float	Transparency for model lines.	0.95
scatter_size	float	Size for scatter points.	8.0
scatter_alpha	float	Alpha for scatter points.	0.35
legend_cols	int or None	Number of columns for the legend. If None a sensible default is chosen.	None

Returns:

Type	Description
fig, ax : tuple	Matplotlib figure and axis containing the overlay plot.

plot_single(res, *, nm_window, xlim=None, ylim=None, title=None, ax=None)

Plot a single fit result (data and optional model curve).

Parameters:

Name	Type	Description	Default
res	dict	Result dictionary as returned by BHFitter.fit (must contain x and y; may contain yfit).	required
nm_window	tuple	Default x-axis window in nanometres when xlim is not provided.	required
xlim	tuple	X-axis limits as (xmin, xmax). Defaults to nm_window.	None
ylim	tuple	Y-axis limits as (ymin, ymax).	None
title	str	Plot title.	None
ax	Axes	Axis to draw into. If None a new figure and axis are created.	None

Returns:

Name	Type	Description
ax	Axes	The axis containing the plot.

reset_light()

use_dark(bg=_DEF_BG, fg=_DEF_FG)

Matplotlib theme utilities: dark/light mode switching and context managers.