rasterize(labels, value_key=...) crashes for categorical table columns and for labels absent from the table

[!NOTE]
This whole message is AI-generated. The issue was automatically discovered and reported by an AI agent (Claude) during an autonomous bug hunt on the spatialdata code base. It has not been verified or triaged by a human yet; the needs: triage label is set so that a maintainer can confirm it. The reproduction script below was executed by the agent in an isolated environment (see Environment) and its output is pasted verbatim.

Summary

value_key="celltype" (categorical) → TypeError: Cannot interpret 'CategoricalDtype(...)' as a data type; a label present in the raster but not in the table → IndexError: index 3 is out of bounds for axis 0 with size 3 (labels below max_index but missing from the table silently get value 0).

Severity (agent's assessment): medium — colouring a labels raster by a categorical annotation is the primary use case and is documented as supported

Where: src/spatialdata/_core/operations/rasterize.py::rasterize (assigner = np.zeros(max_index + 1, dtype=values.dtype); assigner[rasterized])

Expected behaviour

Categoricals are mapped to codes (+ label_index_to_category, as rasterize_shapes_points does) and unannotated labels become background.

Reproduction

Save as repro.py and run uv run repro.py (the PEP 723 header pins spatialdata to the commit the bug was found on; replace the URL fragment with @main to test the current main branch).

# /// script
# requires-python = ">=3.12"
# dependencies = [
#     "spatialdata @ git+https://github.com/scverse/spatialdata.git@ccf1ea048d054b6624214bf618008a9f9ae223e0",
# ]
# ///
"""rasterize(labels, value_key=...) fails for categorical table columns and for labels absent from the table."""
import warnings
import numpy as np
import pandas as pd
from anndata import AnnData
from spatialdata import SpatialData, rasterize
from spatialdata.models import Labels2DModel, TableModel

warnings.simplefilter("ignore")
labels = Labels2DModel.parse(np.array([[0, 1, 2], [3, 3, 0]], dtype=np.uint16))
obs = pd.DataFrame({"region": pd.Categorical(["lab"] * 3), "instance_id": [1, 2, 3], "score": [10.0, 20.0, 30.0], "celltype": pd.Categorical(["a", "b", "a"])})
table = TableModel.parse(AnnData(X=np.zeros((3, 1)), obs=obs), region="lab", region_key="region", instance_key="instance_id")
sdata = SpatialData(labels={"lab": labels}, tables={"t": table})
kwargs = dict(axes=("x", "y"), min_coordinate=[0, 0], max_coordinate=[3, 2], target_coordinate_system="global", target_unit_to_pixels=1, sdata=sdata, table_name="t")
bug = False
for value_key in ["score", "celltype"]:
    try:
        r = rasterize("lab", value_key=value_key, **kwargs)
        print(f"value_key={value_key:8s}: OK -> {np.asarray(r.data.compute()).ravel().tolist()}")
    except Exception as e:  # noqa: BLE001
        print(f"value_key={value_key:8s}: {type(e).__name__}: {str(e)[:90]}")
        bug = True
# label 3 present in the raster but not annotated by the table
obs2 = obs.iloc[:2].copy()
table2 = TableModel.parse(AnnData(X=np.zeros((2, 1)), obs=obs2), region="lab", region_key="region", instance_key="instance_id")
sdata2 = SpatialData(labels={"lab": labels}, tables={"t": table2})
try:
    r = rasterize("lab", value_key="score", **{**kwargs, "sdata": sdata2})
    print("label 3 missing from table: OK ->", np.asarray(r.data.compute()).ravel().tolist())
except Exception as e:  # noqa: BLE001
    print("label 3 missing from table:", type(e).__name__, str(e)[:90])
    bug = True
print("VERDICT:", "BUG REPRODUCED" if bug else "NOT REPRODUCED")

Observed output

value_key=score   : OK -> [0.0, 10.0, 20.0, 30.0, 30.0, 0.0]
value_key=celltype: TypeError: Cannot interpret 'CategoricalDtype(categories=['a', 'b'], ordered=False, categories_dtype=
label 3 missing from table: IndexError index 3 is out of bounds for axis 0 with size 3
VERDICT: BUG REPRODUCED

Possible fix direction (unverified)

Size the lookup table by max(labels.max(), values.index.max()) + 1 (or use a pandas reindex with fill value) and handle categoricals via codes.

Environment

uv run repro.py with the PEP 723 metadata in the script (fresh, isolated environment; spatialdata built from main @ ccf1ea0 (2026-08-28); Python 3.13, latest releases of the dependencies at run time: pandas 3.0, anndata 0.13, zarr 3.3, dask 2026.8, numpy 2.5, geopandas 1.1, shapely 2.1). macOS (arm64). Also reproduced in a second environment with pandas 2.3.3 / anndata 0.12.11 / numpy 2.4.4 / zarr 3.2.1.

Automatically generated; discovered by an AI agent (Claude) and not yet reviewed by a human.

Start in src/spatialdata/_core/operations/rasterize.py::rasterize and run the supplied repro.py with uv run repro.py. Verify both numeric and categorical value_key cases, plus labels missing from the table; done means categorical values are handled and unannotated labels become background without exceptions.