"""Return whether legend/colorbar decorations should be shown.

if color_vector is None:

return False

cv = np.asarray(color_vector)

if cv.size == 0:

return False

first = cv.flat[0]

if not (cv == first).all():

return True

na_hex = na_color.get_hex()

if isinstance(first, str) and first.startswith("#") and na_hex.startswith("#"):

return _hex_no_alpha(first) != _hex_no_alpha(na_hex)

"""Log the datashader backend and effective reduction being used."""

effective = ds_reduction if ds_reduction is not None else default

logger.info(

f"Using '{method}' backend with '{effective}' as reduction"

" method to speed up plotting. Depending on the reduction method, the value"

" range of the plot might change. Set method to 'matplotlib' to disable"

" this behaviour."

sdata_filt: sd.SpatialData,

element: str,

df: pd.DataFrame,

transformation: Any,

coordinate_system: str,

) -> None:

"""Re-register a points DataFrame in *sdata_filt* with its transformation."""

dd_frame = dask.dataframe.from_pandas(df, npartitions=1)

sdata_filt.points[element] = PointsModel.parse(dd_frame, coordinates={"x": "x", "y": "y"})

set_transformation(

element=sdata_filt.points[element],

transformation=transformation,

to_coordinate_system=coordinate_system,

groups: str | list[str] | None,

color_source_vector: pd.Categorical | None,

col_for_color: str | None,

) -> None:

"""Warn when ``groups`` is set but coloring is continuous (no categorical source)."""

if groups is not None and color_source_vector is None and col_for_color is not None:

logger.warning(

f"`groups` is ignored when coloring by continuous column '{col_for_color}'. "

"`groups` filters categories of the column specified via `color`; "

"it has no effect on continuous data."

groups: str | list[str],

color_source_vector: pd.Categorical,

col_for_color: str | None = None,

) -> None:

"""Warn when ``groups`` contains values absent from the color column's categories."""

groups_set = {groups} if isinstance(groups, str) else set(groups)

missing = groups_set - set(color_source_vector.categories)

if not missing:

return

col_label = f" '{col_for_color}'" if col_for_color else " the color column"

try:

missing_str = str(sorted(missing))

except TypeError:

missing_str = str(list(missing))

if missing == groups_set:

logger.warning(

f"None of the requested groups {missing_str} were found in{col_label}. "

"This usually means `groups` refers to values from a different column than `color`. "

"The `groups` parameter selects categories of the column specified via `color`."

)

else:

try:

cats_str = str(sorted(color_source_vector.categories))

except TypeError:

cats_str = str(list(color_source_vector.categories))

logger.warning(

f"Groups {missing_str} were not found in{col_label} and will be ignored. Available categories: {cats_str}."

groups: str | list[str],

color_source_vector: pd.Categorical,

color_vector: pd.Series | np.ndarray | list[str],

) -> tuple[np.ndarray, pd.Categorical, np.ndarray]:

"""Return a boolean mask and filtered color vectors for groups filtering.

keep = color_source_vector.isin(groups)

filtered_csv = color_source_vector[keep]

filtered_cv = np.asarray(color_vector)[keep]

"""Split colorbar params into layout hints, Matplotlib kwargs, and label override."""

layout: dict[str, object] = {}

cbar_kwargs: dict[str, object] = {}

label_override: str | None = None

for key, value in (params or {}).items():

key_lower = key.lower()

if key_lower in {"loc", "location"}:

layout["location"] = value

elif key_lower == "width" or key_lower == "fraction":

layout["fraction"] = value

elif key_lower == "pad":

layout["pad"] = value

elif key_lower == "label":

label_override = None if value is None else str(value)

else:

cbar_kwargs[key] = value

colorbar_params: dict[str, object] | None, fallback: str | None, *, is_default_channel_name: bool = False

) -> str | None:

"""Pick a colorbar label from params or fall back to provided value."""

_, _, label = _split_colorbar_params(colorbar_params)

if label is not None:

return label

if is_default_channel_name:

return None

colorbar: bool | str | None,

*,

has_mappable: bool,

is_continuous: bool,

auto_condition: bool = True,

) -> bool:

"""Resolve colorbar setting to a final boolean request."""

if not has_mappable or not is_continuous:

return False

if colorbar is True:

return True

if colorbar in {False, None}:

return False

color_source_vector: pd.Series | None,

color_vector: Any,

) -> ListedColormap:

"""Build a ListedColormap from a color vector, filtering out NaN entries when categorical."""

if color_source_vector is None:

return ListedColormap(dict.fromkeys(color_vector))

ax: matplotlib.axes.SubplotBase,

cax: ScalarMappable | None,

fig_params: FigParams,

adata: AnnData | None,

col_for_color: str | None,

color_source_vector: pd.Series | None,

color_vector: Any,

palette: ListedColormap | list[str] | None,

alpha: float,

na_color: Color,

legend_params: LegendParams,

colorbar: bool | str | None,

colorbar_params: dict[str, object] | None,

colorbar_requests: list[ColorbarSpec] | None,

scalebar_params: ScalebarParams,

) -> None:

"""Add legend, colorbar, and scalebar decorations if the color vector warrants them."""

if not _want_decorations(color_vector, na_color):

return

if palette is None:

palette = _make_palette(color_source_vector, color_vector)

if color_source_vector is not None and hasattr(color_source_vector, "remove_unused_categories"):

color_source_vector = color_source_vector.remove_unused_categories()

wants_colorbar = _should_request_colorbar(

colorbar,

has_mappable=cax is not None,

is_continuous=col_for_color is not None and color_source_vector is None,

)

_decorate_axs(

ax=ax,

cax=cax,

fig_params=fig_params,

adata=adata,

value_to_plot=col_for_color,

color_source_vector=color_source_vector,

color_vector=color_vector,

palette=palette,

alpha=alpha,

na_color=na_color,

legend_fontsize=legend_params.legend_fontsize,

legend_fontweight=legend_params.legend_fontweight,

legend_loc=legend_params.legend_loc,

legend_fontoutline=legend_params.legend_fontoutline,

na_in_legend=legend_params.na_in_legend,

colorbar=wants_colorbar and legend_params.colorbar,

colorbar_params=colorbar_params,

colorbar_requests=colorbar_requests,

colorbar_label=_resolve_colorbar_label(

colorbar_params,

col_for_color if isinstance(col_for_color, str) else None,

),

scalebar_dx=scalebar_params.scalebar_dx,

scalebar_units=scalebar_params.scalebar_units,

sdata: sd.SpatialData,

render_params: ShapesRenderParams,

coordinate_system: str,

ax: matplotlib.axes.SubplotBase,

fig_params: FigParams,

scalebar_params: ScalebarParams,

legend_params: LegendParams,

colorbar_requests: list[ColorbarSpec] | None = None,

) -> None:

_log_context.set("render_shapes")

element = render_params.element

col_for_color = render_params.col_for_color

groups = render_params.groups

table_layer = render_params.table_layer

sdata_filt = sdata.filter_by_coordinate_system(

coordinate_system=coordinate_system,

filter_tables=bool(render_params.table_name),

)

table_name = render_params.table_name

if table_name is None:

table = None

shapes = sdata_filt[element]

else:

# Workaround for upstream spatialdata bug (scverse/spatialdata#1099):

# join_spatialelement_table calls table.obs.reset_index() which fails when

# the obs index name matches an existing column (e.g. "EntityID" in Merfish data).

# Temporarily drop the conflicting index name for the join, then restore it.

_obs = sdata[table_name].obs

_saved_index_name = _obs.index.name

if _saved_index_name is not None and _saved_index_name in _obs.columns:

_obs.index.name = None

try:

element_dict, joined_table = join_spatialelement_table(

sdata, spatial_element_names=element, table_name=table_name, how="inner"

)

finally:

_obs.index.name = _saved_index_name

sdata_filt[element] = shapes = element_dict[element]

joined_table.uns["spatialdata_attrs"]["region"] = (

joined_table.obs[joined_table.uns["spatialdata_attrs"]["region_key"]].unique().tolist()

)

sdata_filt[table_name] = table = joined_table

shapes = sdata_filt[element]

# get color vector (categorical or continuous)

color_source_vector, color_vector, _ = _set_color_source_vec(

sdata=sdata_filt,

element=sdata_filt[element],

element_name=element,

value_to_plot=col_for_color,

groups=groups,

palette=render_params.palette,

na_color=render_params.color if render_params.color is not None else render_params.cmap_params.na_color,

cmap_params=render_params.cmap_params,

table_name=table_name,

table_layer=table_layer,

coordinate_system=coordinate_system,

)

values_are_categorical = color_source_vector is not None

_warn_groups_ignored_continuous(groups, color_source_vector, col_for_color)

if groups is not None and color_source_vector is not None:

_warn_missing_groups(groups, color_source_vector, col_for_color)

# When groups are specified, filter out non-matching elements by default.

# Only show non-matching elements if the user explicitly sets na_color.

_na = render_params.cmap_params.na_color

if groups is not None and color_source_vector is not None and (_na.default_color_set or _na.alpha == "00"):

keep, color_source_vector, color_vector = _filter_groups_transparent_na(

groups, color_source_vector, color_vector

)

shapes = shapes[keep].reset_index(drop=True)

if len(shapes) == 0:

return

sdata_filt[element] = shapes

# color_source_vector is None when the values aren't categorical

if values_are_categorical and render_params.transfunc is not None:

color_vector = render_params.transfunc(color_vector)

norm = copy(render_params.cmap_params.norm)

if len(color_vector) == 0:

color_vector = [render_params.cmap_params.na_color.get_hex_with_alpha()]

# continuous case: leave NaNs as NaNs; utils maps them to na_color during draw

if color_source_vector is None and not values_are_categorical:

_series = color_vector if isinstance(color_vector, pd.Series) else pd.Series(color_vector)

try:

color_vector = np.asarray(_series, dtype=float)

except (TypeError, ValueError):

nan_count = int(_series.isna().sum())

if nan_count:

logger.warning(

f"Found {nan_count} NaN values in color data. "

"These observations will be colored with the 'na_color'."

)

color_vector = _series.to_numpy()

else:

if np.isnan(color_vector).any():

nan_count = int(np.isnan(color_vector).sum())

logger.warning(

f"Found {nan_count} NaN values in color data. "

"These observations will be colored with the 'na_color'."

)

palette = _make_palette(color_source_vector, color_vector)

has_valid_color = (

len(set(color_vector)) != 1

or list(set(color_vector))[0] != render_params.cmap_params.na_color.get_hex_with_alpha()

)

if has_valid_color and color_source_vector is not None and col_for_color is not None:

# necessary in case different shapes elements are annotated with one table

color_source_vector = color_source_vector.remove_unused_categories()

# Apply the transformation to the PatchCollection's paths

trans, trans_data = _prepare_transformation(sdata_filt.shapes[element], coordinate_system)

shapes = gpd.GeoDataFrame(shapes, geometry="geometry")

# convert shapes if necessary

if render_params.shape is not None:

current_type = shapes["geometry"].type

if not (render_params.shape == "circle" and (current_type == "Point").all()):

logger.info(f"Converting {shapes.shape[0]} shapes to {render_params.shape}.")

max_extent = np.max(

[shapes.total_bounds[2] - shapes.total_bounds[0], shapes.total_bounds[3] - shapes.total_bounds[1]]

)

shapes = _convert_shapes(shapes, render_params.shape, max_extent)

shapes = _validate_polygons(shapes)

# Determine which method to use for rendering

method = render_params.method

if method is None:

method = "datashader" if len(shapes) > 10000 else "matplotlib"

_default_reduction: _DsReduction = "max"

if method != "matplotlib":

_log_datashader_method(method, render_params.ds_reduction, _default_reduction)

if method == "datashader":

_geometry = shapes["geometry"]

is_point = _geometry.type == "Point"

# Handle circles encoded as points with radius

if is_point.any():

radius_values = shapes[is_point]["radius"]

# Convert to numeric, replacing non-numeric values with NaN

radius_numeric = pd.to_numeric(radius_values, errors="coerce")

scale = radius_numeric * render_params.scale

shapes.loc[is_point, "geometry"] = _geometry[is_point].buffer(scale.to_numpy())

# Handle polygon/multipolygon scaling

is_polygon = _geometry.type.isin(["Polygon", "MultiPolygon"])

if is_polygon.any() and render_params.scale != 1.0:

from shapely import affinity

shapes.loc[is_polygon, "geometry"] = _geometry[is_polygon].apply(

lambda geom: affinity.scale(geom, xfact=render_params.scale, yfact=render_params.scale)

)

# apply transformations to the individual points

tm = trans.get_matrix()

transformed_geometry = shapes["geometry"].transform(

lambda x: (np.hstack([x, np.ones((x.shape[0], 1))]) @ tm.T)[:, :2]

)

transformed_element = ShapesModel.parse(

gpd.GeoDataFrame(

data=shapes.drop("geometry", axis=1),

geometry=transformed_geometry,

)

)

plot_width, plot_height, x_ext, y_ext, factor = _get_extent_and_range_for_datashader_canvas(

transformed_element, "global", ax, fig_params

)

cvs = ds.Canvas(plot_width=plot_width, plot_height=plot_height, x_range=x_ext, y_range=y_ext)

# in case we are coloring by a column in table

if col_for_color is not None and col_for_color not in transformed_element.columns:

# Ensure color vector length matches the number of shapes

if len(color_vector) != len(transformed_element):

if len(color_vector) == 1:

# If single color, broadcast to all shapes

color_vector = [color_vector[0]] * len(transformed_element)

else:

logger.warning(

f"Color vector length ({len(color_vector)}) does not match element count "

f"({len(transformed_element)}). This may indicate a bug."

)

if len(color_vector) > len(transformed_element):

color_vector = color_vector[: len(transformed_element)]

else:

na_color = render_params.cmap_params.na_color.get_hex_with_alpha()

color_vector = list(color_vector) + [na_color] * (len(transformed_element) - len(color_vector))

transformed_element[col_for_color] = color_vector if color_source_vector is None else color_source_vector

# Render shapes with datashader

color_by_categorical = col_for_color is not None and color_source_vector is not None

if color_by_categorical:

cat_series = transformed_element[col_for_color]

if not isinstance(cat_series.dtype, pd.CategoricalDtype):

cat_series = cat_series.astype("category")

transformed_element[col_for_color] = cat_series

agg, reduction_bounds, nan_agg = _ds_aggregate(

cvs,

transformed_element,

col_for_color,

color_by_categorical,

render_params.ds_reduction,

_default_reduction,

"shapes",

)

agg, color_span = _apply_ds_norm(agg, norm)

na_color_hex = _hex_no_alpha(render_params.cmap_params.na_color.get_hex())

color_key = _build_color_key(

transformed_element,

col_for_color,

color_by_categorical,

color_vector,

na_color_hex,

)

nan_shaded = None

if color_by_categorical or col_for_color is None:

shaded = _ds_shade_categorical(

agg,

color_key,

color_vector,

render_params.fill_alpha,

)

else:

shaded, nan_shaded, reduction_bounds = _ds_shade_continuous(

agg,

color_span,

norm,

render_params.cmap_params.cmap,

render_params.fill_alpha,

reduction_bounds,

nan_agg,

na_color_hex,

)

_render_ds_outlines(cvs, transformed_element, render_params, fig_params, ax, factor, x_ext + y_ext)

_cax = _render_ds_image(

ax,

shaded,

factor,

render_params.zorder,

x_ext + y_ext,

nan_result=nan_shaded,

)

cax = _build_ds_colorbar(reduction_bounds, norm, render_params.cmap_params.cmap)

elif method == "matplotlib":

# render outlines separately to ensure they are always underneath the shape

if render_params.outline_alpha[0] > 0 and isinstance(render_params.outline_params.outer_outline_color, Color):

_cax = _get_collection_shape(

shapes=shapes,

s=render_params.scale,

c=np.array(["white"]), # hack, will be invisible bc fill_alpha=0

render_params=render_params,

rasterized=sc_settings._vector_friendly,

cmap=None,

norm=None,

fill_alpha=0.0,

outline_alpha=render_params.outline_alpha[0],

outline_color=render_params.outline_params.outer_outline_color.get_hex(),

linewidth=render_params.outline_params.outer_outline_linewidth,

zorder=render_params.zorder,

# **kwargs,

)

cax = ax.add_collection(_cax)

# Transform the paths in PatchCollection

for path in _cax.get_paths():

path.vertices = trans.transform(path.vertices)

if render_params.outline_alpha[1] > 0 and isinstance(render_params.outline_params.inner_outline_color, Color):

_cax = _get_collection_shape(

shapes=shapes,

s=render_params.scale,

c=np.array(["white"]), # hack, will be invisible bc fill_alpha=0

render_params=render_params,

rasterized=sc_settings._vector_friendly,

cmap=None,

norm=None,

fill_alpha=0.0,

outline_alpha=render_params.outline_alpha[1],

outline_color=render_params.outline_params.inner_outline_color.get_hex(),

linewidth=render_params.outline_params.inner_outline_linewidth,

zorder=render_params.zorder,

# **kwargs,

)

cax = ax.add_collection(_cax)

# Transform the paths in PatchCollection

for path in _cax.get_paths():

path.vertices = trans.transform(path.vertices)

_cax = _get_collection_shape(

shapes=shapes,

s=render_params.scale,

c=color_vector.copy(), # copy bc c is modified in _get_collection_shape

render_params=render_params,

rasterized=sc_settings._vector_friendly,

cmap=render_params.cmap_params.cmap,

norm=norm,

fill_alpha=render_params.fill_alpha,

outline_alpha=0.0,

zorder=render_params.zorder,

# **kwargs,

)

cax = ax.add_collection(_cax)

# Transform the paths in PatchCollection

for path in _cax.get_paths():

path.vertices = trans.transform(path.vertices)

if not values_are_categorical:

# Respect explicit vmin/vmax; otherwise derive from finite numeric values, falling back to [0, 1] if unavailable

vmin = render_params.cmap_params.norm.vmin

vmax = render_params.cmap_params.norm.vmax

if vmin is None or vmax is None:

numeric_values = pd.to_numeric(np.asarray(color_vector), errors="coerce")

finite_mask = np.isfinite(numeric_values)

if finite_mask.any():

data_min = float(np.nanmin(numeric_values[finite_mask]))

data_max = float(np.nanmax(numeric_values[finite_mask]))

if vmin is None:

vmin = data_min

if vmax is None:

vmax = data_max

else:

if vmin is None:

vmin = 0.0

if vmax is None:

vmax = 1.0

_cax.set_clim(vmin=vmin, vmax=vmax)

_add_legend_and_colorbar(

ax=ax,

cax=cax,

fig_params=fig_params,

adata=table,

col_for_color=col_for_color,

color_source_vector=color_source_vector,

color_vector=color_vector,

palette=palette,

alpha=render_params.fill_alpha,

na_color=render_params.cmap_params.na_color,

legend_params=legend_params,

colorbar=render_params.colorbar,

colorbar_params=render_params.colorbar_params,

colorbar_requests=colorbar_requests,

scalebar_params=scalebar_params,

sdata: sd.SpatialData,

render_params: PointsRenderParams,

coordinate_system: str,

ax: matplotlib.axes.SubplotBase,

fig_params: FigParams,

scalebar_params: ScalebarParams,

legend_params: LegendParams,

colorbar_requests: list[ColorbarSpec] | None = None,

) -> None:

_log_context.set("render_points")

element = render_params.element

col_for_color = render_params.col_for_color

table_name = render_params.table_name

table_layer = render_params.table_layer

color = render_params.color.get_hex() if render_params.color else None

groups = render_params.groups

palette = render_params.palette

if isinstance(groups, str):

groups = [groups]

sdata_filt = sdata.filter_by_coordinate_system(

coordinate_system=coordinate_system,

# keep tables intact; we pick the right rows ourselves via the table metadata

filter_tables=False,

)

points = sdata.points[element]

coords = ["x", "y"]

if table_name is not None and col_for_color not in points.columns:

logger.warning(

f"Annotating points with {col_for_color} which is stored in the table `{table_name}`. "

f"To improve performance, it is advisable to store point annotations directly in the .parquet file."

)

if col_for_color is None or (

table_name is not None

and (col_for_color in sdata_filt[table_name].obs.columns or col_for_color in sdata_filt[table_name].var_names)

):

points = points[coords].compute()

else:

coords += [col_for_color]

points = points[coords].compute()

added_color_from_table = False

if col_for_color is not None and col_for_color not in points.columns:

color_values = get_values(

value_key=col_for_color,

sdata=sdata_filt,

element_name=element,

table_name=table_name,

table_layer=table_layer,

)

points = points.merge(

color_values[[col_for_color]],

how="left",

left_index=True,

right_index=True,

)

added_color_from_table = True

n_points = len(points)

points_pd_with_color = points

# When we pull colors from a table, keep the raw points (with color) for later,

# but strip the color column from the model we register in sdata so color lookup

# keeps using the table instead of seeing duplicates on the points dataframe.

points_for_model = (

points_pd_with_color.drop(columns=[col_for_color], errors="ignore")

if added_color_from_table and col_for_color is not None

else points_pd_with_color

)

# we construct an anndata to hack the plotting functions

if table_name is None:

adata = AnnData(

X=points[["x", "y"]].values,

obs=points[coords].reset_index(),

dtype=points[["x", "y"]].values.dtype,

)

else:

matched_table = match_table_to_element(sdata=sdata, element_name=element, table_name=table_name)

adata_obs = matched_table.obs.copy()

# if the points are colored by values in X (or a different layer), add the values to obs

if col_for_color in matched_table.var_names:

if table_layer is None:

adata_obs[col_for_color] = matched_table[:, col_for_color].X.flatten().copy()

else:

adata_obs[col_for_color] = matched_table[:, col_for_color].layers[table_layer].flatten().copy()

adata = AnnData(

X=points[["x", "y"]].values,

obs=adata_obs,

dtype=points[["x", "y"]].values.dtype,

uns=matched_table.uns,

)

sdata_filt[table_name] = adata

# we can modify the sdata because of dealing with a copy

# Convert back to dask dataframe to modify sdata

transformation_in_cs = sdata_filt.points[element].attrs["transform"][coordinate_system]

_reparse_points(sdata_filt, element, points_for_model, transformation_in_cs, coordinate_system)

if col_for_color is not None:

assert isinstance(col_for_color, str)

cols = sc.get.obs_df(adata, [col_for_color])

# maybe set color based on type

if isinstance(cols[col_for_color].dtype, pd.CategoricalDtype):

uns_color_key = f"{col_for_color}_colors"

if uns_color_key in adata.uns:

_maybe_set_colors(

source=adata,

target=adata,

key=col_for_color,

palette=palette,

)

# when user specified a single color, we emulate the form of `na_color` and use it

default_color = (

render_params.color if col_for_color is None and color is not None else render_params.cmap_params.na_color

)

assert isinstance(default_color, Color) # shut up mypy

color_element = sdata_filt.points[element]

# Always pass the table through to color resolution; dropping the color column

# from the registered points (see above) avoids duplicate-origin ambiguities.

color_table_name = table_name

# Reuse color data already loaded from the table to avoid a redundant get_values() call.

_preloaded = points_pd_with_color[col_for_color] if added_color_from_table and col_for_color is not None else None

color_source_vector, color_vector, _ = _set_color_source_vec(

sdata=sdata_filt,

element=color_element,

element_name=element,

value_to_plot=col_for_color,

groups=groups,

palette=palette,

na_color=default_color,

cmap_params=render_params.cmap_params,

alpha=render_params.alpha,

table_name=color_table_name,

render_type="points",

coordinate_system=coordinate_system,

preloaded_color_data=_preloaded,

)

if added_color_from_table and col_for_color is not None:

_reparse_points(sdata_filt, element, points_pd_with_color, transformation_in_cs, coordinate_system)

_warn_groups_ignored_continuous(groups, color_source_vector, col_for_color)

if groups is not None and color_source_vector is not None:

_warn_missing_groups(groups, color_source_vector, col_for_color)

# When groups are specified, filter out non-matching elements by default.

# Only show non-matching elements if the user explicitly sets na_color.

_na = render_params.cmap_params.na_color

if groups is not None and color_source_vector is not None and (_na.default_color_set or _na.alpha == "00"):

keep, color_source_vector, color_vector = _filter_groups_transparent_na(

groups, color_source_vector, color_vector

)

n_points = int(keep.sum())

if n_points == 0:

return

# filter the materialized points, adata, and re-register in sdata_filt

points = points[keep].reset_index(drop=True)

adata = adata[keep]

_reparse_points(sdata_filt, element, points, transformation_in_cs, coordinate_system)

# color_source_vector is None when the values aren't categorical

if color_source_vector is None and render_params.transfunc is not None:

color_vector = render_params.transfunc(color_vector)

trans, trans_data = _prepare_transformation(sdata.points[element], coordinate_system, ax)

norm = copy(render_params.cmap_params.norm)

method = render_params.method

if method is None:

method = "datashader" if n_points > 10000 else "matplotlib"

_default_reduction: _DsReduction = "sum"

if method == "datashader":

_log_datashader_method(method, render_params.ds_reduction, _default_reduction)

# NOTE: s in matplotlib is in units of points**2

# use dpi/100 as a factor for cases where dpi!=100

px = int(np.round(np.sqrt(render_params.size) * (fig_params.fig.dpi / 100)))

# Apply transformations and materialize to pandas immediately so

# datashader aggregates without dask scheduler overhead. See #379.

transformed_element = PointsModel.parse(

trans.transform(sdata_filt.points[element][["x", "y"]]),

annotation=sdata_filt.points[element][sdata_filt.points[element].columns.drop(["x", "y"])],

transformations={coordinate_system: Identity()},

).compute()

plot_width, plot_height, x_ext, y_ext, factor = _datashader_canvas_from_dataframe(

transformed_element, ax, fig_params

)

# use datashader for the visualization of points

cvs = ds.Canvas(plot_width=plot_width, plot_height=plot_height, x_range=x_ext, y_range=y_ext)

# ensure color column exists on the transformed element with positional alignment

if col_for_color is not None and col_for_color not in transformed_element.columns:

series_index = transformed_element.index

if color_source_vector is not None:

if isinstance(color_source_vector, dd.Series):

color_source_vector = color_source_vector.compute()

source_series = (

color_source_vector.reindex(series_index)

if isinstance(color_source_vector, pd.Series)

else pd.Series(color_source_vector, index=series_index)

)

transformed_element[col_for_color] = source_series

else:

if isinstance(color_vector, dd.Series):

color_vector = color_vector.compute()

color_series = (

color_vector.reindex(series_index)

if isinstance(color_vector, pd.Series)

else pd.Series(color_vector, index=series_index)

)

transformed_element[col_for_color] = color_series

color_dtype = transformed_element[col_for_color].dtype if col_for_color is not None else None

color_by_categorical = col_for_color is not None and (

color_source_vector is not None

or isinstance(color_dtype, pd.CategoricalDtype)

or pd.api.types.is_object_dtype(color_dtype)

or pd.api.types.is_string_dtype(color_dtype)

)

if color_by_categorical and not isinstance(color_dtype, pd.CategoricalDtype):

transformed_element[col_for_color] = transformed_element[col_for_color].astype("category")

agg, reduction_bounds, nan_agg = _ds_aggregate(

cvs,

transformed_element,

col_for_color,

color_by_categorical,

render_params.ds_reduction,

_default_reduction,

"points",

)

agg, color_span = _apply_ds_norm(agg, norm)

na_color_hex = _hex_no_alpha(render_params.cmap_params.na_color.get_hex())

color_key = _build_color_key(

transformed_element,

col_for_color,

color_by_categorical,

color_vector,

na_color_hex,

)

if (

color_vector is not None

and len(color_vector) > 0

and isinstance(color_vector[0], str)

and color_vector[0].startswith("#")

):

color_vector = np.asarray([_hex_no_alpha(c) for c in color_vector])

nan_shaded = None

if color_by_categorical or col_for_color is None:

shaded = _ds_shade_categorical(

agg,

color_key,

color_vector,

render_params.alpha,

spread_px=px,

)

else:

shaded, nan_shaded, reduction_bounds = _ds_shade_continuous(

agg,

color_span,

norm,

render_params.cmap_params.cmap,

render_params.alpha,

reduction_bounds,

nan_agg,

na_color_hex,

spread_px=px,

ds_reduction=render_params.ds_reduction,

)

_render_ds_image(

ax,

shaded,

factor,

render_params.zorder,

x_ext + y_ext,

nan_result=nan_shaded,

)

cax = _build_ds_colorbar(reduction_bounds, norm, render_params.cmap_params.cmap)

elif method == "matplotlib":

# update axis limits if plot was empty before (necessary if datashader comes after)

update_parameters = not _mpl_ax_contains_elements(ax)

_cax = ax.scatter(

adata[:, 0].X.flatten(),

adata[:, 1].X.flatten(),

s=render_params.size,

c=color_vector,

rasterized=sc_settings._vector_friendly,

cmap=render_params.cmap_params.cmap,

norm=norm,

alpha=render_params.alpha,

transform=trans_data,

zorder=render_params.zorder,

plotnonfinite=True, # nan points should be rendered as well

)

cax = ax.add_collection(_cax)

if update_parameters:

# necessary if points are plotted with mpl first and then with datashader

extent = get_extent(sdata_filt.points[element], coordinate_system=coordinate_system)

ax.set_xbound(extent["x"])

ax.set_ybound(extent["y"])