{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "df823aae",
   "metadata": {},
   "source": [
    "# Morphology\n",
    "\n",
    "A *morphology* is the geometry of a neuron: the branching tree of cable\n",
    "segments, each with a length, radius, and position in space. In `braincell`\n",
    "this is represented by {class}`braincell.Morphology`, built from\n",
    "{class}`braincell.Branch` segments.\n",
    "\n",
    "A morphology is required only for multi-compartment {class}`~braincell.Cell`\n",
    "models. Single-compartment models have no geometry.\n",
    "\n",
    "## The pieces\n",
    "\n",
    "```{list-table}\n",
    ":header-rows: 1\n",
    ":widths: 28 72\n",
    "\n",
    "* - Object\n",
    "  - Role\n",
    "* - {class}`braincell.Branch`\n",
    "  - An **immutable** geometric cable segment: sample points (x, y, z, radius)\n",
    "    and the topology connecting them. Typed subclasses tag what part of the\n",
    "    neuron a branch is.\n",
    "* - {class}`braincell.Morphology`\n",
    "  - The **tree** of branches with parent/child connectivity. The object you\n",
    "    pass to {class}`~braincell.Cell`.\n",
    "```\n",
    "\n",
    "### Typed branches\n",
    "\n",
    "Branches carry a *type* so that mechanisms can target anatomically meaningful\n",
    "regions (\"paint sodium channels on the soma\"). The built-in types are:\n",
    "\n",
    "- {class}`~braincell.Soma`\n",
    "- {class}`~braincell.Dendrite`, with {class}`~braincell.BasalDendrite` and\n",
    "  {class}`~braincell.ApicalDendrite`\n",
    "- {class}`~braincell.Axon`\n",
    "- {class}`~braincell.CustomBranch` for anything else\n",
    "\n",
    "These map onto the standard SWC structure identifiers, so loading an SWC file\n",
    "assigns types automatically.\n",
    "\n",
    "## Where morphologies come from\n",
    "\n",
    "You almost never type coordinates by hand. Instead you load a reconstruction:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "01effda6",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell\n",
    "\n",
    "# from a local SWC file\n",
    "morpho = braincell.Morphology.from_swc(\"neuron.swc\")\n",
    "\n",
    "# from a Neurolucida ASC file\n",
    "morpho = braincell.Morphology.from_asc(\"neuron.asc\")\n",
    "\n",
    "# directly from NeuroMorpho.Org (downloaded and cached)\n",
    "morpho = braincell.Morphology.from_neuromorpho(\"cnic_001\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e4b7ca6",
   "metadata": {},
   "source": [
    "See {doc}`../file_formats/index` for the full set of readers, reader options,\n",
    "and validation reports.\n",
    "\n",
    "## Inspecting and visualizing\n",
    "\n",
    "Once loaded, a morphology can be explored and rendered:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "967368fb",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell.vis as vis\n",
    "\n",
    "vis.plot2d(morpho)   # 2-D dendrogram / tree layout (matplotlib)\n",
    "vis.plot3d(morpho)   # 3-D rendering (PyVista or Plotly)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2ad85f8",
   "metadata": {},
   "source": [
    "The {mod}`braincell.vis` layer also provides morphometry plots (Sholl analysis,\n",
    "branch-order histograms, topology) — see the {doc}`../apis/vis` reference.\n",
    "\n",
    "## The mutable analysis tree (`braincell.morph`)\n",
    "\n",
    "{class}`braincell.Morphology` is the immutable object you simulate. For\n",
    "programmatic construction and analysis there is a richer, mutable tree in\n",
    "{mod}`braincell.morph`:\n",
    "\n",
    "- {class}`~braincell.morph.MorphoBranch` / {class}`~braincell.morph.MorphoEdge`\n",
    "  — editable branch and edge views.\n",
    "- {class}`~braincell.morph.MorphoMetric` — a whole-morphology metric snapshot\n",
    "  (total length, surface area, branch counts, …).\n",
    "\n",
    "Use {mod}`braincell.morph` when you need to *modify* or *measure* a\n",
    "reconstruction; use {class}`~braincell.Morphology` when you are ready to build a\n",
    "cell.\n",
    "\n",
    "## See also\n",
    "\n",
    "- {doc}`discretization` — how the continuous geometry becomes control volumes.\n",
    "- {doc}`regions_locsets` — selecting parts of a morphology to decorate.\n",
    "- {doc}`../file_formats/index` — loading and saving morphologies."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}