Added JSONInit class to parambokeh

examples/user_guide/JSONInit.ipynb

@@ -0,0 +1,352 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Setting parameters via JSON"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "\n",
+    "For all the examples in this notebook to work, launch the notebook server using:\n",
+    "\n",
+    "```\n",
+    "PARAMBOKEH_INIT='{\"p1\":5}' \\\n",
+    " TARGETED='{\"Target1\":{\"p1\":3}, \"Target2\":{\"s\":\"test\"}}' \\\n",
+    " CUSTOM='{\"custom\":{\"val\":99}}' jupyter notebook\n",
+    "```\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import os\n",
+    "import param\n",
+    "import parambokeh\n",
+    "from bokeh.io import output_notebook\n",
+    "output_notebook()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example 1"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The first minimal example will work if the notebook server is launched as follows:\n",
+    "\n",
+    "```\n",
+    "PARAMBOKEH_INIT='{\"p1\":5}' jupyter notebook\n",
+    "```\n",
+    "\n",
+    "First let's show that the ``'PARAMBOKEH_INIT'`` environment is defined:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "os.environ['PARAMBOKEH_INIT']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This string is JSON and the 'PARAMBOKEH_INIT' is the default environment variable name to set parameters via the commandline. Lets make a simple parameterized class with a ``p1`` parameter:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class Test(param.Parameterized):\n",
+    "    \n",
+    "    p1 = param.Number(default=1, bounds=(0,10))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now if we supply ``PARAMBOKEH.JSONInit`` as an initializer, the ``p1`` parameter is set from the default of 1 to the value of 5 specified by the environment variable:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "parambokeh.Widgets(Test, initializer=parambokeh.JSONInit())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example 2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The second example will work if the notebook server is launched as follows:\n",
+    "\n",
+    "```\n",
+    "TARGETED='{\"Target1\":{\"p1\":3}, \"Target2\":{\"s\":\"test\"}}' jupyter notebook\n",
+    "```\n",
+    "\n",
+    "In this example, we show how you can target parameters to different classes using a different environment variable called ``TARGETED``:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "os.environ['TARGETED']"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here the keys are class names and the corresponding dictionary values are the parameter values to override. Let's defined classes ``Target1`` and ``Target2`` with parameters ``p1`` and ``s`` respectively:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class Target1(param.Parameterized):\n",
+    "    \n",
+    "    p1 = param.Number(default=1, bounds=(0,10))\n",
+    "\n",
+    "class Target2(param.Parameterized):\n",
+    "    \n",
+    "    s = param.String(default=\"default\")\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now lets use ``PARAMBOKEH.Widgets`` on ``Target1``:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "parambokeh.Widgets(Target1, initializer=parambokeh.JSONInit(varname='TARGETED'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The value of ``p1`` is now ``3`` as requested.\n",
+    "\n",
+    "Now lets use ``PARAMBOKEH.Widgets`` on ``Target2``:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "parambokeh.Widgets(Target2, initializer=parambokeh.JSONInit(varname='TARGETED'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": true
+   },
+   "source": [
+    "## Example 3"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "The third example will work if the notebook server is launched as follows:\n",
+    "\n",
+    "```\n",
+    "CUSTOM='{\"custom\":{\"val\":99}}' jupyter notebook\n",
+    "```\n",
+    "\n",
+    "In this example, we show how you can target a specific instance using an environment variable called ``CUSTOM``:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "os.environ['CUSTOM']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class Example(param.Parameterized):\n",
+    "    \n",
+    "    val = param.Number(default=1, bounds=(0,100))\n",
+    "    \n",
+    "instance = Example()\n",
+    "parambokeh.Widgets(instance, initializer=parambokeh.JSONInit(varname='CUSTOM', target='custom'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Example 4"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You can also use a JSON file ending with the '.json' extension. For instance, if you execute:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import json\n",
+    "json.dump({\"p1\":5}, open('param_init.json', 'w'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "You cam specify the full path or relative path to the JSON file with:\n",
+    "\n",
+    "\n",
+    "```\n",
+    "PARAMBOKEH_INIT=param_init.json jupyter notebook\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "os.environ['PARAMBOKEH_INIT']"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "class Test(param.Parameterized):\n",
+    "    \n",
+    "    p1 = param.Number(default=1, bounds=(0,10))\n",
+    "    \n",
+    "parambokeh.Widgets(Test, initializer=parambokeh.JSONInit())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Note that you can use ``JSONInit`` without setting any environment variables by specifying the JSON file directly:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "parambokeh.Widgets(Test, initializer=parambokeh.JSONInit(json_file='param_init.json'))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": true
+   },
+   "source": [
+    "## Tips"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "\n",
+    "* It is recommended that you target at the class or instance level if you ever intend to use ``JSONInit`` to customize different sets of parameters.\n",
+    "\n",
+    "* It is recommended that you validate (and pretty print) the JSON at the commandline using ``json.tool``. For instance, you can validate the JSON for the first example before launching the server as follows:\n",
+    "\n",
+    "```\n",
+    "PARAMBOKEH_INIT=`echo '{\"p1\":5}' | python -mjson.tool` jupyter notebook\n",
+    "```"
+   ]
+  }
+ ],
+ "metadata": {
+  "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.6.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 1
+}