{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "path-01",
   "metadata": {},
   "source": "# Paths for supported data sources\n\nPath objects describe locations without reading them. All four classes accept a directory root and expose a `pathlib.Path` through `.fpath`.\n\n| Class | Purpose |\n|---|---|\n| `VTKPath` | VneuroTK HDF5 output naming |\n| `EphysPath` | Session-level electrophysiology products |\n| `MNEPath` | Flat MNE-readable filename under `root` |\n| `BIDSPath` | BIDS entities backed by optional `mne-bids` |"
  },
  {
   "cell_type": "markdown",
   "id": "path-02",
   "metadata": {},
   "source": [
    "## Electrophysiology paths\n",
    "\n",
    "`EphysPath` uses `{root}/sessions/{session_id}/{dtype}_{session_id}[_probeN].ext`. Its `raw_dir` and `nwb_path` use the same project root.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "path-03",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "from vneurotk.io import BIDSPath, EphysPath, MNEPath, VTKPath\n",
    "\n",
    "source_root = Path(\"data\")\n",
    "ephys_path = EphysPath(\n",
    "    root=source_root,\n",
    "    session_id=\"251024_FanFan_nsd1w_MSB\",\n",
    "    dtype=\"TrialRaster\",\n",
    "    probe=0,\n",
    "    extension=\"h5\",\n",
    ")\n",
    "ephys_file = ephys_path.fpath"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-04",
   "metadata": {},
   "source": [
    "## MNE versus BIDS\n",
    "\n",
    "`MNEPath` composes a filename directly below `root`; it does not infer a BIDS hierarchy. `BIDSPath` delegates entity placement and validation to `mne_bids.BIDSPath` when `vneurotk[mne]` is installed. Use `BIDSPath` for a BIDS dataset and `MNEPath` when the exact file is directly under the supplied root.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "path-05",
   "metadata": {},
   "outputs": [],
   "source": [
    "mne_path = MNEPath(\n",
    "    root=source_root,\n",
    "    subject=\"01\",\n",
    "    session=\"ImageNet01\",\n",
    "    task=\"ImageNet\",\n",
    "    run=\"01\",\n",
    "    suffix=\"meg_clean\",\n",
    "    extension=\".fif\",\n",
    ")\n",
    "bids_path = BIDSPath(\n",
    "    root=source_root,\n",
    "    subject=\"01\",\n",
    "    session=\"01\",\n",
    "    task=\"images\",\n",
    "    run=\"01\",\n",
    "    suffix=\"meg\",\n",
    "    extension=\".fif\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-06",
   "metadata": {},
   "source": [
    "## VneuroTK output paths\n",
    "\n",
    "The `VTKPath` root is the output directory. The class appends the BIDS-like HDF5 filename; do not pass an existing HDF5 file as its root. Pass existing files directly to `vneurotk.read()`.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "path-07",
   "metadata": {},
   "outputs": [],
   "source": [
    "output_path = VTKPath(\n",
    "    root=Path(\"outputs\"),\n",
    "    subject=\"01\",\n",
    "    session=\"ImageNet01\",\n",
    "    task=\"ImageNet\",\n",
    "    run=\"01\",\n",
    ")\n",
    "assert output_path.fpath == Path(\"outputs/sub-01_ses-ImageNet01_task-ImageNet_run-01.h5\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "path-08",
   "metadata": {},
   "source": "## Related documentation\n\n- [Path usage](../usage/path)\n- [I/O API](../api/io.md)\n- [HDF5 format](../format/hdf5.md)"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}