{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "path-01",
   "metadata": {},
   "source": "# Work with VneuroTK paths\n\nVneuroTK path objects describe locations without performing I/O. They accept `str` or `pathlib.Path` roots and produce `pathlib.Path` values through `.fpath`.\n\n| Class | Use |\n|---|---|\n| `VTKPath` | VneuroTK HDF5 recordings and the base naming convention |\n| `EphysPath` | Session-level electrophysiology data |\n| `MNEPath` | MNE-readable MEG/EEG files with a flat filename under `root` |\n| `BIDSPath` | BIDS entities backed by the optional `mne-bids` package |\n\nThis notebook uses path construction only and does not read files. Full BIDS loading requires `vneurotk[mne]`."
  },
  {
   "cell_type": "markdown",
   "id": "path-02",
   "metadata": {},
   "source": [
    "## Construct electrophysiology paths"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "path-03",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-08-01T17:59:12.759065Z",
     "iopub.status.busy": "2026-08-01T17:59:12.758943Z",
     "iopub.status.idle": "2026-08-01T17:59:14.134752Z",
     "shell.execute_reply": "2026-08-01T17:59:14.133794Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "PosixPath('data/sessions/251024_FanFan_nsd1w_MSB/TrialRaster_251024_FanFan_nsd1w_MSB.h5')"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "from vneurotk.io import BIDSPath, EphysPath, MNEPath, VTKPath\n",
    "\n",
    "root = Path(\"data\")\n",
    "ephys = EphysPath(\n",
    "    root=root,\n",
    "    session_id=\"251024_FanFan_nsd1w_MSB\",\n",
    "    dtype=\"TrialRaster\",\n",
    "    extension=\"h5\",\n",
    ")\n",
    "ephys.fpath"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-04",
   "metadata": {},
   "source": [
    "`EphysPath` supports unit- and channel-level products such as `TrialRaster`, `MeanFr`, `ChTrialRaster`, and `ChStimFr`. A `probe` adds the probe suffix; `from_components()` assembles the session identifier."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "path-05",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-08-01T17:59:14.137107Z",
     "iopub.status.busy": "2026-08-01T17:59:14.136688Z",
     "iopub.status.idle": "2026-08-01T17:59:14.141914Z",
     "shell.execute_reply": "2026-08-01T17:59:14.140988Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(PosixPath('data/sessions/251024_FanFan_nsd1w_MSB'),\n",
       " PosixPath('data/sessions/251024_FanFan_nsd1w_MSB/TrialRaster_251024_FanFan_nsd1w_MSB_probe0.h5'))"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "multi_probe = EphysPath(\n",
    "    root=root,\n",
    "    session_id=\"251024_FanFan_nsd1w_MSB\",\n",
    "    dtype=\"TrialRaster\",\n",
    "    probe=0,\n",
    "    extension=\"h5\",\n",
    ")\n",
    "from_parts = EphysPath.from_components(\n",
    "    root=root,\n",
    "    date=\"251024\",\n",
    "    subject=\"FanFan\",\n",
    "    paradigm=\"nsd1w\",\n",
    "    region=\"MSB\",\n",
    "    dtype=\"TrialRaster\",\n",
    "    extension=\"h5\",\n",
    ")\n",
    "from_parts.session_dir, multi_probe.fpath"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-06",
   "metadata": {},
   "source": [
    "## Construct MNE and BIDS paths"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "path-07",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-08-01T17:59:14.143779Z",
     "iopub.status.busy": "2026-08-01T17:59:14.143590Z",
     "iopub.status.idle": "2026-08-01T17:59:14.149021Z",
     "shell.execute_reply": "2026-08-01T17:59:14.148334Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(PosixPath('data/sub-01_ses-ImageNet01_task-ImageNet_run-01_meg_clean.fif'),\n",
       " PosixPath('data/sub-01_ses-01_task-images_run-01_meg.fif'))"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mne_path = MNEPath(\n",
    "    root=root,\n",
    "    subject=\"01\",\n",
    "    session=\"ImageNet01\",\n",
    "    task=\"ImageNet\",\n",
    "    run=\"01\",\n",
    "    suffix=\"meg_clean\",\n",
    "    extension=\".fif\",\n",
    ")\n",
    "\n",
    "bids_path = BIDSPath(\n",
    "    root=root,\n",
    "    subject=\"01\",\n",
    "    session=\"01\",\n",
    "    task=\"images\",\n",
    "    run=\"01\",\n",
    "    suffix=\"meg\",\n",
    "    extension=\".fif\",\n",
    ")\n",
    "mne_path.fpath, bids_path.fpath"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-08",
   "metadata": {},
   "source": [
    "`MNEPath` builds a filename directly under `root`. `BIDSPath` delegates BIDS layout and entities to `mne_bids.BIDSPath` when the extra is installed; otherwise `.bids_path` is `None` and `.fpath` uses the base fallback."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-09",
   "metadata": {},
   "source": [
    "## Construct a VneuroTK output path"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "path-10",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-08-01T17:59:14.151006Z",
     "iopub.status.busy": "2026-08-01T17:59:14.150825Z",
     "iopub.status.idle": "2026-08-01T17:59:14.155231Z",
     "shell.execute_reply": "2026-08-01T17:59:14.154293Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "PosixPath('outputs/sub-01_ses-ImageNet01_task-ImageNet_run-01.h5')"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "output = VTKPath(\n",
    "    Path(\"outputs\"),\n",
    "    subject=\"01\",\n",
    "    session=\"ImageNet01\",\n",
    "    task=\"ImageNet\",\n",
    "    run=\"01\",\n",
    ")\n",
    "output.fpath"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-11",
   "metadata": {},
   "source": "Pass a directory as the `VTKPath` root; the object appends the recording filename. To read an existing HDF5 file, pass that file path directly to `vneurotk.read()` instead of wrapping it as a `VTKPath` root.\n\n## Related documentation\n\n- {doc}`Build neural data <data>`\n- [I/O API](../api/io.md)\n- [VneuroTK HDF5 format](../format/hdf5.md)"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.13.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}