{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3feebe87",
   "metadata": {},
   "source": [
    "# NeuroMorpho.Org\n",
    "\n",
    "[NeuroMorpho.Org](https://neuromorpho.org) is the largest public repository of\n",
    "digitally reconstructed neurons — over 250,000 cells from hundreds of labs.\n",
    "`braincell` ships a full client that searches, downloads, **caches**, and parses\n",
    "these reconstructions into ready-to-use morphologies.\n",
    "\n",
    "The client requires the IO extra:\n",
    "\n",
    "```bash\n",
    "pip install -U braincell[io]\n",
    "```\n",
    "\n",
    "## One-liner: load a neuron by id\n",
    "\n",
    "The simplest path is to load a neuron directly by its NeuroMorpho id. The file\n",
    "is downloaded once and cached locally, so subsequent calls are instant:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ac192220",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell\n",
    "\n",
    "morpho = braincell.Morphology.from_neuromorpho(12345)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e6c811d1",
   "metadata": {},
   "source": [
    "Equivalently, via the IO module entry point:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "03baa491",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell.io as io\n",
    "\n",
    "morpho = io.load_neuromorpho(12345)\n",
    "\n",
    "# also get the validation report\n",
    "morpho, report = io.load_neuromorpho(12345, return_report=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff8b1ab2",
   "metadata": {},
   "source": [
    "```{note}\n",
    "The argument is the **integer neuron id** from NeuroMorpho.Org (the number in a\n",
    "neuron's URL), not its name.\n",
    "```\n",
    "\n",
    "## Searching the repository\n",
    "\n",
    "To find neurons matching criteria, use the\n",
    "{class}`~braincell.io.NeuroMorphoClient`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ed57b6b1",
   "metadata": {},
   "outputs": [],
   "source": [
    "from braincell.io import NeuroMorphoClient\n",
    "\n",
    "client = NeuroMorphoClient()\n",
    "\n",
    "# iterate search results (species, brain region, cell type, …)\n",
    "for neuron in client.iter_search(species=\"mouse\", brain_region=\"neocortex\"):\n",
    "    print(neuron.neuron_id, neuron.neuron_name)\n",
    "\n",
    "# describe a single neuron\n",
    "detail = client.get_neuron(12345)\n",
    "\n",
    "# download its reconstruction file(s)\n",
    "record = client.download(12345)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6851d5a2",
   "metadata": {},
   "source": [
    "Search and query construction are typed through\n",
    "{class}`~braincell.io.NeuroMorphoQuery` and return rich models\n",
    "({class}`~braincell.io.NeuroMorphoNeuron`,\n",
    "{class}`~braincell.io.NeuroMorphoMeasurement`,\n",
    "{class}`~braincell.io.NeuroMorphoSearchPage`).\n",
    "\n",
    "## Downloading without parsing\n",
    "\n",
    "To fetch raw files (standard and/or original SWC) without immediately building a\n",
    "morphology:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4fba4333",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell.io as io\n",
    "\n",
    "record = io.fetch_neuromorpho(12345, mode=\"both\")   # 'standard' | 'original' | 'both'\n",
    "print(record)   # NeuroMorphoDownloadRecord: what was written where"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "842b3ea5",
   "metadata": {},
   "source": [
    "## Caching\n",
    "\n",
    "Downloads are cached under a user cache directory\n",
    "(`braincell.io.DEFAULT_USER_CACHE_DIR`) and managed by\n",
    "{class}`~braincell.io.NeuroMorphoCache`. You can point any entry point at a\n",
    "custom location with `cache_dir=...`, and inspect cache state through the\n",
    "client's `get_cache_status`.\n",
    "\n",
    "## Command-line interface\n",
    "\n",
    "The client is also exposed as a CLI, `braincell-neuromorpho`, for searching and\n",
    "downloading from a shell:\n",
    "\n",
    "```bash\n",
    "braincell-neuromorpho --help\n",
    "```\n",
    "\n",
    "## See also\n",
    "\n",
    "- {doc}`../concepts/morphology` — what you get back.\n",
    "- {doc}`../apis/io` — the complete NeuroMorpho client API."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}