{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Installing and Configuring Holoviews"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "HoloViews can be installed on any platform where [NumPy](http://numpy.org) and Python 2.7 or 3 are available.\n",
    "\n",
    "That said, HoloViews is designed to work closely with many other libraries, which can make installation and configuration more complicated.  This user guide page describes some of these less-common or not-required options that may be helpful for some users."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Other installation options\n",
    "\n",
    "The main [installation instructions](http://holoviews.org/#installation) should be sufficient for most users, but you may also want the [Matplotlib](http://matplotlib.org) and [Plotly](https://plot.ly/python/) backends, which are required for some of the examples:\n",
    "\n",
    "    conda install matplotlib plotly\n",
    "\n",
    "HoloViews can also be installed using one of these `pip` commands:\n",
    "\n",
    "    pip install holoviews\n",
    "    pip install 'holoviews[recommended]'\n",
    "    pip install 'holoviews[extras]'\n",
    "    pip install 'holoviews[all]'\n",
    "\n",
    "The first option installs just the bare library and the [NumPy](http://numpy.org) and [Param](http://ioam.github.com/param) libraries, which is all you need on your system to generate and work with HoloViews objects without visualizing them. The other options install additional libraries that are often useful, with the `recommended` option being similar to the `conda` install command above.\n",
    "\n",
    "Between releases, development snapshots are made available as conda packages:\n",
    "\n",
    "    conda install -c pyviz/label/dev holoviews\n",
    "\n",
    "To get the very latest development version you can clone our git\n",
    "repository and put it on the Python path:\n",
    "\n",
    "    git clone git://github.com/ioam/holoviews.git\n",
    "    cd holoviews\n",
    "    pip install -e ."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## JupyterLab configuration\n",
    "\n",
    "To work with JupyterLab you will also need the HoloViews JupyterLab\n",
    "extension:\n",
    "\n",
    "```\n",
    "conda install -c conda-forge jupyterlab\n",
    "jupyter labextension install @pyviz/jupyterlab_pyviz\n",
    "```\n",
    "\n",
    "Once you have installed JupyterLab and the extension launch it with:\n",
    "\n",
    "```\n",
    "jupyter-lab\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## ``hv.config`` settings\n",
    "\n",
    "The default HoloViews installation will use the latest defaults and options available, which is appropriate for new users.  If you want to work with code written for older HoloViews versions, you can use the top-level ``hv.config`` object to control various backwards-compatibility options:\n",
    "\n",
    "* ``future_deprecations``: Enables warnings about future deprecations (introduced in 1.11).\n",
    "* ``warn_options_call``: Warn when using the to-be-deprecated ``__call__`` syntax for specifying options, instead of the recommended ``.opts`` method.\n",
    "\n",
    "It is recommended you set ``warn_options_call`` to ``True`` in your holoviews.rc file (see section below).\n",
    "\n",
    "It is possible to set the configuration using `hv.config` directly:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import holoviews as hv\n",
    "hv.config(future_deprecations=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "However, because in some cases this configuration needs to be declared before the plotting extensions are imported, the recommended way of setting configuration options is:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hv.extension('bokeh', config=dict(future_deprecations=True))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In addition to backwards-compatibility options, ``hv.config`` holds some global options:\n",
    "\n",
    "* ``image_rtol``: The tolerance used to enforce regular sampling for regular, gridded data. Used to validate ``Image`` data.\n",
    "\n",
    "This option allows you to set the ``rtol`` parameter of [``Image``](../reference/elements/bokeh/Image.ipynb) elements globally.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Improved tab-completion\n",
    "\n",
    "Both ``Layout`` and ``Overlay`` are designed around convenient tab-completion, with the expectation of upper-case names being listed first. In recent versions of Jupyter/IPython there has been a regression whereby the tab-completion is no longer case-sensitive. This can be fixed with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import holoviews as hv\n",
    "hv.extension(case_sensitive_completion=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## The holoviews.rc file\n",
    "\n",
    "HoloViews searches for the first rc file it finds in the following places (in order): \n",
    "\n",
    "1. ``holoviews.rc`` in the parent directory of the top-level ``__init__.py`` file (useful for developers working out of the HoloViews git repo)\n",
    "2. ``~/.holoviews.rc``\n",
    "3. ``~/.config/holoviews/holoviews.rc``\n",
    "\n",
    "The rc file location can be overridden via the ``HOLOVIEWSRC`` environment variable.\n",
    "\n",
    "The rc file is a Python script, executed as HoloViews is imported. An example rc file to include various options discussed above might look like this:\n",
    "\n",
    "```\n",
    "import holoviews as hv\n",
    "hv.config(warn_options_call=True)\n",
    "hv.extension.case_sensitive_completion=True\n",
    "```\n"
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}