Datashader Cheat Sheet

1Setup & the pipeline0.19

import datashader as ds import datashader.transfer_functions as tf★
Two imports do almost everything: ds for aggregation, tf for turning aggregates into images.
# 3 stages: aggregate (Canvas) -> transform -> shade (tf) agg = cvs.points(df, "x", "y") img = tf.shade(agg)★
The whole model in two lines. Aggregation produces an xarray grid; shading colors it. Each pixel is an honest aggregate — no overplotting, no sampling.
pip install datashader # brings numba, xarray, dask
Aggregation is JIT-compiled (Numba), so it's fast on tens of millions of rows on a laptop.

2Canvas & glyphsbin into a grid

cvs = ds.Canvas(plot_width=800, plot_height=600, x_range=(0, 10), y_range=(0, 10))★
The grid = plot_width × plot_height pixels. Set x_range/y_range to fix the extent (and avoid a scan to infer it — matters for Dask).
agg = cvs.points(df, "lon", "lat", agg=ds.count())★
Scatter/points — each row drops into one cell. The agg= reduction (card 3) decides what each cell holds.
cvs.line(df, "t", "value") # timeseries / trajectories cvs.raster(xarr) · cvs.polygons(...) · cvs.area(...) · cvs.quadmesh(...)
Other glyphs: line (connected series), raster/quadmesh (regridding), polygons, trimesh (unstructured meshes).

3Reductions (agg)what each cell holds

ds.count() # rows per cell (default) ds.mean("speed") · ds.sum("amt") · ds.max("z")★
Pick the statistic each pixel aggregates. Also min, std, var, first, last, any.
ds.by("category", ds.count()) # per-category stacked grid★
Categorical aggregation — separate count per category, later colored by a color_key (card 5). The column must be category dtype. (Older API: ds.count_cat.)
ds.summary(n=ds.count(), avg=ds.mean("v"))
Compute several reductions in one pass — returns an xarray Dataset with each as a variable.

4tf.shade & colormapsgrid -> image

img = tf.shade(agg, cmap=["lightblue", "darkblue"])★
Maps aggregate values to colors. cmap is a list of colors or a named/continuous colormap. Returns an Image that displays in notebooks.
import colorcet as cc tf.shade(agg, cmap=cc.fire)★
colorcet supplies perceptually-uniform maps (fire, viridis, CET_L*) — the recommended source for continuous colormaps here.
tf.shade(agg).to_pil() # PIL image for saving
The result carries an xarray + an image; export via PIL or hand to HoloViews/Bokeh.

5how= & categorical colorreveal the dynamic range

tf.shade(agg, how="eq_hist")★
The signature move. Histogram equalization spreads color across the full data range, revealing structure when densities span many orders of magnitude — where linear shading shows only a few hot pixels.
tf.shade(agg, how="log") # or "cbrt", "linear"★
Fixed nonlinear scalings. log/cbrt compress heavy tails; linear is faithful but usually hides low-density detail.
tf.shade(agg_by, color_key={"car": "red", "bus": "blue"})
Color a categorical aggregate (from ds.by): each category gets a hue, and overlaps blend — showing where categories mix.

6spread / stack / bgpost-process the image

tf.spread(img, px=2) · tf.dynspread(img)★
Fatten sparse pixels so isolated points are visible. spread uses a fixed radius; dynspread picks one automatically from density.
tf.set_background(img, "black")★
Set the backdrop — dark backgrounds make bright colormaps like fire pop.
tf.stack(img_a, img_b, how="over")
Composite multiple shaded images into one (e.g. two datasets, or highlight layers).

7Dask & GPUbillions of rows

import dask.dataframe as dd df = dd.read_parquet("huge/*.parquet") cvs.points(df, "x", "y") # same call, out-of-core★
Dask dataframes just work — aggregation runs partition-by-partition, so datasets larger than RAM are fine. Columnar sources (Parquet) are fastest.
import cudf gdf = cudf.read_parquet("data.parquet") cvs.points(gdf, "x", "y") # GPU aggregation
cuDF / dask-cuDF run the aggregation on an NVIDIA GPU — interactive rates on hundreds of millions of points. (See the cuML/RAPIDS sheet.)
# memory is set by the grid (plot_width x plot_height), not row count
The output is a fixed-size grid regardless of input size — that's why it scales.

8Interactive (HoloViews)re-aggregate on zoom

from holoviews.operation.datashader import rasterize, datashade rasterize(hv.Points(df)) # re-datashades as you zoom★
The interactive path. Wrapping a HoloViews element re-runs Datashader on every pan/zoom against the visible range — you get axes, colorbars, and hover for free.
# rasterize (preferred) vs datashade★
Prefer rasterize: it returns the aggregate so HoloViews does colormapping client-side (live colorbar + hover). datashade bakes a fixed RGB image (no hover/colorbar).
rasterize(pts).opts(cmap="fire", cnorm="eq_hist", colorbar=True)
Style the rasterized output with normal HoloViews .opts() — cnorm="eq_hist" is the equivalent of how="eq_hist". Add GeoViews for maps.

!Common gotchasread before shipping

it's not a plotting library
Datashader outputs an image/array — no axes, ticks, or interactivity on its own. Pair it with HoloViews/Bokeh (or Matplotlib) for a real plot.
use how="eq_hist"
With linear shading, a few dense cells saturate and everything else looks empty. eq_hist (or log) is almost always what reveals the real structure.
set x_range / y_range
Without them the extent is inferred from the data — a full scan that's slow on Dask, and it won't match a companion plot's axes. Set them explicitly.
sparse points vanish at 1px
Single-pixel points can be invisible. Apply tf.spread/tf.dynspread to make them show.
categorical column must be `category` dtype
ds.by/count_cat needs a pandas category column — cast with df["c"].astype("category") first.
rasterize > datashade for interactivity
In HoloViews, datashade returns baked RGB (no hover/colorbar). Use rasterize so colormapping stays live client-side.
grid size = memory, not row count
Huge plot_width/plot_height blow up memory even on small data. Size the canvas to the display, not the dataset.

Datashader cheat sheet