{
   "cells": [
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "Data caching\n",
            "------------\n",
            "\n",
            "To speed up reoccurring queries to the server, pymaid lets you cache data. This behaviour is by default switched on:"
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 1,
         "metadata": {},
         "outputs": [
            {
               "name": "stderr",
               "output_type": "stream",
               "text": [
                  "INFO  : Global CATMAID instance set. (pymaid)\n"
               ]
            }
         ],
         "source": [
            "import pymaid \n",
            "rm = pymaid.connect_catmaid()"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "Query for a neuron for the first time:"
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 2,
         "metadata": {},
         "outputs": [
            {
               "name": "stdout",
               "output_type": "stream",
               "text": [
                  "CPU times: user 146 ms, sys: 10.6 ms, total: 156 ms\n",
                  "Wall time: 1.01 s\n"
               ]
            }
         ],
         "source": [
            "%time n = pymaid.get_neuron(16)"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "Query for the same neuron a second time:"
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 3,
         "metadata": {},
         "outputs": [
            {
               "name": "stderr",
               "output_type": "stream",
               "text": [
                  "INFO  : Cached data used. (pymaid)\n",
                  "INFO  : Cached data used. (pymaid)\n"
               ]
            },
            {
               "name": "stdout",
               "output_type": "stream",
               "text": [
                  "CPU times: user 128 ms, sys: 6.77 ms, total: 135 ms\n",
                  "Wall time: 146 ms\n"
               ]
            }
         ],
         "source": [
            "%time n2 = pymaid.get_neuron(16)"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "For the second query cached data was used which gives us almost a 10x speed-up. \n",
            "\n",
            "Fine-tuning the cache\n",
            "=====================\n",
            "\n",
            "You can restrict the usage of cached data either by size to prevent running out of memory or by time to discard old data:"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "Caching is a property of the :class:`~pymaid.CatmaidInstance` you are using. Here, we are changing max memory used to 256 megabytes (default is 128mb) and to a max age of 15min (= 900s; no limit by default):"
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 4,
         "metadata": {},
         "outputs": [],
         "source": [
            "rm.setup_cache(size_limit=128, time_limit=900)"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "You can inspect the size of your current cache [mb]:"
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 5,
         "metadata": {},
         "outputs": [
            {
               "data": {
                  "text/plain": [
                     "0.8"
                  ]
               },
               "execution_count": 5,
               "metadata": {},
               "output_type": "execute_result"
            }
         ],
         "source": [
            "rm.cache_size"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "You can also clear the cache:"
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 6,
         "metadata": {},
         "outputs": [
            {
               "data": {
                  "text/plain": [
                     "0.0"
                  ]
               },
               "execution_count": 6,
               "metadata": {},
               "output_type": "execute_result"
            }
         ],
         "source": [
            "rm.clear_cache()\n",
            "rm.cache_size"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "Switching off caching can either be done when initializing the :class:`~pymaid.CatmaidInstance`..."
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 7,
         "metadata": {},
         "outputs": [],
         "source": [
            "rm = pymaid.CatmaidInstance('server_url', 'api_token', 'http_user', 'http_password', caching=False)"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "... or by changing the according attribute on the go:"
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 8,
         "metadata": {},
         "outputs": [],
         "source": [
            "rm.caching = False"
         ]
      },
      {
         "cell_type": "raw",
         "metadata": {
            "raw_mimetype": "text/restructuredtext"
         },
         "source": [
            "Saving cache\n",
            "============\n",
            "\n",
            "Imagine running some analysis: What if you want to preserve the exact data that was used for that analysis? You can save the cache into a separate file and restore it later:"
         ]
      },
      {
         "cell_type": "code",
         "execution_count": 9,
         "metadata": {},
         "outputs": [
            {
               "name": "stderr",
               "output_type": "stream",
               "text": [
                  "INFO  : Cached data used. (pymaid)\n",
                  "INFO  : Cached data used. (pymaid)\n"
               ]
            }
         ],
         "source": [
            "n = pymaid.get_neuron(16)\n",
            "rm.save_cache('cache.pickle')\n",
            "\n",
            "rm.clear_cache()\n",
            "rm.load_cache('cache.pickle')\n",
            "\n",
            "n = pymaid.get_neuron(16)"
         ]
      }
   ],
   "metadata": {
      "celltoolbar": "Raw Cell Format",
      "kernelspec": {
         "display_name": "Python 3",
         "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.7.5"
      }
   },
   "nbformat": 4,
   "nbformat_minor": 2
}