examples/user_guide/Customization.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import hvplot\n",
    "import hvplot.pandas  # noqa"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The hvPlot API is closely modeled on the pandas plot API but also diverges in certain cases, either to improve consistency or to provide additional functionality. This section will outline the valid options to control the axes of a plot, to control datashading and to modify the style of a plot. To look these options up interactively you may either use the tab-completion machinery in IPython or the Jupyter notebook, e.g.:\n",
    "\n",
    "```python\n",
    "df.hvplot.line(<TAB>\n",
    "```\n",
    "\n",
    "OR use the help method:\n",
    "\n",
    "```\n",
    "hvplot.help('line')\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Generic options\n",
    "\n",
    "The generic set of options which may apply to all plot types include:\n",
    "\n",
    "    clim: tuple\n",
    "        Lower and upper bound of the color scale\n",
    "    cnorm (default='linear'): str\n",
    "        Color scaling which must be one of 'linear', 'log' or 'eq_hist'\n",
    "    colorbar (default=False): boolean\n",
    "        Enables a colorbar\n",
    "    fontscale: number\n",
    "        Scales the size of all fonts by the same amount, e.g. fontscale=1.5\n",
    "        enlarges all fonts (title, xticks, labels etc.) by 50%\n",
    "    fontsize: number or dict\n",
    "        Set title, label and legend text to the same fontsize. Finer control\n",
    "        by using a dict: {'title': '15pt', 'ylabel': '5px', 'ticks': 20}\n",
    "    flip_xaxis/flip_yaxis: boolean\n",
    "        Whether to flip the axis left to right or up and down respectively\n",
    "    grid (default=False): boolean\n",
    "        Whether to show a grid\n",
    "    hover : boolean\n",
    "        Whether to show hover tooltips, default is True unless datashade is\n",
    "        True in which case hover is False by default\n",
    "    hover_cols (default=[]): list or str\n",
    "        Additional columns to add to the hover tool or 'all' which will\n",
    "        includes all columns (including indexes if use_index is True).\n",
    "    invert (default=False): boolean\n",
    "        Swaps x- and y-axis\n",
    "    frame_width/frame_height: int\n",
    "        The width and height of the data area of the plot\n",
    "    legend (default=True): boolean or str\n",
    "        Whether to show a legend, or a legend position\n",
    "        ('top', 'bottom', 'left', 'right')\n",
    "    logx/logy (default=False): boolean\n",
    "        Enables logarithmic x- and y-axis respectively\n",
    "    logz (default=False): boolean\n",
    "        Enables logarithmic colormapping\n",
    "    loglog (default=False): boolean\n",
    "        Enables logarithmic x- and y-axis\n",
    "    max_width/max_height: int\n",
    "        The maximum width and height of the plot for responsive modes\n",
    "    min_width/min_height: int\n",
    "        The minimum width and height of the plot for responsive modes\n",
    "    padding: number or tuple\n",
    "        Fraction by which to increase auto-ranged extents to make\n",
    "        datapoints more visible around borders. Supports tuples to\n",
    "        specify different amount of padding for x- and y-axis and\n",
    "        tuples of tuples to specify different amounts of padding for\n",
    "        upper and lower bounds.\n",
    "    responsive: boolean\n",
    "        Whether the plot should responsively resize depending on the\n",
    "        size of the browser. Responsive mode will only work if at\n",
    "        least one dimension of the plot is left undefined, e.g. when\n",
    "        width and height or width and aspect are set the plot is set\n",
    "        to a fixed size, ignoring any responsive option.\n",
    "    rot: number\n",
    "        Rotates the axis ticks along the x-axis by the specified\n",
    "        number of degrees.\n",
    "    shared_axes (default=True): boolean\n",
    "        Whether to link axes between plots\n",
    "    transforms (default={}): dict\n",
    "        A dictionary of HoloViews dim transforms to apply before plotting\n",
    "    title (default=''): str\n",
    "        Title for the plot\n",
    "    tools (default=[]): list\n",
    "        List of tool instances or strings (e.g. ['tap', box_select'])\n",
    "    xaxis/yaxis: str or None\n",
    "        Whether to show the x/y-axis and whether to place it at the\n",
    "        'top'/'bottom' and 'left'/'right' respectively.\n",
    "    xformatter/yformatter (default=None): str or TickFormatter\n",
    "        Formatter for the x-axis and y-axis (accepts printf formatter,\n",
    "        e.g. '%.3f', and bokeh TickFormatter)\n",
    "    xlabel/ylabel/clabel (default=None): str\n",
    "        Axis labels for the x-axis, y-axis, and colorbar\n",
    "    xlim/ylim (default=None): tuple or list\n",
    "        Plot limits of the x- and y-axis\n",
    "    xticks/yticks (default=None): int or list\n",
    "        Ticks along x- and y-axis specified as an integer, list of\n",
    "        ticks positions, or list of tuples of the tick positions and labels\n",
    "    width (default=700)/height (default=300): int\n",
    "        The width and height of the plot in pixels\n",
    "    attr_labels (default=None): bool\n",
    "        Whether to use an xarray object's attributes as labels, defaults to\n",
    "        None to allow best effort without throwing a warning. Set to True\n",
    "        to see warning if the attrs can't be found, set to False to disable\n",
    "        the behavior.\n",
    "    sort_date (default=True): bool\n",
    "        Whether to sort the x-axis by date before plotting\n",
    "    symmetric (default=None): bool\n",
    "        Whether the data are symmetric around zero. If left unset, the data\n",
    "        will be checked for symmetry as long as the size is less than\n",
    "        ``check_symmetric_max``.\n",
    "    check_symmetric_max (default=1000000):\n",
    "        Size above which to stop checking for symmetry by default on the data."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Datashading options\n",
    "\n",
    "In addition to regular plot options hvplot also exposes options for dealing with large data:\n",
    "\n",
    "    aggregator (default=None):\n",
    "        Aggregator to use when applying rasterize or datashade operation\n",
    "        (valid options include 'mean', 'count', 'min', 'max' and more, and\n",
    "        datashader reduction objects)\n",
    "    dynamic (default=True):\n",
    "        Whether to return a dynamic plot which sends updates on widget and\n",
    "        zoom/pan events or whether all the data should be embedded\n",
    "        (warning: for large groupby operations embedded data can become\n",
    "        very large if dynamic=False)\n",
    "    datashade (default=False):\n",
    "        Whether to apply rasterization and shading using datashader\n",
    "        library returning an RGB object\n",
    "    dynspread (default=False):\n",
    "        Allows plots generated with datashade=True to increase the point\n",
    "        size to make sparse regions more visible\n",
    "    rasterize (default=False):\n",
    "        Whether to apply rasterization using the datashader library\n",
    "        returning an aggregated Image\n",
    "    x_sampling/y_sampling (default=None):\n",
    "        Specifies the smallest allowed sampling interval along the x/y axis."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Geographic options\n",
    "\n",
    "When dealing with geographic data, there are a number of options that become avaliable. See the [geographic section](Geographic_Data.ipynb) for more information on working with geographic data:\n",
    "\n",
    "    coastline (default=False):\n",
    "        Whether to display a coastline on top of the plot, setting\n",
    "        coastline='10m'/'50m'/'110m' specifies a specific scale.\n",
    "    crs (default=None):\n",
    "        Coordinate reference system of the data specified as Cartopy\n",
    "        CRS object, proj.4 string or EPSG code.\n",
    "    features (default=None): dict or list\n",
    "        A list of features or a dictionary of features and the scale\n",
    "        at which to render it. Available features include 'borders',\n",
    "        'coastline', 'lakes', 'land', 'ocean', 'rivers' and 'states'.\n",
    "        Available scales include '10m'/'50m'/'110m'.\n",
    "    geo (default=False):\n",
    "        Whether the plot should be treated as geographic (and assume\n",
    "        PlateCarree, i.e. lat/lon coordinates).\n",
    "    global_extent (default=False):\n",
    "        Whether to expand the plot extent to span the whole globe.\n",
    "    project (default=False):\n",
    "        Whether to project the data before plotting (adds initial\n",
    "        overhead but avoids projecting data when plot is dynamically\n",
    "        updated).\n",
    "    tiles (default=False):\n",
    "        Whether to overlay the plot on a tile source. Tiles sources\n",
    "        can be selected by name or a tiles object or class can be passed,\n",
    "        the default is 'Wikipedia'."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Kind options\n",
    "\n",
    "Each type of plot may have a number of options to visual attributes specific to that plot type. In general these are provided in the docstring of the plot type, which can be viewed using ``help`` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hvplot.help('scatter', generic=False, style=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Styling options\n",
    "\n",
    "Beyond the options specific to each plot type (or ``kind``) it is also possible to customize each component in detail, exposing all the options bokeh exposes. These usually include options to color the line and fill color, alpha and style. To see the full listing we can once again use the ``help`` method:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hvplot.help('line', docstring=False, generic=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In general, the objects returned by hvPlot are regular HoloViews objects, which can be overlaid, laid out, composed and customized like all other HoloViews objects.  The [HoloViews](http://holoviews.org) website explains all the functionality available, but what's on this hvPlot website should be enough to get you up and running for typical usage.  "
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}