{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Customization"
   ]
  },
  {
   "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",
    "    bgcolor: str\n",
    "        Background color of the data area of the plot\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 or Literal[\"vline\", \"hline\"]\n",
    "        Whether to show hover tooltips, default is True unless datashade is\n",
    "        True in which case hover is False by default. Can also set\n",
    "        `vline` for hitbox across a vertical line or `hline` for hitbox across a horizontal line.\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",
    "    hover_formatters:\n",
    "        A dict of formatting options for the hover tooltip.\n",
    "    hover_tooltips list[str] or list[tuple]:\n",
    "        A list of dimensions to be displayed in the hover tooltip. See\n",
    "        [HoloViews docs](https://holoviews.org/user_guide/Plotting_with_Bokeh.html#hover-tools)\n",
    "        or [Bokeh docs](https://docs.bokeh.org/en/latest/docs/user_guide/interaction/tools.html#hovertool)\n",
    "        for more info on structuring.\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",
    "    robust: bool\n",
    "        If True and clim are absent, the colormap range is computed\n",
    "        with 2nd and 98th percentiles instead of the extreme values\n",
    "        for image elements. For RGB elements, clips the \"RGB\", or\n",
    "        raw reflectance values between 2nd and 98th percentiles.\n",
    "        Follows the same logic as xarray's robust option.\n",
    "    rot: number\n",
    "        Rotates the axis ticks along the x-axis by the specified\n",
    "        number of degrees.\n",
    "    subcoordinate_y: bool or dict\n",
    "       Whether to enable sub-coordinate y systems for this plot. Accepts also a\n",
    "       dictionary of related options to pass down to HoloViews,\n",
    "       e.g. `{'subcoordinate_scale': 2}`.\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/cticks (default=None): int or list\n",
    "        Ticks along x-axis, y-axis, and colorbar 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",
    "    downsample (default=False):\n",
    "        Controls the application of downsampling to the plotted data,\n",
    "        which is particularly useful for large timeseries datasets to\n",
    "        reduce the amount of data sent to browser and improve\n",
    "        visualization performance. Requires HoloViews >= 1.16. Additional\n",
    "        dependencies: Installing the `tsdownsample` library is required\n",
    "        for using any downsampling methods other than the default 'lttb'.\n",
    "        Acceptable values:\n",
    "        - False: No downsampling is applied.\n",
    "        - True: Applies downsampling using HoloViews' default algorithm\n",
    "            (LTTB - Largest Triangle Three Buckets).\n",
    "        - 'lttb': Explicitly applies the Largest Triangle Three Buckets\n",
    "          algorithm.\n",
    "        - 'minmax': Applies the MinMax algorithm, selecting the minimum\n",
    "          and maximum values in each bin. Requires `tsdownsample`.\n",
    "        - 'm4': Applies the M4 algorithm, selecting the minimum, maximum,\n",
    "          first, and last values in each bin. Requires `tsdownsample`.\n",
    "        - 'minmax-lttb': Combines MinMax and LTTB algorithms for\n",
    "          downsampling, first applying MinMax to reduce to a preliminary\n",
    "          set of points, then LTTB for further reduction. Requires\n",
    "          `tsdownsample`.\n",
    "        Other string values corresponding to supported algorithms in\n",
    "        HoloViews may also be used.\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",
    "    pixel_ratio (default=None):\n",
    "       Pixel ratio applied to the height and width, used when rasterizing or\n",
    "       datashading. When not set explicitly, the ratio is automatically\n",
    "       obtained from the browser device pixel ratio. Default is 1 when\n",
    "       the browser information is not available. Useful when the browser\n",
    "       information is not available (pixel_ratio=2 can give better results on\n",
    "       Retina displays) or for using lower resolution for speed.\n",
    "    rasterize (default=False):\n",
    "        Whether to apply rasterization using the datashader library\n",
    "        returning an aggregated Image\n",
    "    resample_when (default=None):\n",
    "        Applies a resampling operation (datashade, rasterize or downsample) if\n",
    "        the number of individual data points present in the current zoom range\n",
    "        is above this threshold. The raw plot is displayed otherwise.\n",
    "    x_sampling/y_sampling (default=None):\n",
    "        Specifies the smallest allowed sampling interval along the x/y axis.\n",
    "        Used when rasterizing or datashading."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Geographic options\n",
    "\n",
    "When dealing with geographic data, there are a number of options that become available. 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 (input projection) specified as a string or integer EPSG code, a CRS or Proj pyproj object, a Cartopy CRS object or class name, a WKT string, or a proj.4 string. Defaults to PlateCarree.\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",
    "    projection (default=None):\n",
    "        Coordinate reference system of the plot (output projection) specified as a string or integer EPSG code, a CRS or Proj pyproj object, a Cartopy CRS object or class name, a WKT string, or a proj.4 string. Defaults to PlateCarree.\n",
    "    tiles (default=False):\n",
    "        Whether to overlay the plot on a tile source. If coordinate values fall within lat/lon bounds, auto-projects to EPSG:3857 unless `projection=False` or if the data is lazily loaded (dask / ibis). Tiles sources\n",
    "        can be selected by name or a tiles object or class can be passed,\n",
    "        the default is 'Wikipedia'.\n",
    "    tiles_opts (default=None): dict\n",
    "        Options to customize the tiles layer created when `tiles` is set,\n",
    "        e.g. `dict(alpha=0.5)`."
   ]
  },
  {
   "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](https://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
}