I/O#

Path classes and data loaders for VneuroTK.

Path Classes#

class vneurotk.io.path.EphysPath(root, session=None, subject=None, task=None, run=None, desc=None, probe=None, suffix=None, extension=None, session_id=None, dtype=None)#

Path class for ephys session-level data.

Follows the naming convention:

{root}/sessions/{session_id}/{dtype}_{session_id}[_probe{N}].{ext}

The fpath property points to a file under sessions/. Auxiliary properties raw_dir and nwb_path expose the raw/ and nwb/ subdirectories for convenience.

VTKPath fields subject, task, run, desc, and suffix are inherited but not used by fpath; use session_id and dtype instead.

Parameters:
rootPath

Root project directory (e.g. DB/ephys/MonkeyVision).

session_idstr, optional

Full session identifier, e.g. "251024_FanFan_nsd1w_MSB". Format: {date}_{subject}_{paradigm}_{region}.

dtypestr, optional

Data type. Must be one of EPHYS_DTYPES.

probeint, optional

Probe index (0-based). None for single-probe sessions.

extensionstr, optional

File extension. Must be one of EPHYS_EXTENSIONS. Default is "h5".

Parameters:

  • root (Path)

  • session (str | None)

  • subject (str | None)

  • task (str | None)

  • run (str | None)

  • desc (str | None)

  • probe (int | None)

  • suffix (str | None)

  • extension (str | None)

  • session_id (str | None)

  • dtype (str | None)

property fpath: Path#

Full path to the session-level analysis file.

Returns:
Path

{root}/sessions/{session_id}/{dtype}_{session_id}[_probe{N}].{ext}

Raises:
ValueError

If session_id or dtype is not set.

classmethod from_components(root, date, subject, paradigm, region, dtype=None, probe=None, extension='h5')#

Build an EphysPath from individual session components.

Parameters:
rootstr or Path

Root project directory.

datestr

Session date, e.g. "251024".

subjectstr

Subject name, e.g. "FanFan".

paradigmstr

Paradigm string including optional block/run marker, e.g. "nsd1w" (paradigm nsd, block 1w).

regionstr

Brain region, e.g. "MSB".

dtypestr, optional

Data type (see EPHYS_DTYPES).

probeint, optional

Probe index (0-based).

extensionstr

File extension. Default "h5".

Returns:
EphysPath
Parameters:

  • root (str | Path)

  • date (str)

  • subject (str)

  • paradigm (str)

  • region (str)

  • dtype (str | None)

  • probe (int | None)

  • extension (str)

Return type:

EphysPath

load(pre_load=False)#

Load this Ephys session into a BaseData.

Parameters:
pre_loadbool

If True, eagerly load neuro data into memory before returning.

Returns:
BaseData
Parameters:

pre_load (bool)

Return type:

BaseData

property nwb_path: Path#

Path to the NWB intermediate file for this session.

Returns:
Path

{root}/nwb/{session_id}[_probe{N}].nwb

Raises:
ValueError

If session_id is not set.

property raw_dir: Path#

Raw data directory for this session.

Returns:
Path

{root}/raw/{session_id}

Raises:
ValueError

If session_id is not set.

property session_dir: Path#

Directory containing this session’s analysis files.

Returns:
Path

{root}/sessions/{session_id}

Raises:
ValueError

If session_id is not set.

class vneurotk.io.path.MNEPath(root, session=None, subject=None, task=None, run=None, desc=None, probe=None, suffix=None, extension=None)#

Path class for MNE data.

Inherits all attributes from VTKPath. Sets modality to ‘mne’ by default. Constructs MNE-style file paths.

Parameters:

  • root (Path)

  • session (str | None)

  • subject (str | None)

  • task (str | None)

  • run (str | None)

  • desc (str | None)

  • probe (int | None)

  • suffix (str | None)

  • extension (str | None)

property fpath: Path#

Construct MNE-style file path.

Returns:
Path

Full file path in MNE format: root/sub-{subject}_ses-{session}_task-{task}_run-{run}_{suffix}.{extension}

load(pre_load=False)#

Load this MNE recording into a BaseData.

Parameters:
pre_loadbool

If True, eagerly load neuro data into memory before returning.

Returns:
BaseData
Parameters:

pre_load (bool)

Return type:

BaseData

class vneurotk.io.path.VTKPath(root, session=None, subject=None, task=None, run=None, desc=None, probe=None, suffix=None, extension=None, modality=None)#

Base path class for VneuroTK data sources.

Attributes:
rootPath

Root directory for the data.

sessionstr | None

Session identifier.

subjectstr | None

Subject identifier.

taskstr | None

Task identifier.

runstr | None

Run identifier.

descstr | None

Description identifier.

probeint | None

Probe number (ephys only).

suffixstr | None

File suffix.

extensionstr | None

File extension.

modalitystr | None

Data modality (ephys, mne, bids).

Parameters:

  • root (Path)

  • session (str | None)

  • subject (str | None)

  • task (str | None)

  • run (str | None)

  • desc (str | None)

  • probe (int | None)

  • suffix (str | None)

  • extension (str | None)

  • modality (str | None)

property fpath: Path#

Construct full file path.

Returns:
Path

Full file path constructed from attributes.

load(pre_load=False)#

Load data described by this path into a BaseData.

For base VTKPath instances pointing to a saved .h5 file, loads via the internal HDF5 reader. Typed subclasses override this method with format-specific loading logic.

Raises:
NotImplementedError

If this path does not point to a .h5 file and has no typed loading strategy (i.e., it is a plain VTKPath).

Parameters:

pre_load (bool)

Return type:

BaseData

class vneurotk.io.path.BIDSPath(root, session=None, subject=None, task=None, run=None, desc=None, probe=None, suffix=None, extension=None)#

Path class for BIDS data.

Inherits all attributes from VTKPath. Sets modality to ‘bids’ by default. Wraps mne_bids.BIDSPath internally.

Parameters:

  • root (Path)

  • session (str | None)

  • subject (str | None)

  • task (str | None)

  • run (str | None)

  • desc (str | None)

  • probe (int | None)

  • suffix (str | None)

  • extension (str | None)

property bids_path: Any#

Get underlying mne_bids.BIDSPath object.

Returns:
mne_bids.BIDSPath

The wrapped BIDS path object.

property fpath: Path#

Get BIDS file path.

Returns:
Path

Full BIDS file path.

load(pre_load=False)#

Load this BIDS recording into a BaseData.

Parameters:
pre_loadbool

If True, eagerly load neuro data into memory before returning.

Returns:
BaseData
Parameters:

pre_load (bool)

Return type:

BaseData

Path constants#

vneurotk.io.path.EPHYS_DTYPES: frozenset[str] = frozenset({'AvgPsth', 'ChMeanFr', 'ChProp', 'ChStimFr', 'ChTrialRaster', 'ChTrialRecord', 'MeanFr', 'TrialRaster', 'TrialRecord', 'UnitProp'})#

Build an immutable unordered collection of unique elements.

vneurotk.io.path.EPHYS_EXTENSIONS: frozenset[str] = frozenset({'csv', 'h5', 'nwb'})#

Build an immutable unordered collection of unique elements.

Reading Data#

vneurotk.io.loader.read(path, pre_load=False)#

Read data from various sources into BaseData.

Parameters:
pathVTKPath, EphysPath, MNEPath, BIDSPath, Path, or str

Data source. Plain Path / str is treated as a direct file path (e.g. an .h5 file saved by save()).

pre_loadbool

If True, eagerly load neuro data into memory before returning (calls load() internally). If False (default), data is loaded lazily on first access to neuro — call load() explicitly to trigger loading at a chosen point. For data types that carry no lazy loader (already eager), this flag is a no-op.

Returns:
BaseData

Data as BaseData object.

Raises:
NotImplementedError

If loading AvgPsth (not yet implemented).

ValueError

If path type is unknown or file format unsupported.

FileNotFoundError

If the specified file does not exist.

Parameters:
Return type:

BaseData

class vneurotk.io.loader.LazyNeuroLoader(loader_fn)#

Deferred loader for a neuro array — invokes loader_fn on first call.

Wraps any Callable[[], np.ndarray] and guarantees the underlying function is executed at most once. The result is cached so subsequent calls return the same array without re-reading from disk.

Satisfies the NeuroLoader = Callable[[], np.ndarray] contract, so it can be passed directly to set_neuro_loader().

Parameters:
loader_fnCallable[[], np.ndarray]

Zero-argument function that reads and returns the neuro array.

Parameters:

loader_fn (Callable[[], np.ndarray])

Examples

>>> loader = LazyNeuroLoader(lambda: np.load("data.npy"))
>>> bd.set_neuro_loader(loader)  # called at most once on first bd.neuro access
property is_loaded: bool#

True after the first call has materialised the array.

class vneurotk.io.loader.LazyH5Dict(path, group='stimuli_db', *, identity=None)#

HDF5-backed read-only image dict that loads arrays on demand.

The key index is built on first access (one lightweight pass over attribute metadata only). Each __getitem__ call opens the file, reads a single dataset, and closes it immediately.

Parameters:
pathPath or str

Path to the HDF5 file.

groupstr

HDF5 group name that contains the image datasets. Default "stimuli_db".

Parameters:

  • path (Path | str)

  • group (str)

  • identity (FileIdentity | None)