{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### When should I use Datashader?\n",
    "\n",
    "Datashader is designed for working with large datasets, for\n",
    "cases where it is most crucial to faithfully represent the\n",
    "*distribution* of your data. Datashader can work easily with\n",
    "extremely large datasets, generating a fixed-size data structure\n",
    "(regardless of the original number of records) that gets transferred to\n",
    "your local browser for display.  If you ever find yourself subsampling\n",
    "your data just so that you can plot it feasibly, or if you are forced\n",
    "for practical reasons to iterate over chunks of it rather than looking\n",
    "at all of it at once, then Datashader can probably help you."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### When should I *not* use Datashader?\n",
    "\n",
    "If you have a very small number of data points (in the hundreds\n",
    "or thousands) or curves (in the tens or several tens, each with\n",
    "hundreds or thousands of points), then conventional plotting packages\n",
    "like [Bokeh](https://bokeh.pydata.org) may be more suitable.  With conventional browser-based\n",
    "packages, all of the data points are passed directly to the browser for\n",
    "display, allowing specific interaction with each curve or point,\n",
    "including display of metadata, linking to sources, etc.  This approach\n",
    "offers the most flexibility *per point* or *per curve*, but rapidly\n",
    "runs into limitations on how much data can be processed by the browser,\n",
    "and how much can be displayed on screen and resolved by the human\n",
    "visual system.  If you are not having such problems, i.e., your data is\n",
    "easily handled by your plotting infrastructure and you can easily see\n",
    "and work with all your data onscreen already, then you probably don't\n",
    "need Datashader."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Is Datashader part of Bokeh or HoloViews?\n",
    "\n",
    "Datashader is an independent project, focusing on generating\n",
    "aggregate arrays and representations of them as images.  Bokeh\n",
    "and HoloViews are complementary projects to Datashader, focusing on\n",
    "building browser-based visualizations and dashboards. These and other\n",
    "plotting packages can display images rendered by Datashader, providing\n",
    "axes, interactive zooming and panning, selection, legends, hover\n",
    "information, and so on.  Sample code is provided with Datashader for\n",
    "demonstrating how to use HoloViews (supporting Bokeh, Matplotlib, and\n",
    "Plotly) or native Matplotlib to provide such features. The library can\n",
    "also be used separately, without any\n",
    "external plotting packages, generating images that can be displayed\n",
    "directly or saved to disk, or generating aggregate arrays suitable\n",
    "for further analysis."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What's the easiest way to use Datashader interactively?\n",
    "\n",
    "[HoloViews](https://holoviews.org). HoloViews uses Bokeh or Plotly behind\n",
    "the scenes, but it offers a higher level API that is well suited to\n",
    "the sorts of magic that allow interactive use of Datashader. For a\n",
    "given dataset, HoloViews can easily construct either a raw Bokeh/Plotly plot\n",
    "or a Bokeh/Plotly plot with server-side rendering from Datashader, hiding\n",
    "nearly all of the complexity involved."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How can I get legends and colorbars for my Datashader plot?\n",
    "\n",
    "When used as a standalone library, Datashader can only generate images or bare arrays; it does not have any concept of axes, legends, or colorbars. But Datashader is designed to work well as a rendering engine for other plotting libraries that do offer those features. For the specific case of colorbars, just ensure that you are letting the separate plotting library do the colormapping, not Datashader, and you should be able to get full support for colorbars. That is, use Datashader to aggregate the image into a fixed array of values, and then use Bokeh, Plotly, or Holoviews to colormap and render the array as pixels, which will allow the plotting library to construct a suitable colormap. For instance, to get a colorbar in HoloViews, use `rasterize()` to invoke datashader on the data and generate an array of values; do not use `datashade()`, which would `rasterize()` while also calling `shade()` to generate RGB pixel values, at which point the plotting library would not be able to report the mapping from value to color, as it only would have seen the final RGB values. Of course, if you let the plotting library do the colormapping, you will no longer be able to use Datashader-specific features like histogram equalization, which would then need to be implemented by the plotting library (as now done for Bokeh) if you want to have colorbars for such cases."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### What data libraries can I use with Datashader?\n",
    "\n",
    "See the [Performance user guide](user_guide/Performance.ipynb#Data-objects) for the available options for working with columnar/multidimensional/ragged data on single-core/multi-core/distributed/CPU/GPU resources in or out of core for each available glyph."
   ]
  }
 ],
 "metadata": {
  "language_info": {
   "name": "python",
   "pygments_lexer": "ipython3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}
