examples/advanced_tutorial.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![The glorious BrainIndexer logo](img/brain_indexer_logo.png)\n",
    "# BrainIndexer Advanced Tutorial with Jupyter Notebook"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Introduction\n",
    "\n",
    "If you're here and you haven't followed the previous tutorial `basic_tutorial.ipynb` maybe you should. It will give you the basics to understand what's going on here.\n",
    "\n",
    "Or don't do it, I won't force you, I'm not your boss."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Advanced usage\n",
    "### Multi-indexing\n",
    "\n",
    "If you have a huge circuit to index, you can resort to multi-indexing in order to index the big circuit faster. This techniques splits the whole circuit in multiple subtrees that can be processed in parallel using MPI. \n",
    "\n",
    "To do so you can create a multi-index object like this:\n",
    "\n",
    "**Keep in mind that this and the following code won't work directly in this Jupyter notebook due to the necessity of MPI support. You can create a script with this code and run it using the usual `srun -n3` for example.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import brain_indexer\n",
    "from brain_indexer import MorphMultiIndexBuilder\n",
    "\n",
    "CIRCUIT_2K = \"/gpfs/bbp.cscs.ch/project/proj12/spatial_index/v4/circuit-2k\"\n",
    "NODE_FILE = CIRCUIT_2K + \"/nodes.h5\"\n",
    "MORPH_FILE = CIRCUIT_2K + \"/morphologies/ascii\"\n",
    "\n",
    "OUTPUT_DIR = \"multi_index_2k\"\n",
    "\n",
    "MorphMultiIndexBuilder.from_sonata_file(\n",
    "    MORPH_FILE,\n",
    "    NODE_FILE,\n",
    "    \"All\",\n",
    "    output_dir=OUTPUT_DIR,\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We're specifying the same circuit files as the `basic_tutorial.ipynb` notebook and then also supplying a folder that will contain all the subtrees that are generated. \n",
    "\n",
    "Once this process is complete, you can load the generated index using the `open_index` method of the `MorphMultiIndexBuilder` class, specifying the output folder of the previous execution. You can also optionally specify the amount of memory to allocate for loading the index using the `max_cache_size_mb` parameter which is the amount of memory to allocate to load the index expressed in megabytes.\n",
    "\n",
    "You can then perform normal queries like on the usual index."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# The index may use at most roughly 1e6 bytes.\n",
    "index = brain_indexer.open_index(OUTPUT_DIR, max_cache_size_mb=1000)\n",
    "\n",
    "min_corner = [0, 0, 0]\n",
    "max_corner = [30, 30, 30]\n",
    "\n",
    "found = index.box_query(min_corner, max_corner)\n",
    "print(found)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This concludes the advanced tutorial. You now have all the tools, basics and advanced, to use BrainIndexer.\n",
    "\n",
    "**Thanks a lot for your time and for making until the end of this tutorial. 🎉🎉🎉**\n",
    "\n",
    "The BrainIndexer team hopes that this tool will make your life easier, lead to better results but mostly that you'll have fun with it as much as we had fun creating it!\n",
    "\n",
    "**Disclaimer:** This tool is not meant to be fun but we have no right of deciding what's fun and what's not so, yeah, we just hope you don't hate it. And if you do, please let us know, kindly, and we'll do our best to improve it. Swearing is NEVER the answer."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3.9.7 ('venv': venv)",
   "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.7"
  },
  "orig_nbformat": 4,
  "vscode": {
   "interpreter": {
    "hash": "3e114e1f4fb82502fa733e8f3ebf0a137e266fe56a980e57b18e4ea32cca23c2"
   }
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}