{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "48f638c3",
   "metadata": {},
   "source": [
    "# SWC\n",
    "\n",
    "[SWC](https://swc-specification.readthedocs.io/) is the most widely used\n",
    "morphology format: a plain-text table where each row is a sample point with an\n",
    "id, a structure type, `(x, y, z)` coordinates, a radius, and a parent id. It is\n",
    "the default export of most reconstruction tools and the primary download format\n",
    "on NeuroMorpho.Org.\n",
    "\n",
    "## Loading"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bc443205",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell\n",
    "\n",
    "morpho = braincell.Morphology.from_swc(\"neuron.swc\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5c0938bc",
   "metadata": {},
   "source": [
    "`from_swc` accepts:\n",
    "\n",
    "- `path` — the file to read.\n",
    "- `options` — a {class}`~braincell.io.SwcReadOptions` controlling validation.\n",
    "- `mode` — a named validation preset.\n",
    "- `return_report` — when `True`, also return an {class}`~braincell.io.SwcReport`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f83b6202",
   "metadata": {},
   "outputs": [],
   "source": [
    "morpho, report = braincell.Morphology.from_swc(\"neuron.swc\", return_report=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5f07042d",
   "metadata": {},
   "source": [
    "## Structure types\n",
    "\n",
    "SWC structure identifiers map onto `braincell`'s typed branches:\n",
    "\n",
    "| SWC id | Structure | braincell type |\n",
    "|--------|-----------|----------------|\n",
    "| 1 | soma | {class}`~braincell.Soma` |\n",
    "| 2 | axon | {class}`~braincell.Axon` |\n",
    "| 3 | (basal) dendrite | {class}`~braincell.BasalDendrite` |\n",
    "| 4 | apical dendrite | {class}`~braincell.ApicalDendrite` |\n",
    "| other | custom | {class}`~braincell.CustomBranch` |\n",
    "\n",
    "So once an SWC file is loaded, region selectors like\n",
    "`branch_in(\"type\", \"soma\")` work immediately (see\n",
    "{doc}`../concepts/regions_locsets`).\n",
    "\n",
    "## Validation options\n",
    "\n",
    "{class}`~braincell.io.SwcReadOptions` controls how forgiving the reader is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dd0c9055",
   "metadata": {},
   "outputs": [],
   "source": [
    "from braincell.io import SwcReadOptions\n",
    "\n",
    "opts = SwcReadOptions(\n",
    "    standardize_safe_fixes=True,   # apply safe automatic corrections\n",
    "    unknown_type_as_custom=True,   # don't error on unknown structure ids\n",
    "    require_root_type_soma=False,  # allow non-soma roots\n",
    ")\n",
    "morpho = braincell.Morphology.from_swc(\"neuron.swc\", options=opts)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3253b064",
   "metadata": {},
   "source": [
    "## The lower-level reader\n",
    "\n",
    "`Morphology.from_swc` is a convenience wrapper over\n",
    "{class}`braincell.io.SwcReader`, which you can use directly when you want to\n",
    "*check* a file without building a morphology:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d52416cb",
   "metadata": {},
   "outputs": [],
   "source": [
    "from braincell.io import SwcReader\n",
    "\n",
    "reader = SwcReader()\n",
    "report = reader.check(\"neuron.swc\")   # validate only\n",
    "morpho = reader.read(\"neuron.swc\")    # parse to a Morphology"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "12c88d12",
   "metadata": {},
   "source": [
    "See {doc}`../apis/io` for the full reader, options, and report API."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}