GUI Development Bundles: Intentions & Specs

This document specifies a bundle layer: small, deterministic collections of entities that are known to work together. Bundles exist to accelerate GUI development by providing “one import” fixtures with consistent coordinates, shapes, and optional overlays.

Bundle principles

  • Schema-first: every field has a declared schema (see schemas.md).

  • Reproducible: bundles accept seed and are stable across runs.

  • Two modes: mode="small" and mode="large" (see modes.md).

  • GUI-ready: precompute the small derived items GUIs commonly need:

    • grid index mapping,

    • per-channel scalars for heatmaps (e.g. RMS),

    • optional atlas image + placement metadata.

Implemented public API

cogpy.datasets.gui_bundles.ieeg_grid_bundle(...) -> IEEGGridGuiBundle

Intent

  • Provide a grid-shaped time series plus derived forms needed by the current Panel viewers:

    • ChannelGridWidget wants (AP, ML) background values and optional atlas data.

    • ieeg_viewer typically wants a time×channel view (stacked) and/or a grid-wired selector.

Signature (current)

  • ieeg_grid_bundle(*, mode="small", seed=0, with_atlas=False, large_backend="numpy")

Return type

  • cogpy.datasets.gui_bundles.IEEGGridGuiBundle (dataclass)

Return fields (current)

  • sig_grid: xr.DataArray — IEEGGridTimeSeries dims ("time","ML","AP")

  • sig_apml: xr.DataArray — derived view dims ("time","AP","ML") used for consistent flattening/stacking

  • sig_tc: xr.DataArray — stacked view dims ("time","channel") via sig_apml.stack(channel=("AP","ML"))

  • rms_apml: np.ndarray — (n_ap, n_ml) scalar for grid background (std over time)

  • n_ap, n_ml: int — grid shape

  • fs: float | None — sampling rate if present in attrs

  • ap_coords, ml_coords: np.ndarray — physical coords copied from sig_grid

  • atlas_image: np.ndarray | None — currently None (hook for future atlas bundling)

  • meta: dict — includes mode, seed, large_backend

Acceptance criteria

  • sig_grid and sig_tc represent the same underlying signal (no mismatch in indexing order).

  • rms_apml matches sig_apml.std(dim="time").transpose("AP","ML").

  • Flattening/stacking convention is consistent with ChannelGrid:

    • flat = ap * n_ml + ml corresponds to sig_apml.stack(channel=("AP","ML")).isel(channel=flat).

cogpy.datasets.gui_bundles.spectrogram_bursts_bundle(...) -> SpectrogramGuiBundle

Intent

  • Provide a 4D spectrogram tensor plus peak annotations for linked orthoslicer + peak overlay development.

Signature (current)

  • spectrogram_bursts_bundle(*, mode="small", seed=0, kind="toy")

Return fields (current)

  • spec: xr.DataArray — GridSpectrogram4D dims ("ml","ap","time","freq")

  • bursts: pd.DataFrame — BurstPeaksTable

  • meta: dict

Acceptance criteria

  • Every burst row lies within the coordinate extents of spec.

  • Burst coordinates use the same units as spec coords.

Relationship to existing generators

The current module code/lib/cogpy/src/cogpy/datasets/tensor.py already provides:

  • 4D toy tensors: make_dataset, make_flat_blob_dataset

  • peak table schema: detect_bursts_hmaxima

  • a realistic-ish oscillatory grid simulator: AROscillatorGrid.make(...)

  • iEEG-like multichannel signals: example_smooth_multichannel_sigx, example_ieeg

The intention is to wrap (or refactor) these into bundle constructors while keeping:

  • deterministic defaults,

  • explicit schema validation,

  • mode-driven sizing.