Density shading

  run this example as a notebook — or grab the .ipynb (also linked at the bottom of the page)

The density kwarg overlays a subtle KDE (kernel density estimate) “glow” behind the data: a 2D alpha-ramped heatmap, or a 3D volumetric cloud, showing where each dataset’s points are concentrated (GH #108, #191). Density shading is OFF by default (density=None) – pass density=True for the defaults, or a dict to override alpha/levels/grid/per_group.

# Code source: Contextual Dynamics Laboratory
# License: MIT

import numpy as np

import hypertools as hyp

rng = np.random.default_rng(1)

# two 2D clusters
cluster_a_2d = rng.standard_normal((200, 2)) * 0.6
cluster_b_2d = rng.standard_normal((200, 2)) * 0.6 + [4, 0]

hyp.plot([cluster_a_2d, cluster_b_2d], '.', density=True)

/home/docs/checkouts/readthedocs.org/user_builds/hypertools/checkouts/latest/hypertools/plot/backend.py:1353: UserWarning: Failed to switch to any interactive backend (TkAgg, QtAgg, Qt5Agg, Qt4Agg, GTK4Agg, GTK3Agg, WXAgg). Falling back to 'Agg'.
  warnings.warn(BACKEND_WARNING)

The same kwarg works in 3D, where it renders as a translucent volumetric cloud instead of a 2D heatmap.

cluster_a_3d = rng.standard_normal((200, 3)) * 0.6
cluster_b_3d = rng.standard_normal((200, 3)) * 0.6 + [4, 0, 0]

hyp.plot([cluster_a_3d, cluster_b_3d], '.', density=True)

/home/docs/checkouts/readthedocs.org/user_builds/hypertools/checkouts/latest/hypertools/plot/backend.py:1353: UserWarning: Failed to switch to any interactive backend (TkAgg, QtAgg, Qt5Agg, Qt4Agg, GTK4Agg, GTK3Agg, WXAgg). Falling back to 'Agg'.
  warnings.warn(BACKEND_WARNING)

A dict lets you turn up the glow (higher alpha, more contour levels) for a more prominent effect – but by default the density stays subtle so the actual data points remain the dominant visual element.

hyp.plot([cluster_a_2d, cluster_b_2d], '.',
         density={'alpha': 0.4, 'levels': 5})

/home/docs/checkouts/readthedocs.org/user_builds/hypertools/checkouts/latest/hypertools/plot/backend.py:1353: UserWarning: Failed to switch to any interactive backend (TkAgg, QtAgg, Qt5Agg, Qt4Agg, GTK4Agg, GTK3Agg, WXAgg). Falling back to 'Agg'.
  warnings.warn(BACKEND_WARNING)