Module Reference

Provides batch spectrogram plotting utilities. Should work with CDFs like those from FAST (see batch_multi_plot_FAST_spectrograms.py) but should also be flexible with other data.

Assumed folder layout is::

{CDF_DATA_DIRECTORY}/year/month

Filenames in the month folders assumed to be in the following formats::

{??}_{??}_{??}_{instrument}_{timestamp}_{orbit}_v02.cdf (known “instruments” are ees, eeb, ies, or ieb) {??}_{??}_orb_{orbit}_{??}.cdf

Examples::

FAST_data/2000/01/fa_esa_l2_eeb_20000101001737_13312_v02.cdf FAST_data/2000/01/fa_k0_orb_13312_v01.cdf

batch_multi_plot_spectrogram.close_all_axes_and_clear(fig)

Close axes/subplots and clear a figure to free memory.

Parameters:

fig (matplotlib.figure.Figure) – Figure instance to clear and dispose.

Return type:

None

Notes

Ensures axes are deleted, the canvas is closed/detached, and removes the figure from the global Gcf registry when possible to mitigate memory growth during large batch operations.

batch_multi_plot_spectrogram.configure_log_batch(batch_size: int)

Configure buffered logging batch size.

Parameters:

batch_size (int) – Desired number of log records to accumulate before an automatic flush. Values less than 1 are coerced to 1.

batch_multi_plot_spectrogram.generic_batch_plot(items, output_dir, build_datasets_fn, zoom_center_fn=None, zoom_window_seconds=None, vertical_lines_fn=None, y_scale='linear', z_scale='linear', colormap='viridis', max_workers=2, progress_json_path: str = './batch_multi_plot_progress.json', ignore_progress_json: bool = False, flush_batch_size: int = 10, log_flush_batch_size: int | None = None, install_signal_handlers: bool = True)

Generic batch runner for plotting datasets.

Parameters:

• items (iterable) – Iterable of item identifiers (any repr-able objects).

• output_dir (str) – Base output directory; plots saved under output_dir/<item>/generic.png.

• build_datasets_fn (callable) – Callable returning list[dict] describing datasets for an item.

• zoom_center_fn (callable, optional) – Callable mapping item -> center UNIX time (or None) for zoom.

• zoom_window_seconds (float, optional) – Duration of zoom window in seconds.

• vertical_lines_fn (callable, optional) – Callable mapping item -> list[float] UNIX timestamps (or None).

• y_scale ({'linear', 'log'}, default 'linear') – Y-axis scaling for all rows.

• z_scale ({'linear', 'log'}, default 'linear') – Color scaling for all rows.

• colormap (str, default 'viridis') – Matplotlib colormap name.

• max_workers (int, default 2) – Number of parallel worker processes.

• progress_json_path (str, default PLOTTING_PROGRESS_JSON_PATH) – Path to progress JSON (resumable state). Created/updated as needed.

• ignore_progress_json (bool, default False) – If True, skip reading existing progress prior to execution.

• flush_batch_size (int, default 10) – Progress/log batch size; values < 1 coerced to 1. Final partial batch flushed.

• log_flush_batch_size (int, optional) – Explicit log batch size; if None reuse flush_batch_size.

• install_signal_handlers (bool, default True) – When True, a temporary SIGINT handler is installed (restored on exit) to enable graceful interruption (progress & log flush). Set False in embedded environments if altering the global handler causes side-effects.

Returns:

Sequence of (item, status) with status in {'ok', 'no_data', 'error'}.

Return type:

list of tuple

Notes

• Logging is buffered and force-flushed at completion.

• Progress JSON contains simple lists of completed, error, and no-data items.

• Items are identified via repr(item) for data-agnostic persistence.

batch_multi_plot_spectrogram.generic_plot_multirow_optional_zoom(datasets, vertical_lines=None, zoom_duration_minutes=6.25, y_scale='linear', z_scale='linear', colormap='viridis', show=False, title=None, row_label_pad=50, row_label_rotation=90, y_min=None, y_max=None, z_min=None, z_max=None)

Render a multi-row spectrogram grid with an optional zoom column.

Parameters:

• datasets (list of dict) –

  Each dict must contain keys:

  • 'x' – 1D UNIX epoch seconds (float) array

  • 'y' – 1D energy (eV) array (unfiltered, 0–4000 typical)

  • 'data' – 3D ndarray that can be collapsed (time, pitch/angle, energy)

  Optional per-row keys (all honored when present):

  • 'label' – Row label placed on the left (rotated)

  • 'y_label' – Units label for y-axis (default: 'Energy (eV)')

  • 'z_label' – Color scale label (default: 'Counts')

  • 'y_min' / 'y_max' – Energy bounds (overrides global y_min / y_max args)

  • 'z_min' / 'z_max' – Color bounds (overrides global z_min / z_max args)

  • 'vmin' / 'vmax' – Precomputed percentile (or fixed) color bounds used when

    z_min / z_max not provided. (vmin/vmax are interpreted as the row’s native bounds; global z_min / z_max will still clamp if supplied.)

• vertical_lines (list of float, optional) – UNIX timestamps defining event/selection markers and potential zoom window.

• zoom_duration_minutes (float, default 6.25) – Desired zoom window length in minutes (may auto-expand to include full marked span).

• y_scale ({'linear', 'log'}, default 'linear') – Y-axis scaling.

• z_scale ({'linear', 'log'}, default 'linear') – Color (intensity) scale.

• colormap (str, default 'viridis') – Matplotlib colormap.

• show (bool, default False) – If True, display interactively.

• title (str, optional) – Figure suptitle.

• row_label_pad (int, default 50) – Padding for row labels.

• row_label_rotation (int, default 90) – Rotation angle (degrees) for row labels.

• y_min (float, optional) – Global override bounds applied uniformly when provided. Any per-row y_min / y_max / z_min / z_max in a dataset dict take precedence. When neither global nor per-row color bounds are supplied the function relies on each dataset’s vmin / vmax (if present) else falls back to internal percentile selection in lower-level calls.

• y_max (float, optional) – Global override bounds applied uniformly when provided. Any per-row y_min / y_max / z_min / z_max in a dataset dict take precedence. When neither global nor per-row color bounds are supplied the function relies on each dataset’s vmin / vmax (if present) else falls back to internal percentile selection in lower-level calls.

• z_min (float, optional) – Global override bounds applied uniformly when provided. Any per-row y_min / y_max / z_min / z_max in a dataset dict take precedence. When neither global nor per-row color bounds are supplied the function relies on each dataset’s vmin / vmax (if present) else falls back to internal percentile selection in lower-level calls.

• z_max (float, optional) – Global override bounds applied uniformly when provided. Any per-row y_min / y_max / z_min / z_max in a dataset dict take precedence. When neither global nor per-row color bounds are supplied the function relies on each dataset’s vmin / vmax (if present) else falls back to internal percentile selection in lower-level calls.

Returns:

(fig, canvas) or (None, None) if datasets is empty.

Return type:

tuple

Notes

• Determines need for a zoom column dynamically: only rendered if at least

  one dataset contains non-NaN values inside the computed zoom window.

• Y-axis and colorbar labels default to “Energy (eV)” and “Counts” when a

  dataset omits explicit y_label / z_label (defaults originate in generic_plot_spectrogram_set / dataset assembly).

batch_multi_plot_spectrogram.generic_plot_spectrogram_set(datasets, collapse_axis=1, zoom_center=None, zoom_window_seconds=None, vertical_lines=None, x_is_unix=True, y_scale='linear', z_scale='linear', colormap='viridis', figure_title=None, show=False, y_min=None, y_max=None, z_min=None, z_max=None)

Plot a vertical stack of generic spectrograms.

Parameters:

• datasets (list of dict) – Each dict requires keys 'x', 'y', 'data' and may include optional keys: 'label', 'y_label', 'z_label', 'y_min', 'y_max', 'z_min', 'z_max'.

• collapse_axis (int, default 1) – Axis index of the 3D array collapsed prior to plotting.

• zoom_center (float, optional) – Center (UNIX time) for zoom column when used.

• zoom_window_seconds (float, optional) – Duration of zoom window (seconds) when zoom_center provided.

• vertical_lines (list of float, optional) – UNIX timestamps to annotate with vertical lines.

• x_is_unix (bool, default True) – If True, x values are treated as UNIX seconds and formatted.

• y_scale ({'linear', 'log'}, default 'linear') – Y-axis scaling mode.

• z_scale ({'linear', 'log'}, default 'linear') – Color (intensity) scale mode.

• colormap (str, default 'viridis') – Matplotlib colormap name.

• figure_title (str, optional) – Figure-level title (sup-title).

• show (bool, default False) – If True, display interactively (requires GUI backend).

• y_min (float, optional) – Global Y min fallback when per-row not supplied. Defaults to 0 if omitted and per-row missing.

• y_max (float, optional) – Global Y max fallback when per-row not supplied. If both global and per-row absent, inferred.

• z_min (float, optional) – Global colorbar lower bound fallback.

• z_max (float, optional) – Global colorbar upper bound fallback.

Returns:

(fig, canvas) or (None, None) if datasets is empty.

Return type:

tuple

batch_multi_plot_spectrogram.get_cdf_file_type(cdf_file_path: str)

Infer instrument type from a CDF file path.

Parameters:

cdf_file_path (str) – Path to the CDF file.

Returns:

Instrument type string (e.g., 'ees'), 'orb' for orbit files, or None if not recognized.

Return type:

str or None

batch_multi_plot_spectrogram.get_cdf_var_shapes(cdf_folder_path='./FAST_data/', variable_names=['time_unix', 'data', 'energy', 'pitch_angle'])

Collect shapes of variables across CDF files in a folder.

Parameters:

• cdf_folder_path (str, default CDF_DATA_DIRECTORY) – Directory containing CDF files.

• variable_names (list of str, default CDF_VARIABLE_NAMES) – Variable names to inspect.

Returns:

Mapping from variable name (str) to list of shape tuples (or None) per file.

Return type:

dict

batch_multi_plot_spectrogram.get_timestamps_for_orbit(filtered_orbits_dataframe, orbit_number, instrument_type, time_unix_array)

Compute orbit boundary UNIX timestamps from filtered indices.

Parameters:

• filtered_orbits_dataframe (pandas.DataFrame) – DataFrame containing filtered orbits and min/max indices per instrument.

• orbit_number (int) – Orbit number to look up.

• instrument_type (str) – Instrument type identifier (e.g., 'ees', 'ies').

• time_unix_array (numpy.ndarray) – 1D array of UNIX timestamps for the instrument.

Returns:

Boundary UNIX timestamps for the orbit (one value for a degenerate span or two values for start/end). Returns an empty list on invalid indices.

Return type:

list of float

batch_multi_plot_spectrogram.get_variable_shape(cdf_path, variable_name)

Return the shape of a variable in a CDF file.

Parameters:

• cdf_path (str) – Path to the CDF file.

• variable_name (str) – Variable name to inspect.

Returns:

Variable shape tuple, or None if variable absent / not array or an error occurs.

Return type:

tuple or None

batch_multi_plot_spectrogram.load_filtered_orbits(csv_path='./FAST_Cusp_Indices.csv')

Load the filtered orbits CSV with a simple cache.

Parameters:

csv_path (str, default FILTERED_ORBITS_CSV_PATH) – Path to the filtered orbits TSV/CSV file.

Returns:

DataFrame of filtered orbits, or None if loading fails.

Return type:

pandas.DataFrame or None

Notes

A module-level dictionary caches previously loaded DataFrames keyed by absolute path string to avoid repeated disk I/O in batch routines.

batch_multi_plot_spectrogram.log_error(message: str, force_flush: bool = False)

Queue an error log message and echo to console immediately.

batch_multi_plot_spectrogram.log_message(message: str, force_flush: bool = False)

Queue an informational log message.

Messages are appended to an in-memory buffer; a flush occurs automatically once the configured batch size is reached or force_flush is True.

batch_multi_plot_spectrogram.make_spectrogram(x_axis_values, y_axis_values, data_array_3d, x_axis_min=None, x_axis_max=None, x_axis_is_unix=True, x_axis_label=None, center_timestamp=None, window_duration_seconds=None, y_axis_scale_function=None, y_axis_label=None, y_axis_min=0, y_axis_max=4000, z_axis_scale_function=None, z_axis_min=None, z_axis_max=None, z_axis_label=None, collapse_axis=1, colormap='viridis', axis_object=None, instrument_label=None, vertical_lines_unix=None)

Plot a spectrogram by collapsing a 3D data array along an axis.

Parameters:

• x_axis_values (array-like) – 1D array for x (horizontal) axis (e.g., time sequence).

• y_axis_values (array-like) – 1D array for y (vertical) axis (e.g., energy bins).

• data_array_3d (numpy.ndarray) – 3D data array, e.g. (time, angle/pitch, energy).

• x_axis_min (float, optional) – Explicit x-axis clipping bounds before plotting.

• x_axis_max (float, optional) – Explicit x-axis clipping bounds before plotting.

• x_axis_is_unix (bool, default True) – If True, x-axis treated as UNIX seconds and converted to dates.

• x_axis_label (str, optional) – Custom x-axis label (default depends on x_axis_is_unix).

• center_timestamp (float, optional) – Center of requested zoom window (UNIX seconds).

• window_duration_seconds (float, optional) – Duration of zoom window; both must be provided for zoom to apply.

• y_axis_scale_function ({'linear', 'log'}, optional) – Y-axis scaling; None behaves as 'linear'.

• y_axis_label (str, optional) – Y-axis label text.

• y_axis_min (float, default 0, 4000) – Y-axis clipping range applied before filtering / plotting.

• y_axis_max (float, default 0, 4000) – Y-axis clipping range applied before filtering / plotting.

• z_axis_scale_function ({'linear', 'log'}, optional) – Color scale mode; None behaves as 'linear'.

• z_axis_min (float, optional) – Optional color scale bounds (percentiles chosen if omitted).

• z_axis_max (float, optional) – Optional color scale bounds (percentiles chosen if omitted).

• z_axis_label (str, optional) – Colorbar label text.

• collapse_axis (int, default 1) – Axis index along which to collapse the 3D data array.

• colormap (str, default 'viridis') – Matplotlib colormap name.

• axis_object (matplotlib.axes.Axes, optional) – Existing axes to draw into; if None a new figure/axes created.

• instrument_label (str, optional) – Title string applied to the axes.

• vertical_lines_unix (list of float, optional) – UNIX timestamps to annotate with vertical lines.

Returns:

• axis_object (matplotlib.axes.Axes or None) – The axis object used for plotting (None if no data plotted).

• x_axis_plot (numpy.ndarray or None) – X values actually used (possibly filtered / converted), or None if skipped.

Plots a folder of FAST ESA data as spectrograms.

Assumed folder layout is::

{FAST_CDF_DATA_FOLDER_PATH}/year/month

Filenames in the month folders assumed to be in the following formats::

{??}_{??}_{??}_{instrument}_{timestamp}_{orbit}_v02.cdf (known “instruments” are ees, eeb, ies, or ieb) {??}_{??}_orb_{orbit}_{??}.cdf

Examples::

FAST_data/2000/01/fa_esa_l2_eeb_20000101001737_13312_v02.cdf FAST_data/2000/01/fa_k0_orb_13312_v01.cdf

batch_multi_plot_FAST_spectrograms.FAST_plot_instrument_grid(cdf_file_paths: Dict[str, str], filtered_orbits_df=None, orbit_number: int | None = None, zoom_duration_minutes: float = 6.25, scale_function_y: str = 'linear', scale_function_z: str = 'linear', instrument_order: Tuple[str, ...] = ('ees', 'eeb', 'ies', 'ieb'), show: bool = True, colormap: str = 'viridis', y_min: float | None = None, y_max: float | None = None, z_min: float | None = None, z_max: float | None = None, global_extrema: Dict[str, int | float] | None = None) → Tuple[Any, Any]

Plot a multi-instrument ESA spectrogram grid for a single orbit.

Loads each instrument CDF, orients and filters the data, collapses across pitch-angle, and constructs datasets for generic_plot_multirow_optional_zoom. When vertical lines are available for the orbit, a zoom column is included.

Parameters:

• cdf_file_paths (dict of {str: str}) – Mapping of instrument key ('ees', 'eeb', 'ies', 'ieb') to CDF file path. Missing instruments are skipped.

• filtered_orbits_df (pandas.DataFrame or None) – DataFrame for vertical line computation; if None, lines are omitted.

• orbit_number (int or None) – Orbit identifier used in titles/lines.

• zoom_duration_minutes (float, default 6.25) – Zoom window length (minutes).

• scale_function_y ({'linear', 'log'}, default 'linear') – Y-axis scaling.

• scale_function_z ({'linear', 'log'}, default 'linear') – Color scale for intensity.

• instrument_order (tuple of str, default ('ees', 'eeb', 'ies', 'ieb')) – Display order of instrument rows.

• show (bool, default True) – Whether to show the figure interactively.

• colormap (str, default 'viridis') – Matplotlib colormap name.

• y_min (float or None, optional) – Global fallback overrides for axis/color limits. Per-instrument overrides from global_extrema take precedence; finally row-level percentile scaling is used when neither is provided.

• y_max (float or None, optional) – Global fallback overrides for axis/color limits. Per-instrument overrides from global_extrema take precedence; finally row-level percentile scaling is used when neither is provided.

• z_min (float or None, optional) – Global fallback overrides for axis/color limits. Per-instrument overrides from global_extrema take precedence; finally row-level percentile scaling is used when neither is provided.

• z_max (float or None, optional) – Global fallback overrides for axis/color limits. Per-instrument overrides from global_extrema take precedence; finally row-level percentile scaling is used when neither is provided.

• global_extrema (dict or None, optional) – Mapping containing precomputed extrema keys ({instrument}_{y_scale}_{z_scale}_{axis}_{min|max}) used to supply per-instrument (row-specific) limits. This enables distinct y/z ranges for ees, eeb, ies, and ieb within the same figure, improving contrast when dynamic ranges differ.

• y_min – Direct energy bounds override applied when global_extrema is not provided. Ignored per-instrument when global_extrema supplies instrument-specific keys.

• y_max – Direct energy bounds override applied when global_extrema is not provided. Ignored per-instrument when global_extrema supplies instrument-specific keys.

• z_min – Direct intensity scale overrides (see above re: global_extrema).

• z_max – Direct intensity scale overrides (see above re: global_extrema).

• global_extrema – Mapping containing precomputed extrema keys of the form {instrument}_{y_scale}_{z_scale}_{axis}_{min|max}. When present these take precedence over y_min / y_max / z_min / z_max.

Returns:

Figure and Canvas, or (None, None) if no datasets.

Notes

• Files that fail to load are logged and skipped; remaining instruments may

  still render.

• Energy bins are restricted to [0, 4000] (or overridden via global_extrema

  or explicit y_min / y_max).

• vmin/vmax per row use 1st/99th percentiles for robust scaling unless

  global_extrema provides per-instrument z_min / z_max.

• Each dataset row sets y_label='Energy (eV)' and z_label='Counts' by

  default for clarity of physical units.

Return type:

tuple[Figure or None, FigureCanvasBase or None]

batch_multi_plot_FAST_spectrograms.FAST_plot_pitch_angle_grid(cdf_file_path: str, filtered_orbits_df=None, orbit_number: int | None = None, zoom_duration_minutes: float = 6.25, scale_function_y: str = 'linear', scale_function_z: str = 'linear', pitch_angle_categories: Dict[str, List[Tuple[float, float]]] | None = None, show: bool = True, colormap: str = 'viridis', y_min: float | None = None, y_max: float | None = None, z_min: float | None = None, z_max: float | None = None) → Tuple[Any, Any]

Plot a grid of ESA spectrograms collapsed by pitch-angle categories.

Each row corresponds to a pitch-angle category (e.g., downgoing, upgoing, perpendicular, all). If orbit boundary timestamps are available for this instrument/orbit, a zoom column is added. Data are loaded from the CDF, oriented so that energy is the y-axis, and collapsed over pitch-angle via FAST_COLLAPSE_FUNCTION (np.nansum by default).

Parameters:

• cdf_file_path (str) – Path to the instrument CDF file.

• filtered_orbits_df (pandas.DataFrame or None) – DataFrame used to compute vertical lines for the orbit_number. If None, vertical lines are omitted.

• orbit_number (int or None) – Orbit number used to compute and label vertical lines.

• zoom_duration_minutes (float, default 6.25) – Window length (minutes) for the optional zoom column.

• scale_function_y ({'linear', 'log'}, default 'linear') – Y-axis scaling for the spectrogram.

• scale_function_z ({'linear', 'log'}, default 'linear') – Color scale for the spectrogram intensity.

• pitch_angle_categories (dict or None) – Mapping of label -> list of (min_deg, max_deg) ranges; if None, defaults to standard four groups.

• show (bool, default True) – If True, display the plot; otherwise render off-screen.

• colormap (str, default 'viridis') – Matplotlib colormap name.

• y_min (float or None, optional) – Optional explicit energy (y-axis) limits override. When None the default lower bound (0) and observed upper bound (<=4000) subset is used. These overrides are typically provided by precomputed global extrema.

• y_max (float or None, optional) – Optional explicit energy (y-axis) limits override. When None the default lower bound (0) and observed upper bound (<=4000) subset is used. These overrides are typically provided by precomputed global extrema.

• z_min (float or None, optional) – Optional explicit color (intensity) scale limits. When None the 1st / 99th percentiles per row are used (robust to outliers). When provided (e.g., global extrema), they are applied uniformly across rows.

• z_max (float or None, optional) – Optional explicit color (intensity) scale limits. When None the 1st / 99th percentiles per row are used (robust to outliers). When provided (e.g., global extrema), they are applied uniformly across rows.

Returns:

Figure and Canvas for the grid, or (None, None) if no datasets.

Return type:

tuple[Figure or None, FigureCanvasBase or None]

Notes

• Energy bins are filtered to [0, 4000] (or explicit y_min / y_max).

• vmin/vmax (row color bounds) are derived from 1st/99th percentiles

  unless explicit z_min / z_max provided.

• Each dataset row includes y_label='Energy (eV)' and z_label='Counts';

  modify after return if alternative units are desired.

• When no pitch-angle category yields data, the function logs a message and

  returns (None, None).

batch_multi_plot_FAST_spectrograms.FAST_plot_spectrograms_directory(directory_path: str = './FAST_data/', output_base: str = './FAST_plots/', y_scale: str = 'linear', z_scale: str = 'log', zoom_duration_minutes: float = 6, instrument_order: Tuple[str, ...] = ('ees', 'eeb', 'ies', 'ieb'), verbose: bool = True, progress_json_path: str | None = './batch_multi_plot_FAST_progress.json', ignore_progress_json: bool = False, use_tqdm: bool | None = None, colormap: str = 'viridis', max_workers: int = 4, orbit_timeout_seconds: int | float = 60, instrument_timeout_seconds: int | float = 30, retry_timeouts: bool = True, flush_batch_size: int = 10, log_flush_batch_size: int | None = None, max_processing_percentile: float = 95.0) → List[Dict[str, Any]]

Batch process ESA spectrogram plots for all orbits in a directory.

Discovers instrument CDF files (excluding filenames containing "_orb_"), groups them by orbit number, and processes each orbit in parallel worker processes for matplotlib safety. Progress is persisted to a JSON file to support resume and to record error/timeout orbits per y/z scale combo. Before scheduling orbit tasks a global extrema pass runs (compute_global_extrema) for the requested (y_scale, z_scale). For log scales, if a completed linear counterpart (same other-axis scale) exists, its maxima are reused and log-transformed with a floor (see log_floor_cutoff / log_floor_value) instead of rescanning files.

Parameters:

• directory_path (str, default FAST_CDF_DATA_FOLDER_PATH) – Root folder containing CDF files.

• output_base (str, default FAST_OUTPUT_BASE) – Base output directory for plots organized as output_base/year/month/orbit.

• y_scale ({'linear', 'log'}, default 'linear') – Y-axis scaling.

• z_scale ({'linear', 'log'}, default 'log') – Color scale for intensity.

• zoom_duration_minutes (float, default DEFAULT_ZOOM_WINDOW_MINUTES) – Zoom window length for zoom columns.

• instrument_order (tuple of str, default ('ees', 'eeb', 'ies', 'ieb')) – Display order for instrument grid.

• verbose (bool, default True) – If True, prints additional batch messages.

• progress_json_path (str or None, default FAST_PLOTTING_PROGRESS_JSON) – Path to persist progress across runs.

• ignore_progress_json (bool, default False) – If True, don’t read previous progress before starting.

• use_tqdm (bool or None, default None) – If True, show a tqdm progress bar; if None, defaults to False.

• colormap (str, default 'viridis') – Matplotlib colormap name.

• max_workers (int, default 4) – Max number of worker processes.

• orbit_timeout_seconds (int or float, default 60) – Total per-orbit timeout.

• instrument_timeout_seconds (int or float, default 30) – Per-instrument/grid timeout.

• retry_timeouts (bool, default True) – If True, retry timed-out orbits once after the initial pass.

• flush_batch_size (int, default 10) – Batch size applied to both extrema JSON and progress JSON writes to reduce I/O. Values < 1 are coerced to 1. Final partial batch always flushes.

• log_flush_batch_size (int or None, default None) – Batch size for buffered logging. If None, defaults to flush_batch_size.

• max_processing_percentile (float, default 95.0) – Upper percentile (0 < p <= 100) forwarded to the internal compute_global_extrema helper as max_percentile. Currently this percentile controls the pooled positive intensity (Z) maxima selection. Energy (Y) maxima continue to use a fixed 99% cumulative positive count coverage rule (hard-coded) – i.e., the smallest energy whose cumulative positive finite sample count reaches 99% of total positive samples. A future refactor may unify these so that max_processing_percentile also governs the Y coverage threshold.

Returns:

Result dictionaries from FAST_process_single_orbit (and any retries), in no particular order.

Return type:

list of dict

Raises:

KeyboardInterrupt – Raised immediately on SIGINT/SIGTERM to stop scheduling and terminate workers.

Notes

• Signal handling installs handlers that request shutdown, terminate child

  processes, and raise KeyboardInterrupt promptly.

• Progress JSON tracks last completed orbit per scale combo under key

  f"progress_{y_scale}_{z_scale}_last_orbit" and records error/timeout orbits under dedicated keys (including per-instrument).

• If ignore_progress_json is True, progress is not read; writes are

  still attempted.

• If retry_timeouts is True, timed-out orbits are retried once with

  a smaller pool.

• max_processing_percentile only impacts intensity maxima today; Y

  maxima coverage threshold is fixed at 99%.

batch_multi_plot_FAST_spectrograms.FAST_process_single_orbit(orbit_number: int, instrument_file_paths: Dict[str, str], filtered_orbits_dataframe, zoom_duration_minutes: float, y_axis_scale: str, z_axis_scale: str, instrument_order: Tuple[str, ...], colormap: str, output_base_directory: str, orbit_timeout_seconds: int | float = 60, instrument_timeout_seconds: int | float = 30, global_extrema: Dict[str, int | float] | None = None) → Dict[str, Any]

Process all plots for a single orbit with timeouts and deferred saving.

For each available instrument, renders a pitch-angle grid, then renders a combined instrument grid. Figures are accumulated in memory and saved only if no timeout thresholds are exceeded.

Parameters:

• orbit_number (int) – The orbit identifier.

• instrument_file_paths (dict of {str: str}) – Mapping of instrument key to CDF file path.

• filtered_orbits_dataframe (pandas.DataFrame) – DataFrame used to compute orbit boundary timestamps.

• zoom_duration_minutes (float) – Zoom window length for zoomed plots.

• y_axis_scale ({'linear', 'log'}) – Y-axis scaling.

• z_axis_scale ({'linear', 'log'}) – Color scale for intensity.

• instrument_order (tuple of str) – Order used in the instrument grid.

• colormap (str) – Matplotlib colormap.

• output_base_directory (str) – Root folder for saving figures; year/month are inferred from the CDF path when possible, else 'unknown'.

• orbit_timeout_seconds (int or float, default 60) – Maximum wall-clock seconds permitted for the entire orbit processing (summed).

• instrument_timeout_seconds (int or float, default 30) – Per-instrument rendering timeout; exceeded instruments are skipped and noted.

• global_extrema (dict or None, optional) – Precomputed extrema mapping used to supply uniform axis limits to all instrument plots for deterministic scaling; produced by compute_global_extrema.

• orbit_timeout_seconds – Max total time for this orbit; if exceeded, status becomes 'timeout' and no figures are saved.

• instrument_timeout_seconds – Max time per instrument (and for the instrument grid). Exceeding this aborts the orbit without saving.

• global_extrema – Precomputed extrema dictionary (see compute_global_extrema) used to supply consistent per-instrument axis limits across all orbits.

Returns:

Result dictionary with keys: orbit (int), status ('ok', 'error', or 'timeout'), errors (list of str). On timeout, includes timeout_type and timeout_instrument when applicable.

Return type:

dict

Notes

• Timing diagnostics are logged per instrument and for the grid.

• Exceptions during plotting/saving are logged; processing continues when safe. Figures are closed in all cases to free memory.

batch_multi_plot_FAST_spectrograms.configure_info_logger_batch(batch_size: int) → None

Configure the batch size for buffered info logging.

Parameters:

batch_size (int) – Number of log entries to accumulate before an automatic flush. Values < 1 disable buffering (flush every call).

batch_multi_plot_FAST_spectrograms.flush_info_logger_buffer(force: bool = True) → None

Flush any buffered info/error log messages immediately.

Parameters:

force (bool, default True) – Present for future extensibility; currently ignored (always flushes).

batch_multi_plot_FAST_spectrograms.info_logger(prefix: str, exception: BaseException | None = None, level: str = 'error', include_trace: bool = False, force_flush: bool = False) → None

Unified logger for messages and exceptions.

This helper formats a message with an optional exception, includes the exception class name when provided, and delegates to generic logging helpers from the base module (log_message/log_error). When include_trace is True and an exception is given, a traceback is also emitted.

Parameters:

• prefix (str) – Human-readable message prefix for the log line.

• exception (BaseException or None) – Optional exception instance. If None, only prefix is logged.

• level ({'error', 'message'}, default 'error') – Logging level. 'error' routes to log_error; otherwise to log_message.

• include_trace (bool, default False) – When True and exception is not None, include a formatted traceback after the primary log message.

• force_flush (bool, default False) – When True, forces an immediate flush of the buffered log messages (including the current one) regardless of batch size.

Return type:

None

Notes

If the underlying logging helpers fail (e.g., misconfigured), this function falls back to printing to stdout/stderr to avoid silent loss. When an exception is provided, messages are formatted as "{prefix} [<ExceptionClass>]: {exception}".

batch_multi_plot_FAST_spectrograms.main() → None

Run the FAST batch plotter for all y/z scale combinations sequentially.

Invokes FAST_plot_spectrograms_directory four times with combinations of linear/log y and z, using colormaps tailored for each.

Return type:

None

Notes

An interrupt during any run stops the sequence immediately without starting subsequent combinations.

batch_multi_plot_FAST_spectrograms.round_extrema(value: float | int, direction: str) → float

Round an extrema value up or down to a visually clean axis limit.

This function is used to make plot axis extrema (min/max) more visually appealing and consistent by rounding them to the nearest significant digit in the specified direction. For example, 1234 rounded up becomes 1300, and 0.0123 rounded down becomes 0.012.

Parameters:

• value (float or int) – The extrema value to round. If zero, returns 0.0.

• direction ({'up', 'down'}) – The direction to round: - ‘up’: round up to the next clean value (for maxima) - ‘down’: round down to the previous clean value (for minima)

Returns:

The rounded extrema value.

Return type:

float

Raises:

ValueError – If an invalid direction is provided.

Examples

>>> round_extrema(1234, 'up')
1300.0
>>> round_extrema(1234, 'down')
1200.0
>>> round_extrema(0.0123, 'up')
0.013
>>> round_extrema(0.0123, 'down')
0.012