Core#

Joint data object and shared primitives.

BaseData#

class vneurotk.core.recording.BaseData(neuro, neuro_info, stim_labels=None, vision_info=None, trial=None, trial_info=None, trial_starts=None, trial_ends=None, vision_onsets=None, trial_meta=None, data_mode=None)#

Unified container for neural data, stimulus labels, and trial structure.

Parameters:
neuronp.ndarray | None

Neural data array. None when using lazy loading. Shape (ntime, nchan) → data_mode="continuous"; (n_trials, n_timebins, nchan) → data_mode="epochs"; (n, nchan) with data_mode="patterns" for aggregated data.

neuro_infodict

Mutable dictionary compatible with NeuroInfo. sfreq is required for time-based operations. Optional keys include ch_names, highpass, lowpass, source_file, and shape.

stim_labelsnp.ndarray | None

Internal stimulus-label array of shape (ntime,) or (n_trials, n_timebins). np.nan at non-stimulus timepoints, stimulus ID at onset timepoints. Not exposed directly; use trial_stim_ids.

vision_infodict | None

Mutable dictionary compatible with VisionInfo; commonly contains n_stim and stim_ids.

trialnp.ndarray | None

Trial-ID array. Shape (ntime,) for continuous data or (n_trials, n_timebins) for epochs data; np.nan outside trials.

trial_infodict | None

Mutable dictionary compatible with TrialInfo; commonly contains baseline and trial_window.

trial_startsnp.ndarray | None

Start sample indices per trial, shape (n_trials,).

trial_endsnp.ndarray | None

End sample indices per trial, shape (n_trials,).

vision_onsetsnp.ndarray | None

Stimulus onset sample indices, shape (n_trials,).

trial_metapd.DataFrame | None

Per-trial metadata table.

data_modestr or None

"continuous" for 2-D time-series (ntime, nchan), "epochs" for 3-D trial-epoched (n_trials, n_timebins, nchan), "patterns" for 2-D aggregated (n, nchan). None triggers auto-inference from neuro.ndim (3-D → "epochs", 2-D → "continuous").

Parameters:

  • neuro (np.ndarray | None)

  • neuro_info (dict[str, Any])

  • stim_labels (np.ndarray | None)

  • vision_info (dict[str, Any] | None)

  • trial (np.ndarray | None)

  • trial_info (dict[str, Any] | None)

  • trial_starts (np.ndarray | None)

  • trial_ends (np.ndarray | None)

  • vision_onsets (np.ndarray | None)

  • trial_meta (Any)

  • data_mode (DataMode | None)

Examples

>>> import numpy as np
>>> neuro = np.random.randn(1000, 64)
>>> info = dict(sfreq=250.0, ch_names=[f"ch{i}" for i in range(64)])
>>> bd = BaseData(neuro, info)
>>> bd
BaseData(ntime=1000, nchan=64, n_trials=0, configured=False)
configure(stim_ids, trial_window=None, vision_onsets=None, vision_db=None)#

Attach stimulus and trial structure to the data.

For continuous data (data_mode == "continuous"), both trial_window and vision_onsets are required.

For pre-epoched data (data_mode == "epochs"), both parameters are optional: vision_onsets falls back to any already-stored value, then defaults to index 0 of each epoch; trial_window is ignored.

Parameters:
stim_idsarray-like, shape (n_onsets,)

Stimulus ID for each onset / trial, must match vision_onsets length and order.

trial_windowlist of float | int or None

Two-element [start, end] relative to each onset. Float → seconds; int → samples. Required for continuous data; ignored for epochs data.

vision_onsetsnp.ndarray or None

1-D array of stimulus onset sample indices. Required for continuous data. For epochs data defaults to already-stored value or 0.

vision_dbdict, list, np.ndarray, or None

Stimulus image source. Stored immediately as the Stimulus Set for this Recording. It can also be supplied later to extract_from() via vision. If a Stimulus Set is already attached, it is replaced and an info message is logged.

Parameters:

  • stim_ids (ndarray | list)

  • trial_window (list[float | int] | None)

  • vision_onsets (ndarray | None)

  • vision_db (dict | list | ndarray | None)

Return type:

None

property configured: bool#

Whether the state required by the active data mode is complete.

Continuous and epochs recordings require the full trial structure. Patterns are already row-level responses, so a two-dimensional neuro array (or declared lazy shape) is sufficient; row stimulus IDs are optional and only enable vision alignment.

classmethod for_continuous(neuro=None, neuro_info=None, **kwargs)#

Factory for continuous (2-D time-series) recordings.

Parameters:
neuronp.ndarray or None

Neural data, shape (ntime, nchan). Pass None when using lazy loading via set_neuro_loader().

neuro_infodict or None

Metadata dict; sfreq key is required for most operations.

**kwargs

Any other BaseData constructor parameters (e.g. stim_labels, trial_info).

Returns:
BaseData
Parameters:

  • neuro (ndarray | None)

  • neuro_info (dict[str, Any] | None)

  • kwargs (Any)

Return type:

BaseData

classmethod for_epochs(neuro=None, neuro_info=None, **kwargs)#

Factory for pre-epoched recordings.

Parameters:
neuronp.ndarray or None

Neural data, shape (n_trials, n_timebins, nchan). Pass None when using lazy loading.

neuro_infodict or None

Metadata dict; sfreq key is required for most operations.

**kwargs

Any other BaseData constructor parameters.

Returns:
BaseData
Parameters:

  • neuro (ndarray | None)

  • neuro_info (dict[str, Any] | None)

  • kwargs (Any)

Return type:

BaseData

classmethod for_patterns(neuro=None, neuro_info=None, **kwargs)#

Factory for row-level response patterns.

Pattern rows are valid without trial arrays. Pass trial_meta with a stim_index column when rows have explicit stimulus identities and should align to vision features.

Parameters:

  • neuro (ndarray | None)

  • neuro_info (dict[str, Any] | None)

  • kwargs (Any)

Return type:

BaseData

property has_vision: bool#

Whether any DNN features have been stored via vision.extract_from().

property info: Info#

Summary of neuro, visual, and trial metadata.

property is_configured: bool#

Alias for configured. True after configure() succeeds.

property is_vision_ready: bool#

True when DNN features have been extracted and vision is safe to access.

load()#

Explicitly load neuro data into memory and return self.

Returns:
BaseData

self, for method chaining.

Return type:

BaseData

property n_timepoints: int#

Time points per trial.

property n_trials: int#

Number of trials (patterns have rows rather than trials).

property nchan: int#

Number of channels.

property neuro: NeuroData#

Neural data as a NeuroData.

Returns a NeuroData wrapper. Use data for the underlying NumPy array; .epochs and .continuous provide trial-structured views.

property ntime: int#

Number of time samples (first axis for continuous/patterns; second for epochs).

plot(window=(0.0, 5.0), figsize=(6, 3), cmap_neuro='Greys', cmap_ontime='summer', color_offtime='black', marker_size=40)#

Plot neural activity alongside stimulus labels.

Parameters:
windowtuple of float | int

Display window. Float values are seconds, int values are samples.

figsizetuple of float

Figure size (width, height).

cmap_neurostr

Colormap for neural heatmap.

cmap_ontimestr

Colormap for in-trial time.

color_offtimestr

Color for off-trial points.

marker_sizefloat

Scatter marker size.

Returns:
matplotlib.figure.Figure
Raises:
ValueError

If data_mode="patterns", which has no time axis.

Parameters:

  • window (tuple[float | int, float | int])

  • figsize (tuple[float, float])

  • cmap_neuro (str)

  • cmap_ontime (str)

  • color_offtime (str)

  • marker_size (float)

save(path, *, compression='gzip', compression_opts=4, chunk_target_bytes=1048576)#

Persist data that is complete for its active mode to an HDF5 file.

Parameters:
pathVTKPath | pathlib.Path | str

Destination file path.

compressionstr or None

HDF5 filter for neural and activation arrays. Defaults to "gzip"; pass None to disable compression.

compression_optsAny

Filter-specific options; defaults to gzip level 4.

chunk_target_bytesint

Approximate maximum chunk size for large numerical arrays. Defaults to 1 MiB and preserves lazy dataset loading.

Raises:
RuntimeError

If the data is incomplete for its active mode.

Parameters:

  • path (Any)

  • compression (str | None)

  • compression_opts (Any)

  • chunk_target_bytes (int)

Return type:

None

set_neuro_loader(loader)#

Register a lazy loader for the neuro array.

Parameters:
loaderNeuroLoader

Callable with no arguments that returns np.ndarray when called. The loader is invoked once on the first access of neuro and its result is cached.

Parameters:

loader (Callable[[], ndarray])

Return type:

None

property stim_labels: ndarray | None#

Raw stimulus label array from the trial layout.

Shape depends on data_mode:

  • "continuous" → (ntime,)

  • "epochs" → (n_trials, n_timebins)

None before configure() is called.

property trial_stim_ids: ndarray#

Stimulus IDs aligned to trial or pattern rows.

Pattern data exposes IDs only when row metadata explicitly contains a stim_index column. Row position alone never implies stimulus identity.

Raises:
RuntimeError

If the active mode is incomplete, or patterns have no explicit row stimulus IDs.

property vision: Any#

DNN feature store for this dataset.

Returns a VisionData with the following interface:

  • db — original stimulus image dict (vision_db).

  • stim_ids — per-onset stimulus IDs, shape (n_trials,).

  • meta — DataFrame with one row per stored VisualRepresentation.

  • vision[mask] — smart accessor: string / int / bool-mask index; single VR → aligned ndarray; multiple VRs → VisualRepresentations.

Raises:
RuntimeError

If configure() has not been called yet.

Data modes#

vneurotk.core.recording.DataMode#

alias of Literal[‘continuous’, ‘epochs’, ‘patterns’]

Metadata dictionaries#

NeuroInfo, VisionInfo, and TrialInfo are TypedDict boundary types for the known metadata keys. Runtime values remain ordinary mutable dictionaries, so existing dict inputs, extra keys, persistence, and equality behavior remain compatible.

class vneurotk.core.metadata.NeuroInfo#

Known keys accepted in BaseData.neuro_info.

The runtime value remains an ordinary mutable dict. total=False preserves existing inputs, including pattern data without a sampling rate and lazy data that only declares a shape.

class vneurotk.core.metadata.VisionInfo#

Known keys accepted in BaseData.vision_info.

class vneurotk.core.metadata.TrialInfo#

Known keys accepted in BaseData.trial_info.

Epochs with varying onset positions use one window per trial, while continuous and uniformly aligned epochs use a single two-value window.

StimulusSet#

class vneurotk.core.stimulus.StimulusSet(stim_ids, stimuli=None)#

Container linking per-onset stimulus IDs to per-stimulus images.

Parameters:
stim_idsarray-like, shape (n_onsets,)

Stimulus ID for each onset.

stimulidict, list, np.ndarray, or None

Image source for each unique stimulus.

dict

{stim_id: image} — explicit mapping.

list / np.ndarray of length n_unique

Auto-assigned in first-appearance order from stim_ids.

list / np.ndarray of length n_onsets

Aggregated per stim_id (first occurrence wins per id).

None

Only stim IDs are stored; no image data.

Parameters:

  • stim_ids (np.ndarray | list)

  • stimuli (dict | list | np.ndarray | None)

Notes

Supported image types: PIL.Image, np.ndarray, Path, str. Path / str entries are lazily loaded as PIL.Image on __getitem__ access.

Examples

>>> ss = StimulusSet(stim_ids=[0, 1, 0], stimuli={0: arr0, 1: arr1})
>>> ss[0]   # returns arr0
classmethod from_dict(stim_ids, stimuli)#

Build from an explicit {stim_id: image} mapping.

Parameters:
stim_idsarray-like, shape (n_onsets,)

Stimulus ID per onset.

stimulidict

Complete {stim_id: image} mapping; every unique ID in stim_ids must have a corresponding entry. Mapping entries whose keys do not occur in stim_ids are ignored.

Returns:
StimulusSet
Raises:
ValueError

If any unique stimulus ID has no mapping entry.

Parameters:

  • stim_ids (ndarray)

  • stimuli (dict)

Return type:

StimulusSet

classmethod from_h5(stim_ids, lazy_dict)#

Build from a LazyH5Dict or any Mapping for lazy HDF5 access.

Parameters:
stim_idsarray-like, shape (n_onsets,)

Stimulus ID per onset.

lazy_dictMapping

Any mapping conforming to ImageSource (e.g. LazyH5Dict).

Returns:
StimulusSet
Parameters:

  • stim_ids (ndarray)

  • lazy_dict (Any)

Return type:

StimulusSet

classmethod from_unique_list(stim_ids, images)#

Build from a list of images aligned with unique stim_ids.

images must have exactly as many entries as there are unique stimulus IDs, ordered by first appearance in stim_ids.

Parameters:
stim_idsarray-like, shape (n_onsets,)

Stimulus ID per onset.

imageslist

One image per unique stimulus, in first-appearance order.

Returns:
StimulusSet
Raises:
ValueError

If len(images) does not equal the number of unique stim IDs.

Parameters:

  • stim_ids (ndarray)

  • images (list)

Return type:

StimulusSet

items()#

Yield (stim_id, image) pairs for all unique stimuli.

property stim_ids: ndarray#

Per-onset stimulus IDs, shape (n_onsets,).

property stimuli: Mapping[Any, Any] | None#

Dict {stim_id: image} or None if not provided.

property unique_ids: list#

Unique stimulus IDs in sorted order when their types are comparable.

Info#

class vneurotk.core.info.Info(neuro, visual, trial, configured, data_mode='continuous')#

Summary object returned by BaseData.info.

Parameters:
neurodict

Dict with keys n_time, n_chan, sfreq, highpass, lowpass.

visualdict or None

Dict with key n_stim.

trialdict or None

Dict with keys baseline, trial_window.

configuredbool

Whether the parent BaseData has been configured.

data_modestr

"continuous", "epochs", or "patterns".

Parameters:

  • neuro (Mapping[str, Any])

  • visual (Mapping[str, Any] | None)

  • trial (Mapping[str, Any] | None)

  • configured (bool)

  • data_mode (str)