{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "059053f4",
   "metadata": {},
   "source": [
    "# Neurolucida ASC\n",
    "\n",
    "The Neurolucida ASCII format (`.asc`), produced by MBF Bioscience's Neurolucida\n",
    "tracing software, stores morphologies as nested S-expressions with rich\n",
    "metadata (spines, markers, contours). `braincell` reads it through\n",
    "{class}`braincell.io.AscReader`.\n",
    "\n",
    "## Loading"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ebfd68ab",
   "metadata": {},
   "outputs": [],
   "source": [
    "import braincell\n",
    "\n",
    "morpho = braincell.Morphology.from_asc(\"neuron.asc\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b5facfb",
   "metadata": {},
   "source": [
    "As with SWC, you can request a validation report:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b435a1ee",
   "metadata": {},
   "outputs": [],
   "source": [
    "morpho, report = braincell.Morphology.from_asc(\"neuron.asc\", return_report=True)\n",
    "print(report)   # AscReport: issues found and metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bdd3b01b",
   "metadata": {},
   "source": [
    "## What the reader captures\n",
    "\n",
    "The ASC reader understands the format's richer structure than SWC:\n",
    "\n",
    "- typed branches (soma, axon, basal/apical dendrite) → `braincell` branch types;\n",
    "- {class}`~braincell.io.AscSpineRecord` — dendritic spine annotations;\n",
    "- {class}`~braincell.io.AscMetadata` — file-level metadata;\n",
    "- {class}`~braincell.io.AscReport` / {class}`~braincell.io.AscIssue` — the\n",
    "  validation report and any problems encountered.\n",
    "\n",
    "## Lower-level reader"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84b22231",
   "metadata": {},
   "outputs": [],
   "source": [
    "from braincell.io import AscReader\n",
    "\n",
    "reader = AscReader()\n",
    "morpho = reader.read(\"neuron.asc\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "570aeca3",
   "metadata": {},
   "source": [
    "See {doc}`../apis/io` for the full ASC API. For the simpler, more portable\n",
    "format, see {doc}`swc`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "name": "python"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}