{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "data-01",
   "metadata": {},
   "source": "# Neural data modes and containers\n\n`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."
  },
  {
   "cell_type": "markdown",
   "id": "data-02",
   "metadata": {},
   "source": [
    "## Build all three modes\n",
    "\n",
    "| Factory | Shape | Meaning |\n",
    "|---|---|---|\n",
    "| `for_continuous` | `(n_samples, n_channels)` | Continuous recording; configure onsets before requesting epochs |\n",
    "| `for_epochs` | `(n_trials, n_timebins, n_channels)` | Trials are already segmented |\n",
    "| `for_patterns` | `(n_rows, n_channels)` | Aggregated rows, not a time axis |\n",
    "\n",
    "Use the factories to disambiguate two-dimensional arrays.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "data-03",
   "metadata": {},
   "outputs": [],
   "source": [
    "import numpy as np\n",
    "\n",
    "import vneurotk as vtk\n",
    "\n",
    "info = {\"ch_names\": [\"a\", \"b\", \"c\", \"d\"], \"sfreq\": 10.0}\n",
    "continuous = vtk.BaseData.for_continuous(np.arange(80, dtype=float).reshape(20, 4), neuro_info=info)\n",
    "epochs = vtk.BaseData.for_epochs(np.arange(96, dtype=float).reshape(3, 8, 4), neuro_info=info)\n",
    "patterns = vtk.BaseData.for_patterns(\n",
    "    np.arange(24, dtype=float).reshape(6, 4),\n",
    "    neuro_info={\"ch_names\": info[\"ch_names\"]},\n",
    ")\n",
    "assert [x.data_mode for x in (continuous, epochs, patterns)] == [\"continuous\", \"epochs\", \"patterns\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "data-04",
   "metadata": {},
   "source": [
    "## Container semantics\n",
    "\n",
    "`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.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "data-05",
   "metadata": {},
   "outputs": [],
   "source": [
    "neuro = patterns.neuro\n",
    "raw_array = neuro.data\n",
    "converted = np.asarray(neuro)\n",
    "assert raw_array.shape == converted.shape == (6, 4)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "data-06",
   "metadata": {},
   "source": [
    "## Configure trial semantics\n",
    "\n",
    "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.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "data-07",
   "metadata": {},
   "outputs": [],
   "source": [
    "stim_ids = np.array([\"image-1\", \"image-2\", \"image-1\"])\n",
    "images = {\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",
    "continuous.configure(\n",
    "    stim_ids=stim_ids,\n",
    "    vision_onsets=np.array([2, 8, 14]),\n",
    "    trial_window=[-1, 3],\n",
    "    vision_db=images,\n",
    ")\n",
    "epoch_array = continuous.neuro.epochs"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "data-08",
   "metadata": {},
   "source": "## Related documentation\n\n- [Neural-data usage](../usage/data)\n- [Visualization usage](../usage/viz)\n- [Visualization example](viz)\n- [Core API](../api/core.md)\n- [Neural API](../api/neuro.md)"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}