example_notebooks/fanc_python_package_examples.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "6fac85c8",
   "metadata": {},
   "source": [
    "## Examples of using functions in the [`fanc` python package](https://github.com/htem/FANC_auto_recon/tree/main/fanc).\n",
    "\n",
    "Before starting, be sure you've followed the [installation instructions](https://github.com/htem/FANC_auto_recon#installing-and-configuring-the-fanc-python-package)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d2490404",
   "metadata": {},
   "outputs": [],
   "source": [
    "import fanc"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "82573dcc",
   "metadata": {},
   "source": [
    "Let's look up the latest segment ID for the FANC homepage neuron by giving the homepage point coordinate to `fanc.lookup.segid_from_pt()`.  \n",
    "(See [Neuroglancer states for proofreading](https://github.com/htem/FANC_auto_recon/wiki/Neuroglancer-states-for-proofreading) for the \"homepage\" neuroglancer state which shows this neuron/coordinate.)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4a519118",
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime, timezone\n",
    "now = datetime.utcnow()\n",
    "\n",
    "homepage_neuron_segid = fanc.lookup.segid_from_pt([48848, 114737, 2690], timestamp=now)\n",
    "# This should give 648518346486614449 as of July 30, 2023\n",
    "print('Homepage neuron segid:', homepage_neuron_segid)\n",
    "\n",
    "# Look up the entry in the soma table for this neuron\n",
    "homepage_neuron_soma = fanc.lookup.soma_from_segid(homepage_neuron_segid, timestamp=now)\n",
    "print('Homepage neuron soma info:')\n",
    "homepage_neuron_soma"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "df813a3b",
   "metadata": {},
   "source": [
    "### 3D rendering\n",
    "Let's display some FANC neurons aligned to the VNC template.\n",
    "\n",
    "To use `fanc.plot_neurons()` with the default setting of `template_space='JRC2018_VNC_FEMALE'`, you will need to have done the optional elastix/transformix setup steps during installation. If you skipped those steps, you can specify `template_space=None` when calling `fanc.plot_neurons()` to see the neuron in FANC-space instead of being template-aligned.\n",
    "\n",
    "This function will generate a popup window that you can interact with (rotate around, etc). When you're done, press Q while the popup window is selected to allow your notebook to continue."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6e336de5",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Show a 3D render of the neuron aligned to the template space, with FANC outlines displayed\n",
    "# Note that `template_space='JRC2018_VNC_FEMALE'` is the default behavior, just specifying it here for clarity\n",
    "fanc.plot_neurons(homepage_neuron_segid, show_outlines=True, template_space='JRC2018_VNC_FEMALE')\n",
    "# You can skip warping into alignment with the template if you haven't set up elastix:\n",
    "#fanc.plot_neurons(homepage_neuron_segid, show_outlines=True, template_space=None)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e52530b3",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Check the docstring for many more options\n",
    "fanc.plot_neurons?"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4bf245cb",
   "metadata": {},
   "outputs": [],
   "source": [
    "# which might lead you to notice the `save` option, which can\n",
    "# be used to save publication-ready images of your neurons\n",
    "fanc.plot_neurons(homepage_neuron_segid,\n",
    "                  show_outlines=True,\n",
    "                  template_space='JRC2018_VNC_FEMALE',\n",
    "                  save=True,\n",
    "                  save_path=f'./output/plot_neuron_{homepage_neuron_segid}.png')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6683d386",
   "metadata": {},
   "source": [
    "The result should look like this (yes, sorry, it's upside down by default):  \n",
    "<img width=\"640\" align=\"left\" src=\"output/plot_neuron_648518346481082458.png\" >"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ff15a134",
   "metadata": {},
   "source": [
    "### Interacting with data in CAVE tables"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cefb2bb1",
   "metadata": {},
   "outputs": [],
   "source": [
    "# The following is a simpler alternative to `client = CAVEclient('fanc_production_mar2021')`\n",
    "client = fanc.get_caveclient()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ad3f60ed",
   "metadata": {},
   "source": [
    "You can now do all the usual fun things that CAVEclient lets you do, like query for synapses.\n",
    "\n",
    "Let's pull some synapses, then use `fanc.synaptic_links.to_ng_annotations()` to copy these synaptic links to the clipboard in a format that can be pasted into a neuroglancer annotation layer."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1f072853",
   "metadata": {},
   "outputs": [],
   "source": [
    "homepage_neuron_output_synapses = client.materialize.synapse_query(pre_ids=homepage_neuron_segid)\n",
    "\n",
    "fanc.synaptic_links.to_ng_annotations(homepage_neuron_output_synapses)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "056213e8",
   "metadata": {},
   "source": [
    "I then went to neuroglancer, made an annotation layer, then opened up the neuroglancer state using the `{}` button, went into `\"layers\"`, went to the annotation layer (the last one), and pasted my clipboard contents into the `\"annotations\": ` line, replacing the existing `[]`.\n",
    "\n",
    "That gave me this neuroglancer state, showing all the output synapses from the homepage neuron https://neuromancer-seung-import.appspot.com/?json_url=https://global.daf-apis.com/nglstate/api/v1/5212944610623488.\n",
    "\n",
    "A quick exercise: How would you make a state just like this, except with all the inputs to the homepage neuron (instead of its outputs)?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "972fd824",
   "metadata": {},
   "source": [
    "### Programmatically generate neuroglancer scenes showing certain types of neurons\n",
    "\n",
    "[`nglui`](https://github.com/seung-lab/NeuroglancerAnnotationUI) is a package to facilitate programmatically making neuroglancer scenes. We wrote `fanc.statebuilder.render_scene()` which uses `nglui` to build neuroglancer scenes relevant for FANC. For instance, you can generate the default FANC scene via:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3c8e2d81",
   "metadata": {},
   "outputs": [],
   "source": [
    "fanc.statebuilder.render_scene()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2456f190",
   "metadata": {},
   "source": [
    "You can customize this scene in a number of ways. Check the docstring for lots of info:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9c21f77e",
   "metadata": {},
   "outputs": [],
   "source": [
    "fanc.statebuilder.render_scene?"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2f4ae78a",
   "metadata": {},
   "source": [
    "The main argument here is `neurons`, where you can specify some set of neurons to display. For instance, specify the name of a CAVE table to bring up all the neurons labeled by that table:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4bcd1250",
   "metadata": {},
   "outputs": [],
   "source": [
    "fanc.statebuilder.render_scene(neurons=fanc.lookup.cells_annotated_with('neck motor neuron'))\n",
    "# This should give a state showing the 24 neck motor neurons in FANC"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "aeeb7caf",
   "metadata": {},
   "source": [
    "For more flexibility, pull data from a table yourself, do some processing, then generate the scene:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "11ebde2d",
   "metadata": {},
   "outputs": [],
   "source": [
    "front_leg_mns = client.materialize.query_table('motor_neuron_table_v7')\n",
    "\n",
    "# Pull out some subset of the motor neurons that we might be interested in\n",
    "accessory_nerve_mns = front_leg_mns.loc[front_leg_mns.classification_system.str.startswith('A')]\n",
    "ventral_nerve_mns = front_leg_mns.loc[front_leg_mns.classification_system.str.startswith('V')]\n",
    "\n",
    "fanc.statebuilder.render_scene(neurons=accessory_nerve_mns)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cfaec9aa",
   "metadata": {},
   "source": [
    "The `render_scene()` command above gave me https://neuromancer-seung-import.appspot.com/?json_url=https://global.daf-apis.com/nglstate/api/v1/5373044079984640"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3226be59",
   "metadata": {},
   "source": [
    "### More info\n",
    "The majority of the functions in this package have decent docstrings. By [looking through the package's modules](https://github.com/htem/FANC_auto_recon/tree/main/fanc) you can find more functions that may be useful to you.\n",
    "\n",
    "Please also feel free to post questions on the [#code channel](https://fanc-reconstruction.slack.com/archives/CLE1R5048/p1671568387097929) on the FANC Slack, or [open an issue](https://github.com/htem/FANC_auto_recon/issues) on GitHub."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.15"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}