{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Configuring\n",
    "Besides being super convenient, ahlive is super customizable."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### keywords\n",
    "Common settings can be accessed through documented keywords.\n",
    "\n",
    "For a list of documented keywords, see `help(ah.Array)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "ah.Array([0, 1, 2], [3, 4, 5], figsize=(3, 3)).render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "Do not expect all the keywords exposed in ahlive to match the matplotlib keywords!\n",
    "    \n",
    "This is because some keywords are too generic in matplotlib, e.g. `plt.margins(x=1)` is exposed as `xmargins=1`\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Any keywords not documented are assumed to be `plot` keywords.\n",
    "\n",
    "For example in vanilla matplotlib, to change the marker type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "_ = plt.scatter([0], [3], marker='o')\n",
    "_ = plt.scatter([1], [4], marker='^')\n",
    "_ = plt.scatter([2], [5], marker='v')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here, although `marker` is not documented in ahlive's docstring, it can still be used."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "ah.Array([0, 1, 2], [3, 4, 5], marker=['o', '^', 'v']).render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "These `plot` keywords can be a scalar too."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "ah.Array([0, 1, 2], [3, 4, 5], marker='^').render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### config\n",
    "However, because matplotlib is huge, not all keywords can be exposed. Instead, ahlive has a generic `config` method.\n",
    "\n",
    "To set `figsize` without the built-in keyword, first pass the name of the method followed by the keyword arguments.\n",
    "\n",
    "For example, to set `figsize` in vanilla matplotlib:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "_ = plt.figure(figsize=(3, 3))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The method is `figure` so that will be the first positional argument passed to `config`, and then the keyword argument is `figsize=(3, 3)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "arr = ah.Array([0, 1, 2], [3, 4, 5])\n",
    "arr.config('figure', figsize=(3, 3)).render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or another way of doing this is to pass a nested dictionary; this way, multiple methods can be configured simultaneously."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "arr = ah.Array([0, 1, 2], [3, 4, 5])\n",
    "arr.config(**{\n",
    "    'figure': {'figsize': (3, 3)},\n",
    "    'axes': {'xlim': [0, 4], 'ylim': [0, 10]}\n",
    "}).render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However not all methods are named exactly as their matplotlib counterpart!\n",
    "\n",
    "For example to set `color` in vanilla matplotlib:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import matplotlib.pyplot as plt\n",
    "plt.scatter([0, 1, 2], [3, 4, 5], color='red')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The method is not `scatter` in ahlive, instead it's `plot`! This is so that ahlive can handle `plot`, `scatter`, `bar`, etc. without too complex internal code."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "arr = ah.Array([0, 1, 2], [3, 4, 5])\n",
    "arr.config('plot', color='red').render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Furthermore, methods are often prefixed: `ref_` for references, `grid_` for grids, `remark_` for remarks, etc."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "arr = ah.Reference([0, 1, 2])\n",
    "arr.config('ref_plot', color='red').render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To get a full list of configurable methods:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "for key, val in ah.CONFIGURABLES.items():\n",
    "    print(f\"{key}\\n{val}\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### hooks\n",
    "Still, there's lots to be desired that ahlive is incapable of doing. Therefore, if there's a need, things can be done the vanilla matplotlib way first and wrapped into a function listed in `hooks`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "import matplotlib.pyplot as plt\n",
    "import numpy as np\n",
    "\n",
    "def add_twinx(fig, ax):\n",
    "    ax2 = ax.twinx()\n",
    "    ax2.set_ylabel('The twin axes')\n",
    "    ax2.set_ylim(0, 24)\n",
    "\n",
    "ah.Array([0, 1], [0, 12], hooks=[add_twinx]).render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-info\">\n",
    "\n",
    "`hooks` accept multiple custom functions.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### style\n",
    "\n",
    "Setting `style='minimal'` reduces the number of tick labels and grid lines."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "ah.Array([0, 1, 2], [3, 4, 5], style='minimal').render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Setting `style='bare'` removes all tick labels, grid lines, borders, and spacing around the subplot."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "ah.Array([0, 1, 2], [3, 4, 5], style='bare').render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### defaults\n",
    "\n",
    "To get a full list of configurable defaults:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "for key, val in ah.DEFAULTS.items():\n",
    "    print(f\"{key}\\n{val}\\n\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "To set, or update, defaults, specify the relevant key as a positional argument, and the desired keyword arguments.\n",
    "\n",
    "Here, the the final and transition frames' `durations`, or lag, is updated to 3 and 0.25 seconds respectively."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "\n",
    "ah.config_defaults(\"durations\", final_frame=3, transition_frames=0.1)\n",
    "\n",
    "ah.Array([0, 1, 2], [3, 4, 5]).render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or equivalently; emphasis on the double asterisks if done this way!\n",
    "\n",
    "```python\n",
    "import ahlive as ah\n",
    "\n",
    "ah.config_defaults(\"durations\", **{'final_frame': 3, 'transition_frames': 0.1})\n",
    "\n",
    "ah.Array([0, 1, 2], [3, 4, 5]).render()\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Or another way of doing this is to pass a nested dictionary; this way, multiple default keys can be configured simultaneously. The `_kwds` suffix is optional."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import ahlive as ah\n",
    "\n",
    "ah.config_defaults(**{\n",
    "    \"durations_kwds\": dict(final_frame=5, transition_frames=0.5),\n",
    "    \"plot\": {\"scatter\": dict(color=\"red\", s=1000)}\n",
    "})\n",
    "\n",
    "ah.Array([0, 1, 2], [3, 4, 5]).render()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<div class=\"alert alert-warning\">\n",
    "\n",
    "Note that some defaults require an extra layer of nesting, with the keys as the name of the `chart`, like for `plot_kwds`, `ref_plot_kwds`, `preset_kwds`.\n",
    "\n",
    "</div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The new defaults will persist the entire session until restarted."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ah.Array([0, 1, 0], [6, -1, 2]).render()"
   ]
  }
 ],
 "metadata": {},
 "nbformat": 4,
 "nbformat_minor": 4
}