{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "data-01",
   "metadata": {},
   "source": "# Build VneuroTK neural data\n\n`BaseData` represents neural recordings while `NeuroData` is its neural-array container. `NeuroData` is not an `ndarray` subclass; use `.data` for the underlying array or `numpy.asarray()` for array conversion.\n\nThis notebook uses deterministic synthetic arrays and requires only the core package."
  },
  {
   "cell_type": "markdown",
   "id": "data-02",
   "metadata": {},
   "source": [
    "## Choose an explicit data mode\n",
    "\n",
    "| Mode | Raw shape | Trial structure |\n",
    "|---|---|---|\n",
    "| `continuous` | `(n_samples, n_channels)` | Configure onsets before using `.epochs` |\n",
    "| `epochs` | `(n_trials, n_timebins, n_channels)` | Already trial-structured |\n",
    "| `patterns` | `(n_rows, n_channels)` | Aggregated rows |\n",
    "\n",
    "Use the matching factory whenever a 2-D array's meaning would otherwise be ambiguous."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "data-03",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-08-01T17:59:16.060556Z",
     "iopub.status.busy": "2026-08-01T17:59:16.060275Z",
     "iopub.status.idle": "2026-08-01T17:59:16.592385Z",
     "shell.execute_reply": "2026-08-01T17:59:16.591552Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "('continuous', 'epochs', 'patterns')"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "import numpy as np\n",
    "\n",
    "import vneurotk as vtk\n",
    "\n",
    "continuous = vtk.BaseData.for_continuous(\n",
    "    neuro=np.arange(80, dtype=float).reshape(20, 4),\n",
    "    neuro_info={\"ch_names\": [\"a\", \"b\", \"c\", \"d\"], \"sfreq\": 10.0},\n",
    ")\n",
    "epochs = vtk.BaseData.for_epochs(\n",
    "    neuro=np.arange(96, dtype=float).reshape(3, 8, 4),\n",
    "    neuro_info={\"ch_names\": [\"a\", \"b\", \"c\", \"d\"], \"sfreq\": 10.0},\n",
    ")\n",
    "patterns = vtk.BaseData.for_patterns(\n",
    "    neuro=np.arange(24, dtype=float).reshape(6, 4),\n",
    "    neuro_info={\"ch_names\": [\"a\", \"b\", \"c\", \"d\"]},\n",
    ")\n",
    "continuous.data_mode, epochs.data_mode, patterns.data_mode"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "data-04",
   "metadata": {},
   "source": [
    "## Inspect the neural container"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "data-05",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-08-01T17:59:16.594811Z",
     "iopub.status.busy": "2026-08-01T17:59:16.594465Z",
     "iopub.status.idle": "2026-08-01T17:59:16.600217Z",
     "shell.execute_reply": "2026-08-01T17:59:16.599194Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "((6, 4), dtype('float64'), (6, 4), (6, 4))"
      ]
     },
     "execution_count": 2,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "neuro = patterns.neuro\n",
    "neuro.shape, neuro.dtype, np.asarray(neuro).shape, neuro.data.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "data-06",
   "metadata": {},
   "source": [
    "## Configure continuous trial structure"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "data-07",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-08-01T17:59:16.602345Z",
     "iopub.status.busy": "2026-08-01T17:59:16.602116Z",
     "iopub.status.idle": "2026-08-01T17:59:16.610378Z",
     "shell.execute_reply": "2026-08-01T17:59:16.609399Z"
    }
   },
   "outputs": [
    {
     "data": {
      "text/plain": [
       "(3, 4, 4)"
      ]
     },
     "execution_count": 3,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "stim_ids = np.array([\"image-1\", \"image-2\", \"image-1\"])\n",
    "continuous.configure(\n",
    "    vision_onsets=np.array([2, 8, 14]),\n",
    "    stim_ids=stim_ids,\n",
    "    vision_db={\n",
    "        \"image-1\": np.zeros((8, 8, 3), dtype=np.uint8),\n",
    "        \"image-2\": np.full((8, 8, 3), 255, dtype=np.uint8),\n",
    "    },\n",
    "    trial_window=[-1, 3],\n",
    ")\n",
    "continuous.neuro.epochs.shape"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "data-08",
   "metadata": {},
   "source": [
    "`configure()` binds stimulus IDs, onset samples, a trial window, and an image database. Pattern rows require `trial_meta[\"stim_index\"]` only when they need alignment with vision features."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "data-09",
   "metadata": {},
   "source": [
    "## Read recording sources"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "data-10",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-08-01T17:59:16.611867Z",
     "iopub.status.busy": "2026-08-01T17:59:16.611724Z",
     "iopub.status.idle": "2026-08-01T17:59:16.615418Z",
     "shell.execute_reply": "2026-08-01T17:59:16.614204Z"
    }
   },
   "outputs": [],
   "source": "from pathlib import Path\n\nfrom vneurotk.io import EphysPath, MNEPath\n\n# These examples describe inputs; reading requires the matching local files.\nsource_root = Path(\"data\")\nmne_source = 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)\nephys_source = EphysPath(\n    root=source_root,\n    session_id=\"251024_FanFan_nsd1w_MSB\",\n    dtype=\"TrialRaster\",\n    extension=\"h5\",\n)\n# meg_data = vtk.read(mne_source)\n# ephys_data = vtk.read(ephys_source)"
  },
  {
   "cell_type": "markdown",
   "id": "data-11",
   "metadata": {},
   "source": "Electrophysiology products are configured by their loaders. MNE recordings remain lazy until neural values are accessed and need `configure()` before trial-aligned views are available.\n\n## Related documentation\n\n- [Work with paths](path)\n- [Extract vision features with neural data](vision_union)\n- [Core API](../api/core.md)\n- [Neural API](../api/neuro.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
}