Make it easy to use categorical bar charts with linked selections

[MarcSkovMadsen]

Add built-in categorical_agg operation for link_selections with categorical Bars

Problem

HoloViews' link_selections is a powerful cross-filtering mechanism, but it only works out of the box with numeric dimensions via hv.operation.histogram. There is no built-in operation for categorical dimensions. Every natural approach a user tries fails:

Failure 1 — histogram() on a categorical dimension

from holoviews.operation import histogram
hist_cat = histogram(points, dimension='category')

ValueError: Categorical data found. Cannot create histogram from categorical data.

histogram explicitly rejects non-numeric data, so it cannot be repurposed for categorical counts.

Failure 2 — Pre-aggregated hv.Bars with link_selections

bars_agg = hv.Bars(
    df.groupby('category').size().reset_index(name='count'),
    kdims='category', vdims='count',
)
layout = ls(points) + ls(bars_agg)

The layout renders initially, but the moment a selection is made (lasso, box-select, or programmatic expression), it raises:

CallbackError: linked_selection aborted because it could not display selection
for all elements: One or more dimensions in the expression dim('x')>0 could not
resolve on ':Dataset   [category]   (count)' Ensure all dimensions referenced by
the expression are present on the supplied object on ':Bars   [category]   (count)'.

Because bars_agg was constructed from an independent DataFrame, it has no lineage back to points and cannot resolve the cross-filter expression.

Failure 3 — Raw hv.Bars from unaggregated data

bars_raw = hv.Bars(df, kdims=['category'])
print(bars_raw.kdims)  # [Dimension('category')]
print(bars_raw.vdims)  # [Dimension('x'), Dimension('y')]

No exception is raised, but the result is silently wrong. HoloViews auto-detects the remaining DataFrame columns (x, y) as vdims, producing 100 individual bars rather than a 4-bar categorical count chart. The element technically renders with link_selections, but the visualization is meaningless — it is not a count (or any aggregation) over categories.

---

Minimum reproducible example

Self-contained script demonstrating all three failures (HoloViews 1.22.1, Python 3.12):

import holoviews as hv
import numpy as np
import pandas as pd

hv.extension('bokeh')

# --- Sample data ---
rng = np.random.default_rng(42)
df = pd.DataFrame({
    'category': rng.choice(['A', 'B', 'C', 'D'], 100),
    'x': rng.normal(size=100),
    'y': rng.normal(size=100),
})

ls = hv.link_selections.instance()
points = hv.Points(df, kdims=['x', 'y'], vdims=['category'])

# --- Failure 1: histogram on categorical dimension ---
from holoviews.operation import histogram

try:
    hist_cat = histogram(points, dimension='category')
    print('Attempt 1 succeeded (unexpected)')
except Exception as e:
    print(f'Attempt 1 — histogram on categorical:\n  {type(e).__name__}: {e}\n')

# --- Failure 2: Pre-aggregated Bars with link_selections ---
bars_agg = hv.Bars(
    df.groupby('category').size().reset_index(name='count'),
    kdims='category', vdims='count',
)
try:
    layout = ls(points) + ls(bars_agg)
    # Trigger a selection to expose the error
    from holoviews.util.transform import dim
    ls.selection_expr = (dim('x') > 0)
    hv.render(layout)
    print('Attempt 2 succeeded (unexpected)')
except Exception as e:
    print(f'Attempt 2 — Pre-aggregated Bars:\n  {type(e).__name__}: {e}\n')

# --- Failure 3: Raw Bars from unaggregated data (silent wrong behavior) ---
bars_raw = hv.Bars(df, kdims=['category'])
print(f'Attempt 3 — Raw Bars auto-detected vdims: {bars_raw.vdims}')
print(f'  Expected 4 category-count bars, got {len(bars_raw)} individual rows.')
print('  No exception, but the chart is meaningless — not a categorical aggregation.\n')

---

Proposed solution — a built-in categorical_agg operation

Add a new operation to holoviews.operation (e.g. categorical_agg) that generalises what histogram does for numeric dimensions to categorical dimensions, supporting arbitrary aggregation functions — not just counting.

Suggested API

from holoviews.operation import categorical_agg

# Count occurrences per category (default)
bars_count = categorical_agg(points, dimension='category')

# Sum a numeric value dimension per category
bars_sum = categorical_agg(points, dimension='category', value_dimension='y', function=np.sum)

# Mean
bars_mean = categorical_agg(points, dimension='category', value_dimension='y', function=np.mean)

# Standard deviation
bars_std = categorical_agg(points, dimension='category', value_dimension='y', function=np.std)

# Min / Max
bars_min = categorical_agg(points, dimension='category', value_dimension='y', function=np.min)
bars_max = categorical_agg(points, dimension='category', value_dimension='y', function=np.max)

# All work seamlessly with link_selections
ls = hv.link_selections.instance()
layout = ls(points) + ls(bars_count) + ls(bars_mean)

Key parameters

Parameter	Type	Default	Description
dimension	str	(required)	Categorical dimension to group by
value_dimension	str or None	None	Numeric dimension to aggregate. When None, counts rows per category.
function	callable	np.size	Aggregation function applied to value_dimension (or row count when value_dimension is None). Any function accepting an array and returning a scalar: np.sum, np.mean, np.std, np.min, np.max, or a custom callable.
label	str or None	None	Label for the value axis. Auto-generated from function name if None (e.g. "mean(y)").

Requirements

• Must be a holoviews.core.Operation subclass so it preserves data lineage — link_selections recurses into the operation's source element to resolve cross-filter expressions, then re-runs the operation on the filtered subset.
• Returns hv.Bars with kdims=[dimension] and vdims=[label].
• Should handle edge cases: empty selections (return zero-height bars for all categories), missing categories in a filtered subset (fill with 0 or NaN as appropriate for the aggregation).

---

Working workaround

Until a built-in operation exists, this custom Operation subclass achieves the same result. The pattern comes from a real-world energy trading dashboard:

import param
import numpy as np
import holoviews as hv
from holoviews.core import Operation

class categorical_agg(Operation):
    """Aggregate a categorical dimension, returning Bars.

    Preserves data lineage back to the source element so that
    link_selections can resolve all source dimensions during cross-filtering.
    """

    dimension = param.String(doc="Categorical dimension to group by")
    value_dimension = param.String(default=None, allow_None=True,
        doc="Numeric dimension to aggregate. None means count rows.")
    function = param.Callable(default=np.size,
        doc="Aggregation function (np.sum, np.mean, np.std, np.min, np.max, ...)")
    label = param.String(default=None, allow_None=True,
        doc="Label for the value axis. Auto-generated if None.")

    def _process(self, element, key=None):
        cat_vals = element.dimension_values(self.p.dimension, expanded=True)
        unique_cats = np.unique(cat_vals)

        if self.p.value_dimension is None:
            # Pure count
            _, counts = np.unique(cat_vals, return_counts=True)
            agg_label = self.p.label or "Count"
            data = list(zip(unique_cats, counts))
        else:
            num_vals = element.dimension_values(self.p.value_dimension, expanded=True)
            results = []
            for cat in unique_cats:
                mask = cat_vals == cat
                results.append(self.p.function(num_vals[mask]))
            func_name = getattr(self.p.function, '__name__', 'agg')
            agg_label = self.p.label or f"{func_name}({self.p.value_dimension})"
            data = list(zip(unique_cats, results))

        return hv.Bars(data, kdims=[self.p.dimension], vdims=[agg_label])

Full working example with cross-filtering

import holoviews as hv import numpy as np import param from holoviews.core import Operation class categorical_agg(Operation): """Aggregate a categorical dimension, returning Bars. Preserves data lineage back to the source element so that link_selections can resolve all source dimensions during cross-filtering. """ dimension = param.String(doc="Categorical dimension to group by") value_dimension = param.String( default=None, allow_None=True, doc="Numeric dimension to aggregate. None means count rows.", ) function = param.Callable( default=np.size, doc="Aggregation function (np.sum, np.mean, np.std, np.min, np.max, ...)", ) label = param.String( default=None, allow_None=True, doc="Label for the value axis. Auto-generated if None.", ) def _process(self, element, key=None): cat_vals = element.dimension_values(self.p.dimension, expanded=True) unique_cats = np.unique(cat_vals) if self.p.value_dimension is None: # Pure count _, counts = np.unique(cat_vals, return_counts=True) agg_label = self.p.label or "Count" data = list(zip(unique_cats, counts)) else: num_vals = element.dimension_values(self.p.value_dimension, expanded=True) results = [] for cat in unique_cats: mask = cat_vals == cat results.append(self.p.function(num_vals[mask])) func_name = getattr(self.p.function, "__name__", "agg") agg_label = self.p.label or f"{func_name}({self.p.value_dimension})" data = list(zip(unique_cats, results)) return hv.Bars(data, kdims=[self.p.dimension], vdims=[agg_label]) import numpy as np import pandas as pd hv.extension("bokeh") rng = np.random.default_rng(42) df = pd.DataFrame( { "x": rng.normal(0, 1, 200), "y": rng.normal(0, 1, 200), "category": rng.choice(["A", "B", "C", "D"], 200), } ) from holoviews.operation import histogram ls = hv.link_selections.instance() points = hv.Points(df, kdims=["x", "y"], vdims=["category"]) scatter = ls(points) bars_count = ls(categorical_agg(points, dimension="category")) bars_mean = ls( categorical_agg(points, dimension="category", value_dimension="y", function=np.mean) ) hist_x = ls(histogram(points, dimension="x", num_bins=20)) layout = scatter + bars_count + bars_mean + hist_x import panel as pn pn.extension() pn.panel(layout, sizing_mode="stretch_both").servable()

Why this works

HoloViews operations maintain a reference to their source element. When link_selections encounters a selection expression like dim('x') > 0, it recurses into the operation's source (points) where x exists, applies the filter, then re-runs the operation on the filtered subset. Pre-aggregated hv.Bars lack this source reference, so the expression cannot resolve and raises CallbackError.

---

Documentation ask

The Linked Brushing user guide currently only demonstrates numeric dimensions with histogram. Please update it to:

1. Show the categorical_agg operation (once built in) as the recommended approach for categorical Bars, including examples of count, sum, mean, etc.
2. Document the general principle: operations that derive from a source element preserve lineage, enabling link_selections to cross-filter through them.
3. Demonstrate how to build and use a custom Operation with linked selections

---

Related issues

• #3842 — Original linked selections proposal
• PR #3951 — Initial link_selections implementation

[AR21SM]

@MarcSkovMadsen If possible, can I take this up?

[MarcSkovMadsen]

That would be awesome.

[MarcSkovMadsen]

There is a reference example below using the categorical_agg aggregation. It would be really awesome if it was possible to crossfilter by clicking the bars in addition to using the box and lasso selection tools.

energy-trading-crossfilter.mp4

Reference Example

"""Energy Trading Cross-Filtering Dashboard.

A cross-filtering dashboard for energy trading data using Panel,
HoloViews link_selections, and Panel Material UI widgets with a dark theme.
"""

import numpy as np
import pandas as pd
import param

import holoviews as hv
from holoviews.core import Operation
from holoviews.operation import histogram

import panel as pn
import panel_material_ui as pmui

pn.extension(throttled=True, theme="dark")
pmui.Paper.param.margin.default = 10

# ---------------------------------------------------------------------------
# Synthetic data generation
# ---------------------------------------------------------------------------

COMMODITIES = ["Power", "Gas", "Oil", "Coal", "Carbon"]
REGIONS = ["North America", "Europe", "Asia Pacific"]
TRADE_TYPES = ["Buy", "Sell"]
COUNTERPARTIES = [
    "Apex Energy", "BlueRock Trading", "Crest Commodities",
    "Delta Fuels", "Ember Markets", "FrostBridge Capital",
    "Granite Resources", "Helix Power Co",
]

# Price ranges per commodity (mean, std)
PRICE_PARAMS = {
    "Power": (55, 20),
    "Gas": (3.5, 1.2),
    "Oil": (75, 15),
    "Coal": (130, 30),
    "Carbon": (25, 8),
}

# Volume ranges per commodity (mean, std)
VOLUME_PARAMS = {
    "Power": (500, 200),
    "Gas": (10000, 4000),
    "Oil": (1000, 400),
    "Coal": (5000, 2000),
    "Carbon": (2000, 800),
}


def generate_data(n_rows: int = 2000, seed: int = 42) -> pd.DataFrame:
    """Generate synthetic energy trading data."""
    rng = np.random.default_rng(seed)

    commodities = rng.choice(COMMODITIES, size=n_rows)
    regions = rng.choice(REGIONS, size=n_rows)
    trade_types = rng.choice(TRADE_TYPES, size=n_rows)
    counterparties = rng.choice(COUNTERPARTIES, size=n_rows)

    timestamps = pd.Timestamp.now() - pd.to_timedelta(
        rng.uniform(0, 90, size=n_rows), unit="D"
    )

    prices = np.array([
        max(0.1, rng.normal(*PRICE_PARAMS[c])) for c in commodities
    ])
    volumes = np.array([
        max(10, rng.normal(*VOLUME_PARAMS[c])) for c in commodities
    ])

    # P&L: positive bias for buys in rising markets, random otherwise
    pnl = rng.normal(0, prices * volumes * 0.001, size=n_rows)

    df = pd.DataFrame({
        "timestamp": timestamps,
        "commodity": commodities,
        "region": regions,
        "trade_type": trade_types,
        "price": np.round(prices, 2),
        "volume": np.round(volumes, 1),
        "pnl": np.round(pnl, 2),
        "counterparty": counterparties,
    })
    # Numeric timestamp for HoloViews vdim
    df["timestamp_num"] = df["timestamp"].astype(np.int64) // 10**9
    return df


# ---------------------------------------------------------------------------
# Custom HoloViews Operation for categorical bar charts
# ---------------------------------------------------------------------------

class categorical_agg(Operation):
    """Aggregate a categorical dimension, returning Bars.

    Preserves data lineage back to the source element so that
    link_selections can resolve all source dimensions during cross-filtering.
    """

    dimension = param.String(doc="Categorical dimension to group by")
    value_dimension = param.String(
        default=None,
        allow_None=True,
        doc="Numeric dimension to aggregate. None means count rows.",
    )
    function = param.Callable(
        default=np.size,
        doc="Aggregation function (np.sum, np.mean, np.std, np.min, np.max, ...)",
    )
    label = param.String(
        default=None,
        allow_None=True,
        doc="Label for the value axis. Auto-generated if None.",
    )

    def _process(self, element, key=None):
        cat_vals = element.dimension_values(self.p.dimension, expanded=True)
        unique_cats = np.unique(cat_vals)

        if self.p.value_dimension is None:
            # Pure count
            _, counts = np.unique(cat_vals, return_counts=True)
            agg_label = self.p.label or "Count"
            data = list(zip(unique_cats, counts))
        else:
            num_vals = element.dimension_values(self.p.value_dimension, expanded=True)
            results = []
            for cat in unique_cats:
                mask = cat_vals == cat
                results.append(self.p.function(num_vals[mask]))
            func_name = getattr(self.p.function, "__name__", "agg")
            agg_label = self.p.label or f"{func_name}({self.p.value_dimension})"
            data = list(zip(unique_cats, results))

        return hv.Bars(data, kdims=[self.p.dimension], vdims=[agg_label])


# ---------------------------------------------------------------------------
# Dashboard component
# ---------------------------------------------------------------------------

class EnergyTradingDashboard(pn.viewable.Viewer):
    """Cross-filtering energy trading dashboard."""

    dark_theme = param.Boolean(default=True, allow_refs=True)

    def __init__(self, df: pd.DataFrame | None = None, **params):
        super().__init__(**params)
        self.df = df if df is not None else generate_data()
        self._ls, self._plots = self._build_plots()
        self._sidebar_components = self._build_sidebar()

    def _build_plots(self):
        """Create all HoloViews elements with link_selections."""
        df = self.df
        ls = hv.link_selections.instance()

        points = hv.Points(
            df,
            kdims=["price", "volume"],
            vdims=["commodity", "region", "trade_type", "pnl",
                    "timestamp_num", "counterparty"],
        )

        # 1. Price vs Volume scatter colored by commodity
        scatter = ls(points).opts(
            hv.opts.Points(
                color="commodity",
                cmap="Category10",
                size=5,
                responsive=True,
                height=380,
                title="Price vs Volume",
                xlabel="Price",
                ylabel="Volume",
                tools=["hover"],
            )
        )

        # 2-4. Numeric histograms (preserves lineage)
        hist_price = ls(histogram(points, dimension="price", num_bins=30)).opts(
            hv.opts.Histogram(
                responsive=True, height=300, title="Price Distribution",
                color="#4fc3f7",
            )
        )
        hist_volume = ls(histogram(points, dimension="volume", num_bins=30)).opts(
            hv.opts.Histogram(
                responsive=True, height=300, title="Volume Distribution",
                color="#81c784",
            )
        )
        hist_pnl = ls(histogram(points, dimension="pnl", num_bins=30)).opts(
            hv.opts.Histogram(
                responsive=True, height=300, title="P&L Distribution",
                color="#ffb74d",
            )
        )

        # 5-6. Categorical bars (custom Operation preserves lineage)
        bars_commodity = ls(categorical_agg(points, dimension="commodity")).opts(
            hv.opts.Bars(
                responsive=True, height=380, title="Trades by Commodity",
                color="#4fc3f7",
            )
        )
        bars_region = ls(categorical_agg(points, dimension="region")).opts(
            hv.opts.Bars(
                responsive=True, height=300, title="Trades by Region",
                color="#ce93d8",
            )
        )

        plots = {
            "scatter": scatter,
            "commodity_bars": bars_commodity,
            "price_hist": hist_price,
            "volume_hist": hist_volume,
            "pnl_hist": hist_pnl,
            "region_bars": bars_region,
        }
        return ls, plots

    def _wrap_plot(self, key: str) -> pmui.Paper:
        """Wrap a HoloViews plot in a Paper container."""
        return pmui.Paper(
            pn.pane.HoloViews(
                self._plots[key],
                sizing_mode="stretch_width",
                theme="dark_minimal",
            ),
            margin=10,
        )

    def _build_sidebar(self):
        """Build sidebar with KPIs and description."""
        df = self.df
        total_trades = len(df)
        total_volume = df["volume"].sum()
        total_pnl = df["pnl"].sum()

        description = pmui.Typography(
            "### Energy Trading Dashboard\n\n"
            "Explore energy trading data across commodities, regions, "
            "and counterparties. **Select data in any chart** to cross-filter all others.",
            sizing_mode="stretch_width",
        )

        icon_style = {"color": "primary.main"}

        kpi_trades = pmui.Paper(
            pmui.Typography(
                '<span class="material-icons" style="font-size: 2rem;">receipt_long</span>',
                sizing_mode="fixed", width=40, height=40, sx=icon_style,
            ),
            pmui.Typography(f"**Total Trades**\n\n{total_trades:,}", sizing_mode="stretch_width"),
            direction="row",
            sx={"padding": "12px", "alignItems": "center", "gap": "12px"},
            margin=10,
        )

        vol_display = f"{total_volume:,.0f}"
        kpi_volume = pmui.Paper(
            pmui.Typography(
                '<span class="material-icons" style="font-size: 2rem;">bar_chart</span>',
                sizing_mode="fixed", width=40, height=40, sx=icon_style,
            ),
            pmui.Typography(f"**Total Volume**\n\n{vol_display}", sizing_mode="stretch_width"),
            direction="row",
            sx={"padding": "12px", "alignItems": "center", "gap": "12px"},
            margin=10,
        )

        pnl_color = "success" if total_pnl >= 0 else "error"
        kpi_pnl = pmui.Paper(
            pmui.Typography(
                '<span class="material-icons" style="font-size: 2rem;">trending_up</span>',
                sizing_mode="fixed", width=40, height=40,
                sx={"color": f"{pnl_color}.main"},
            ),
            pmui.Typography(
                f"**Total P&L**\n\n${total_pnl:,.2f}",
                sizing_mode="stretch_width",
            ),
            direction="row",
            sx={"padding": "12px", "alignItems": "center", "gap": "12px"},
            margin=10,
        )

        info = pmui.Typography(
            "**How to use:**\n\n"
            "- Box-select on any chart to filter\n"
            "- Click a bar to filter by category\n"
            "- Selections propagate across all charts\n"
            "- Reset by clicking empty space",
            variant="body2",
            sizing_mode="stretch_width",
            sx={"mt": 2},
        )

        return [description, kpi_trades, kpi_volume, kpi_pnl, info]

    def __panel__(self):
        """Return layout for notebook use."""
        grid = pmui.Grid(
            pmui.Grid(self._wrap_plot("scatter"), size={"md": 6, "xs": 12}),
            pmui.Grid(self._wrap_plot("commodity_bars"), size={"md": 6, "xs": 12}),
            pmui.Grid(self._wrap_plot("price_hist"), size={"md": 4, "xs": 12}),
            pmui.Grid(self._wrap_plot("volume_hist"), size={"md": 4, "xs": 12}),
            pmui.Grid(self._wrap_plot("pnl_hist"), size={"md": 4, "xs": 12}),
            pmui.Grid(self._wrap_plot("region_bars"), size={"md": 6, "xs": 12}),
            container=True,
            spacing=2,
            margin=15,
        )
        return grid

    @classmethod
    def create_app(cls, **params) -> pmui.Page:
        """Create a full Page app for serving."""
        instance = cls(**params)
        page = pmui.Page(
            title="Energy Trading Dashboard",
            sidebar=instance._sidebar_components,
            main=[instance.__panel__()],
            dark_theme=instance.dark_theme,
        )
        # Sync Page theme back to component
        instance.dark_theme = page.param.dark_theme
        return page


# ---------------------------------------------------------------------------
# Serve
# ---------------------------------------------------------------------------

if __name__ == "__main__":
    EnergyTradingDashboard.create_app().show(port=5007, open=True)
elif pn.state.served:
    EnergyTradingDashboard.create_app().servable()

Related Issues

• temporary white while dark themed app loads panel-extensions/panel-material-ui#572

[AR21SM]

hi @MarcSkovMadsen could you verify this #6804 Thank you :)