Neural data modes and containers#

BaseData gives neural arrays an explicit layout: continuous samples, pre-epoched trials, or aggregated patterns. NeuroData wraps the stored array and provides structured views; it is not a NumPy array subclass.

Build all three modes#

Factory	Shape	Meaning
`for_continuous`	`(n_samples, n_channels)`	Continuous recording; configure onsets before requesting epochs
`for_epochs`	`(n_trials, n_timebins, n_channels)`	Trials are already segmented
`for_patterns`	`(n_rows, n_channels)`	Aggregated rows, not a time axis

Use the factories to disambiguate two-dimensional arrays.

import numpy as np

import vneurotk as vtk

info = {"ch_names": ["a", "b", "c", "d"], "sfreq": 10.0}
continuous = vtk.BaseData.for_continuous(np.arange(80, dtype=float).reshape(20, 4), neuro_info=info)
epochs = vtk.BaseData.for_epochs(np.arange(96, dtype=float).reshape(3, 8, 4), neuro_info=info)
patterns = vtk.BaseData.for_patterns(
    np.arange(24, dtype=float).reshape(6, 4),
    neuro_info={"ch_names": info["ch_names"]},
)
assert [x.data_mode for x in (continuous, epochs, patterns)] == ["continuous", "epochs", "patterns"]

Container semantics#

data.neuro returns NeuroData. Its .data property is the underlying ndarray; numpy.asarray(data.neuro) performs explicit array conversion. Shape, dtype, and size are proxied. Trial-aware .epochs and .continuous return arrays when trial structure exists.

neuro = patterns.neuro
raw_array = neuro.data
converted = np.asarray(neuro)
assert raw_array.shape == converted.shape == (6, 4)

Configure trial semantics#

For continuous recordings, configure() binds each stimulus ID to an onset and derives trial boundaries from trial_window. Pre-epoched recordings already have a trial axis and need only stimulus alignment. Patterns cannot be configured; provide trial_meta["stim_index"] when rows must align with vision features.

stim_ids = np.array(["image-1", "image-2", "image-1"])
images = {
    "image-1": np.zeros((8, 8, 3), dtype=np.uint8),
    "image-2": np.full((8, 8, 3), 255, dtype=np.uint8),
}
continuous.configure(
    stim_ids=stim_ids,
    vision_onsets=np.array([2, 8, 14]),
    trial_window=[-1, 3],
    vision_db=images,
)
epoch_array = continuous.neuro.epochs