{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "7ae51569",
   "metadata": {},
   "source": [
    "# IO Overview\n",
    "\n",
    "Loading a morphology is almost always a one-liner using a\n",
    "`Morphology.from_*` constructor. Each reader parses a file (or a downloaded\n",
    "record), validates it, and returns a {class}`braincell.Morphology` ready to wrap\n",
    "in a {class}`~braincell.Cell`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1034114f",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell\n",
    "\n",
    "morpho = braincell.Morphology.from_swc(\"neuron.swc\")\n",
    "morpho = braincell.Morphology.from_asc(\"neuron.asc\")\n",
    "morpho = braincell.Morphology.from_neuromorpho(12345)   # NeuroMorpho.Org neuron id"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2376828b",
   "metadata": {},
   "source": [
    "## Validation reports\n",
    "\n",
    "Reconstructions are messy: disconnected points, missing soma, unknown structure\n",
    "identifiers. Instead of failing on the first problem (or silently guessing),\n",
    "the SWC reader can hand back a **report** describing what it found and fixed.\n",
    "Pass `return_report=True`:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28eb6f30",
   "metadata": {},
   "outputs": [],
   "source": [
    "morpho, report = braincell.Morphology.from_swc(\"messy.swc\", return_report=True)\n",
    "print(report)        # SwcReport: issues, fixes applied, summary"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a341a51b",
   "metadata": {},
   "source": [
    "The report types ({class}`~braincell.io.SwcReport`,\n",
    "{class}`~braincell.io.SwcIssue`, and the ASC equivalents) let you decide\n",
    "programmatically whether a reconstruction is clean enough to trust.\n",
    "\n",
    "## Reader options\n",
    "\n",
    "Readers accept an options object to control validation strictness. For SWC,\n",
    "{class}`~braincell.io.SwcReadOptions` controls things like:\n",
    "\n",
    "- `standardize_safe_fixes` — automatically apply safe corrections;\n",
    "- `unknown_type_as_custom` — map unrecognized structure ids to\n",
    "  {class}`~braincell.CustomBranch` instead of erroring;\n",
    "- `require_root_type_soma` — enforce that the root is a soma."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "960f9371",
   "metadata": {},
   "outputs": [],
   "source": [
    "from braincell.io import SwcReadOptions\n",
    "\n",
    "opts = SwcReadOptions(unknown_type_as_custom=True)\n",
    "morpho = braincell.Morphology.from_swc(\"neuron.swc\", options=opts)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "355f7d06",
   "metadata": {},
   "source": [
    "## Saving and reloading\n",
    "\n",
    "To persist a `braincell` morphology (after editing, say) and reload it later,\n",
    "use the checkpoint helpers — see {doc}`checkpointing`.\n",
    "\n",
    "## Where to go next\n",
    "\n",
    "- {doc}`swc` · {doc}`asc` · {doc}`neuroml2` — per-format details.\n",
    "- {doc}`neuromorpho` — searching and downloading from NeuroMorpho.Org.\n",
    "- {doc}`../concepts/morphology` — what a morphology *is*, once loaded."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}