Upload 3 files

LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amphora NeuroText contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,213 @@
+---
+license: mit
+language:
+  - en
+tags:
+  - neuroscience
+  - fmri
+  - brain-encoding
+  - text-embeddings
+  - roi-prediction
+  - pytorch
+library_name: pytorch
+pipeline_tag: feature-extraction
+---
+
+# Amphora NeuroText — Text to Brain ROI Activations
+
+**Hugging Face model:** [`ffh92r32rm0/Amphora_NeuroText`](https://huggingface.co/ffh92r32rm0/Amphora_NeuroText)
+
+Lightweight MLP that maps **text** → **56 cortical/subcortical ROI activation scores**.
+
+```
+text  →  Qwen3-Embedding-4B (2560d)  →  Text2ROI MLP (3.2M params)  →  56 ROI values
+```
+
+This is a fast, text-native brain encoding model. It does **not** require the full V5 joint fMRI encoder or multimodal feature extraction — only Qwen3 text embeddings plus this 13 MB projector.
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://huggingface.co/ffh92r32rm0/Amphora_NeuroText/colab)
+
+**Try it now:** [Open the Colab demo](https://huggingface.co/ffh92r32rm0/Amphora_NeuroText/colab) (GPU runtime → type text → click **Predict** → ROI bar chart + fsaverage5 brain maps).
+
+Weights (`text2roi_projector.pt`) download automatically from this public HF repo — no token needed.
+
+**Model page:** https://huggingface.co/ffh92r32rm0/Amphora_NeuroText
+
+## Model details
+
+| | |
+|---|---|
+| **Input** | Any English text string |
+| **Text encoder** | [`Qwen/Qwen3-Embedding-4B`](https://huggingface.co/Qwen/Qwen3-Embedding-4B) (2560d, L2-normalized last token) |
+| **Projector** | 3-layer MLP: 2560 → 1024 → 512 → 56 |
+| **Output** | 56 ROI activation scores (universal schema, same order as NeuroDiffusion V5) |
+| **Parameters** | 3,178,040 (projector only) |
+| **Checkpoint size** | ~13 MB |
+| **Val mean Pearson R** | **0.170** (held-out text–fMRI pairs) |
+| **Training data** | ~300k text–ROI pairs from naturalistic fMRI corpora |
+| **License** | MIT (this repo). Qwen3-Embedding-4B has its own [license](https://huggingface.co/Qwen/Qwen3-Embedding-4B). |
+
+### ROI outputs (56 regions)
+
+Visual (`V1`–`EBA`), parietal (`IPS2`–`hIP3`), frontal executive (`dlPFC`–`FP2`), language (`IFG`–`AG`), default mode (`PCC`, `mPFC_dmn`, `LP_L/R`), salience/affect (`AI`, `dACC`, `vmPFC`, hippocampus), subcortical (`Amygdala`, `Caudate`, `Putamen`, `Thalamus`). See `config.json` for full list.
+
+## Intended use
+
+- Research prototyping: estimate population-level brain ROI responses to text stimuli
+- Creative tools: text-driven neuroemotion / brain-state visualization pipelines
+- Fast baseline before running the full multimodal V5 encoder
+
+## Limitations
+
+- **Not mind reading.** Outputs are model predictions trained on group fMRI, not measurements of any individual person's thoughts or emotions.
+- **Modest accuracy.** Val mean R ≈ 0.17 — useful for relative comparisons across texts, not clinical or diagnostic use.
+- **Text only.** No image, audio, or video input. Multimodal (image/audio/video) encoding is out of scope for this model.
+- **English-biased.** Trained primarily on English naturalistic narratives; other languages are untested.
+- **Depends on Qwen3.** First run downloads ~8 GB of embedding weights from Hugging Face.
+
+## Quick start
+
+### Colab demo (recommended — no install)
+
+1. Open the [**Colab demo**](https://huggingface.co/ffh92r32rm0/Amphora_NeuroText/colab) (or model page → **Use this model** → **Google Colab**)
+2. Runtime → **Change runtime type** → **GPU** (T4)
+3. Run all cells, type any sentence, click **Predict brain map**
+
+Everything loads from this HF repo (`ffh92r32rm0/Amphora_NeuroText`) — notebook, weights, and helper scripts.
+
+**Commercial-friendly brain viz:** The Colab demo uses **MNE + Nilearn** for fsaverage5 / HCP-MMP plotting (`text2roi_to_fsaverage.py`). It does **not** import tribev2 (CC BY-NC). See `requirements-colab.txt`.
+
+### Local install
+
+**1. Install**
+
+```bash
+pip install torch numpy transformers huggingface_hub
+# or
+pip install -r requirements.txt
+```
+
+**2. Download this model**
+
+```bash
+huggingface-cli download ffh92r32rm0/Amphora_NeuroText text2roi_projector.pt predict.py config.json
+```
+
+Or in Python:
+
+```python
+from huggingface_hub import hf_hub_download
+
+ckpt = hf_hub_download("ffh92r32rm0/Amphora_NeuroText", "text2roi_projector.pt")
+```
+
+**3. Run inference**
+
+CLI:
+
+```bash
+python predict.py --text "a dog running through a sunny park" --device cuda
+```
+
+Python API:
+
+```python
+from predict import predict_text
+from huggingface_hub import hf_hub_download
+
+ckpt = hf_hub_download("ffh92r32rm0/Amphora_NeuroText", "text2roi_projector.pt")
+result = predict_text("a terrifying monster in a dark alley", checkpoint_path=ckpt, device="cuda")
+
+for roi, score in sorted(result["roi_predictions"].items(), key=lambda x: abs(x[1]), reverse=True)[:8]:
+    print(f"{roi:16s} {score:+.4f}")
+```
+
+**Example output:**
+
+```
+LO2              +0.4797
+FFA-2            +0.4387
+V3A              +0.4014
+mPFC_dmn         +0.3215
+V2               +0.3037
+IPS2             +0.2845
+HPC_L            -0.2610
+MST              +0.2586
+```
+
+**4. Load projector weights manually**
+
+```python
+import torch
+from predict import Text2ROI
+
+ckpt = torch.load("text2roi_projector.pt", map_location="cpu", weights_only=False)
+model = Text2ROI(in_dim=ckpt["in_dim"], hidden=ckpt["hidden"], out_dim=ckpt["n_roi"])
+model.load_state_dict(ckpt["state_dict"])
+model.eval()
+
+# embed: (1, 2560) float32 from Qwen3-Embedding-4B
+with torch.no_grad():
+    rois = model(torch.from_numpy(embed)).numpy()  # (1, 56)
+```
+
+## Training
+
+Trained with Pearson-R correlation loss + 0.1× MSE on ~300k (text embedding, ROI target) pairs:
+
+```bash
+python train_text2roi.py \
+  --data /path/to/neurotext_pairs.npz \
+  --out text2roi_projector.pt \
+  --epochs 80 --batch 2048 --lr 3e-4
+```
+
+Train your own projector with Pearson-R loss + 0.1× MSE on `(text embedding, ROI target)` pairs in `.npz` format.
+
+## Evaluation
+
+| Metric | Value |
+|--------|-------|
+| Val mean Pearson R (56 ROIs) | 0.170 |
+| Projector params | 3.18M |
+| Training time | ~5 min (RTX 5080) |
+
+Reproduce on your val split:
+
+```bash
+python infer_text2roi.py --checkpoint text2roi_projector.pt --data neurotext_pairs.npz
+```
+
+## Files in this repo
+
+| File | Description |
+|------|-------------|
+| `text2roi_projector.pt` | Trained MLP weights + metadata |
+| `notebook.ipynb` | **Interactive Colab demo** (opened via `/colab` on the model page) |
+| `text2roi_colab_demo.ipynb` | Same Colab demo (alternate filename) |
+| `text2roi_to_fsaverage.py` | ROI → fsaverage5 mapping + Nilearn plotting (no tribev2) |
+| `predict.py` | Standalone inference script |
+| `config.json` | Model hyperparameters and eval summary |
+| `requirements.txt` | Local Python dependencies |
+| `requirements-colab.txt` | Colab deps (MNE + Nilearn, no tribev2) |
+| `LICENSE` | MIT |
+
+## Citation
+
+```bibtex
+@misc{amphora_neurotext2026,
+  author       = {ffh92r32rm0},
+  title        = {Amphora NeuroText: Text-to-Brain ROI Activation Projector},
+  year         = {2026},
+  publisher    = {Hugging Face},
+  howpublished = {\url{https://huggingface.co/ffh92r32rm0/Amphora_NeuroText}},
+  license      = {MIT}
+}
+```
+
+## Links
+
+- **Model:** https://huggingface.co/ffh92r32rm0/Amphora_NeuroText
+- **Colab demo:** https://huggingface.co/ffh92r32rm0/Amphora_NeuroText/colab
+- **Text encoder:** https://huggingface.co/Qwen/Qwen3-Embedding-4B
+- **Brain visualization:** MNE + Nilearn (fsaverage5 / HCP-MMP1, commercial-friendly)

text2roi_colab_demo.ipynb

@@ -0,0 +1,293 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "# Amphora NeuroText — Colab Demo\n",
+        "\n",
+        "**Type text → predict 56 brain ROI activations → visualize on fsaverage5 cortical maps (MNE + Nilearn).**\n",
+        "\n",
+        "Open this notebook from the [Hugging Face model page](https://huggingface.co/ffh92r32rm0/Amphora_NeuroText) → **Use this model** → **Google Colab**, or go directly to:\n",
+        "\n",
+        "**https://huggingface.co/ffh92r32rm0/Amphora_NeuroText/colab**\n",
+        "\n",
+        "All assets (weights, helper scripts) download from `ffh92r32rm0/Amphora_NeuroText` — no GitHub, no login required.\n",
+        "\n",
+        "Pipeline:\n",
+        "```\n",
+        "text → Qwen3-Embedding-4B → Text2ROI MLP (3M params) → 56 ROI scores → HCP-MMP parcels → fsaverage5 surface\n",
+        "```\n",
+        "\n",
+        "Brain plotting uses **MNE + Nilearn only** (BSD/MIT-friendly) — no tribev2 import (CC BY-NC).\n",
+        "\n",
+        "**Setup:** Runtime → Change runtime type → **GPU** (T4 is enough), then run all cells.\n",
+        "\n",
+        "Model: [ffh92r32rm0/Amphora_NeuroText](https://huggingface.co/ffh92r32rm0/Amphora_NeuroText) · MIT license\n",
+        "\n",
+        "> ⚠️ Predictions are **model estimates** from group fMRI training — not measurements of anyone's private thoughts."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Install dependencies (first run ~5–8 min)\n",
+        "# Commercial-friendly: MNE + Nilearn for brain viz — no tribev2 (CC BY-NC).\n",
+        "import sys\n",
+        "\n",
+        "!{sys.executable} -m pip install -q --upgrade pip\n",
+        "!{sys.executable} -m pip install -q \"torch>=2.3\" \"transformers>=4.44\" huggingface_hub ipywidgets\n",
+        "!{sys.executable} -m pip install -q nilearn mne nibabel scipy matplotlib numpy\n",
+        "\n",
+        "print(\"Deps installed (MNE + Nilearn for fsaverage5 brain maps).\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "import json\n",
+        "from pathlib import Path\n",
+        "\n",
+        "import matplotlib.pyplot as plt\n",
+        "import numpy as np\n",
+        "import torch\n",
+        "import torch.nn as nn\n",
+        "import torch.nn.functional as F\n",
+        "from huggingface_hub import hf_hub_download\n",
+        "from IPython.display import display, clear_output\n",
+        "import ipywidgets as widgets\n",
+        "\n",
+        "HF_REPO = \"ffh92r32rm0/Amphora_NeuroText\"\n",
+        "\n",
+        "DEVICE = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n",
+        "print(f\"Device: {DEVICE}\")\n",
+        "\n",
+        "CKPT_PATH = hf_hub_download(HF_REPO, \"text2roi_projector.pt\")\n",
+        "print(f\"Checkpoint: {CKPT_PATH}\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "ROI_NAMES_56 = [\n",
+        "    \"V1\", \"V2\", \"V3\", \"V4\", \"V3A\", \"V3B\", \"LO1\", \"LO2\",\n",
+        "    \"MT\", \"MST\", \"V7\", \"IPS1\",\n",
+        "    \"FFA-1\", \"FFA-2\", \"PPA\", \"RSC\", \"OFA\", \"EBA\",\n",
+        "    \"IPS2\", \"IPS3\", \"IPS4\", \"IPS5\", \"SPL1\", \"hIP1\", \"hIP2\", \"hIP3\",\n",
+        "    \"dlPFC\", \"vlPFC\", \"OFC\", \"ACC\", \"mPFC\", \"FP1\", \"FP2\",\n",
+        "    \"IFG\", \"IFGorb\", \"STG\", \"STS\", \"MTG\", \"AG\",\n",
+        "    \"PCC\", \"mPFC_dmn\", \"LP_L\", \"LP_R\", \"HPC_L\", \"HPC_R\",\n",
+        "    \"AI\", \"dACC\", \"sgACC\", \"vmPFC\",\n",
+        "    \"Amygdala_L\", \"Amygdala_R\", \"Caudate_L\", \"Caudate_R\",\n",
+        "    \"Putamen_L\", \"Putamen_R\", \"Thalamus\",\n",
+        "]\n",
+        "\n",
+        "class Text2ROI(nn.Module):\n",
+        "    def __init__(self, in_dim=2560, hidden=1024, out_dim=56, dropout=0.1):\n",
+        "        super().__init__()\n",
+        "        self.net = nn.Sequential(\n",
+        "            nn.Linear(in_dim, hidden), nn.GELU(), nn.Dropout(dropout), nn.LayerNorm(hidden),\n",
+        "            nn.Linear(hidden, hidden // 2), nn.GELU(), nn.Dropout(dropout),\n",
+        "            nn.Linear(hidden // 2, out_dim),\n",
+        "        )\n",
+        "    def forward(self, x):\n",
+        "        return self.net(x)\n",
+        "\n",
+        "def load_projector(path):\n",
+        "    ckpt = torch.load(path, map_location=\"cpu\", weights_only=False)\n",
+        "    model = Text2ROI(int(ckpt[\"in_dim\"]), int(ckpt[\"hidden\"]), int(ckpt[\"n_roi\"]))\n",
+        "    model.load_state_dict(ckpt[\"state_dict\"])\n",
+        "    model.to(DEVICE).eval()\n",
+        "    names = [str(x) for x in ckpt.get(\"roi_names\", ROI_NAMES_56)]\n",
+        "    return model, names, ckpt\n",
+        "\n",
+        "PROJECTOR, ROI_NAMES, CKPT_META = load_projector(CKPT_PATH)\n",
+        "print(f\"Loaded Text2ROI v1 — val R={CKPT_META.get('best_val_r', 0):+.3f}, {len(ROI_NAMES)} ROIs\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "QWEN_ID = \"Qwen/Qwen3-Embedding-4B\"\n",
+        "from transformers import AutoModel, AutoTokenizer\n",
+        "\n",
+        "print(\"Loading Qwen3 embedder (first run downloads ~8 GB)...\")\n",
+        "_tok = AutoTokenizer.from_pretrained(QWEN_ID, padding_side=\"left\")\n",
+        "_qwen = AutoModel.from_pretrained(QWEN_ID, dtype=torch.bfloat16).to(DEVICE).eval()\n",
+        "print(\"Qwen3 ready.\")\n",
+        "\n",
+        "@torch.no_grad()\n",
+        "def embed_text(text: str) -> np.ndarray:\n",
+        "    tok = _tok([text], return_tensors=\"pt\", padding=True, truncation=True, max_length=512).to(DEVICE)\n",
+        "    out = _qwen(**tok)\n",
+        "    emb = out.last_hidden_state[:, -1].float()\n",
+        "    emb = F.normalize(emb, p=2, dim=1).cpu().numpy().astype(np.float32)\n",
+        "    return emb\n",
+        "\n",
+        "@torch.no_grad()\n",
+        "def predict_rois(text: str) -> dict:\n",
+        "    x = torch.from_numpy(embed_text(text)).to(DEVICE)\n",
+        "    pred = PROJECTOR(x).cpu().numpy().reshape(-1)\n",
+        "    return {name: float(pred[i]) for i, name in enumerate(ROI_NAMES)}"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "# Map 56 ROI values → fsaverage5 vertices (MNE + Nilearn — no tribev2)\n",
+        "import sys\n",
+        "from pathlib import Path\n",
+        "\n",
+        "_helper = Path(hf_hub_download(HF_REPO, \"text2roi_to_fsaverage.py\"))\n",
+        "sys.path.insert(0, str(_helper.parent))\n",
+        "from text2roi_to_fsaverage import roi_dict_to_fsaverage5, plot_fsaverage5_brain\n",
+        "\n",
+        "print(\"fsaverage5 plotting helpers ready (MNE + Nilearn).\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "def plot_results(text: str, roi_values: dict):\n",
+        "    vertex_map, skipped = roi_dict_to_fsaverage5(roi_values)\n",
+        "\n",
+        "    # --- ROI bar chart ---\n",
+        "    top = sorted(roi_values.items(), key=lambda kv: abs(kv[1]), reverse=True)[:16]\n",
+        "    names = [t[0] for t in top]\n",
+        "    vals = [t[1] for t in top]\n",
+        "    colors = [\"#c44e52\" if v < 0 else \"#4c72b0\" for v in vals]\n",
+        "\n",
+        "    fig, ax = plt.subplots(figsize=(7, 5))\n",
+        "    ax.barh(names[::-1], vals[::-1], color=colors[::-1])\n",
+        "    ax.axvline(0, color=\"#333\", lw=0.8)\n",
+        "    ax.set_title(\"Top ROI predictions\")\n",
+        "    ax.set_xlabel(\"Predicted activation\")\n",
+        "    plt.tight_layout()\n",
+        "    plt.show()\n",
+        "\n",
+        "    # --- fsaverage5 brain maps (Nilearn) ---\n",
+        "    skip_note = f\" — subcortical skipped: {len(skipped)}\" if skipped else \"\"\n",
+        "    plot_fsaverage5_brain(\n",
+        "        vertex_map,\n",
+        "        views=[\"left\", \"right\", \"dorsal\"],\n",
+        "        cmap=\"RdBu_r\",\n",
+        "        threshold=0.02,\n",
+        "        title=f\"fsaverage5 cortical map (HCP-MMP ROIs){skip_note}\",\n",
+        "    )\n",
+        "    plt.show()\n",
+        "\n",
+        "    print(\"\\nTop ROIs:\")\n",
+        "    for n, v in top[:10]:\n",
+        "        print(f\"  {n:<16} {v:+.4f}\")\n",
+        "    if skipped:\n",
+        "        print(f\"\\n(Subcortical / unmapped ROIs not painted on cortex: {', '.join(skipped[:8])}{'…' if len(skipped)>8 else ''})\")"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## Try it — enter text and click **Predict**\n",
+        "\n",
+        "Or use a preset example below."
+      ]
+    },
+    {
+      "cell_type": "code",
+      "metadata": {},
+      "source": [
+        "text_in = widgets.Textarea(\n",
+        "    value=\"a dog running through a sunny park\",\n",
+        "    description=\"Text:\",\n",
+        "    layout=widgets.Layout(width=\"90%\", height=\"80px\"),\n",
+        ")\n",
+        "btn = widgets.Button(description=\"Predict brain map\", button_style=\"primary\", icon=\"play\")\n",
+        "out = widgets.Output()\n",
+        "\n",
+        "PRESETS = {\n",
+        "    \"Sunny park\": \"a dog running through a sunny park\",\n",
+        "    \"Scary scene\": \"a terrifying monster jumps out in a dark alley\",\n",
+        "    \"Romantic\": \"two people sharing a quiet candlelit dinner\",\n",
+        "    \"Math puzzle\": \"solving a difficult calculus proof step by step\",\n",
+        "}\n",
+        "preset_btns = [widgets.Button(description=k, layout=widgets.Layout(width=\"140px\")) for k in PRESETS]\n",
+        "\n",
+        "def _on_preset(btn):\n",
+        "    text_in.value = PRESETS[btn.description]\n",
+        "\n",
+        "for b in preset_btns:\n",
+        "    b.on_click(_on_preset)\n",
+        "\n",
+        "def _on_predict(_):\n",
+        "    with out:\n",
+        "        clear_output(wait=True)\n",
+        "        text = text_in.value.strip()\n",
+        "        if not text:\n",
+        "            print(\"Enter some text first.\")\n",
+        "            return\n",
+        "        print(f\"Predicting for: {text!r} …\")\n",
+        "        rois = predict_rois(text)\n",
+        "        plot_results(text, rois)\n",
+        "\n",
+        "btn.on_click(_on_predict)\n",
+        "\n",
+        "display(widgets.VBox([\n",
+        "    text_in,\n",
+        "    widgets.HBox([btn] + preset_btns),\n",
+        "    out,\n",
+        "]))"
+      ],
+      "execution_count": null,
+      "outputs": []
+    },
+    {
+      "cell_type": "markdown",
+      "metadata": {},
+      "source": [
+        "## What the output means\n",
+        "\n",
+        "| Output | Description |\n",
+        "|--------|-------------|\n",
+        "| **Bar chart** | Top 16 of 56 ROI activation scores (positive = predicted up-regulation) |\n",
+        "| **Brain surface** | ROI values painted onto **fsaverage5** via HCP-MMP1 parcels (MNE + Nilearn) |\n",
+        "| **Skipped ROIs** | Subcortical regions (amygdala, striatum, thalamus) are not on the cortical surface |\n",
+        "\n",
+        "**Model:** [ffh92r32rm0/Amphora_NeuroText](https://huggingface.co/ffh92r32rm0/Amphora_NeuroText)"
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "provenance": [],
+      "gpuType": "T4"
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    },
+    "accelerator": "GPU"
+  },
+  "nbformat": 4,
+  "nbformat_minor": 5
+}