{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "neurovision-01",
   "metadata": {},
   "source": "# NOD-MEG neurovision workflow\n\nThis workflow downloads the bounded NOD-MEG sample, configures MEG trials and stimuli, extracts selected model activations, and saves one VneuroTK HDF5 recording."
  },
  {
   "cell_type": "markdown",
   "id": "neurovision-02",
   "metadata": {},
   "source": [
    "## Data-rights warning\n",
    "\n",
    "Technical access does not grant permission to use or redistribute recordings, metadata, stimuli, or derived files. Verify authoritative licenses, citations, consent or ethics conditions, privacy requirements, and stimulus terms before use. Saved HDF5 files can contain neural arrays, trial metadata, model provenance, and stimulus pixels; review them before sharing.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "neurovision-03",
   "metadata": {},
   "source": [
    "## Read the sample\n",
    "\n",
    "The fetcher may use the network on first run. `vtk.read()` keeps neural values lazy until accessed.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "neurovision-04",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "import mne\n",
    "import numpy as np\n",
    "import pandas as pd\n",
    "import torch\n",
    "\n",
    "import vneurotk as vtk\n",
    "from vneurotk.datasets import sample\n",
    "from vneurotk.io import MNEPath, VTKPath\n",
    "\n",
    "sample_root = sample.data_path(\"nod-meg\")\n",
    "nod_root = sample_root / \"nod-meg\"\n",
    "subject, session, run = sample.NOD_SUBJECT, sample.NOD_SESSION, sample.NOD_RUN\n",
    "source = MNEPath(\n",
    "    root=nod_root / \"meg\",\n",
    "    subject=subject,\n",
    "    session=session,\n",
    "    task=sample.NOD_TASK,\n",
    "    run=run,\n",
    "    suffix=\"meg_clean\",\n",
    "    extension=\".fif\",\n",
    ")\n",
    "data = vtk.read(source)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "neurovision-05",
   "metadata": {},
   "source": [
    "## Configure trial alignment\n",
    "\n",
    "The events table supplies stimulus IDs in run order; MNE annotations supply onset samples. Float `trial_window` bounds are seconds.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "neurovision-06",
   "metadata": {},
   "outputs": [],
   "source": [
    "events = pd.read_csv(nod_root / \"events\" / f\"sub-{subject}_events.csv\")\n",
    "run_number = int(run)\n",
    "run_events = events.query(\"run == @run_number and session == @session\")\n",
    "stim_ids = run_events[\"image_id\"].to_numpy()\n",
    "images = {sid: nod_root / \"stimuli\" / f\"{sid}.JPEG\" for sid in np.unique(stim_ids)}\n",
    "raw = mne.io.read_raw(source.fpath, preload=False, verbose=False)\n",
    "onsets = vtk.utils.get_event_samples(raw, event_name=\"stim_on\")\n",
    "data.configure(\n",
    "    stim_ids=stim_ids,\n",
    "    vision_onsets=onsets,\n",
    "    trial_window=[-0.2, 0.8],\n",
    "    vision_db=images,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "neurovision-07",
   "metadata": {},
   "source": [
    "## Extract representations\n",
    "\n",
    "The integrated extractor stores activations once per unique stimulus. `data.vision[...]` aligns them back to trial order.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "neurovision-08",
   "metadata": {},
   "outputs": [],
   "source": [
    "device = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
    "model = vtk.VisionModel(\"facebook/dinov2-base\", backend=\"transformers\", device=device)\n",
    "model.set_selector(module_name=\"layernorm\")\n",
    "data.vision.extract_from(model, batch_size=16)\n",
    "trial_aligned = data.vision[\"layernorm\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "neurovision-09",
   "metadata": {},
   "source": [
    "## Save the recording\n",
    "\n",
    "`VTKPath` receives an output directory and appends the filename. Saving creates parent directories as needed.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "neurovision-10",
   "metadata": {},
   "outputs": [],
   "source": [
    "output = VTKPath(\n",
    "    root=Path(\"outputs\"),\n",
    "    subject=subject,\n",
    "    session=session,\n",
    "    task=sample.NOD_TASK,\n",
    "    run=run,\n",
    ")\n",
    "data.save(output)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "neurovision-11",
   "metadata": {},
   "source": "## Related documentation\n\n- [Neural-data usage](../usage/data)\n- [Integrated vision usage](../usage/vision_union)\n- [Dataset and data-rights policy](../data-policy.md)\n- [Core API](../api/core.md)\n- [Vision API](../api/vision.md)\n- [I/O API](../api/io.md)"
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}