alphapepttools.pl.MappedColormaps

alphapepttools.pl.MappedColormaps#

class alphapepttools.pl.MappedColormaps(cmap, percentile=None)#

Percentile-based colormap normalization for outlier-robust visualization

Mapping a continuous colorscale to data can suffer from compression due to outliers. For example, if 90 % of values lie between 0 and 1 but 10 % of values are between 1 and 100, these extreme values will cause all other values to be compressed into a small range of colors. By applying normalization to a certain percentile range of the data, the colormap can be adjusted accordingly. Values outside the percentile will receive the same color as the minimum or maximum, respectively.

Parameters:

  • cmap (str) – Name of the colormap to be used

  • percentile (tuple[float, float], optional) – Percentile range to be used for normalization. If None, the full range of data is used. For example, (5, 95) will map colors between the 5th and 95th percentile.

vmin#

Lower normalization bound. None until fit() or fit_transform() has been called. Public and writable by design, mirroring matplotlib.colors.Normalize, so callers can pin hard bounds after fitting.

Type:

float or None

vmax#

Upper normalization bound. Same semantics as vmin.

Type:

float or None

Attributes table#

scalar_mappable

Return a ScalarMappable for use in colorbars

Methods table#

fit([data, vmin, vmax])

Determine and store the normalization bounds without producing colors

fit_transform(data, *[, as_hex])

Normalize data and transform it to colors

transform(data, *[, as_hex])

Map data to colors using the previously fitted normalization bounds

Attributes#

MappedColormaps.scalar_mappable#

Return a ScalarMappable for use in colorbars

This property provides a ScalarMappable instance that can be used to create colorbars consistent with the normalization applied by fit() or fit_transform(). It uses the same vmin, vmax, and colormap, ensuring that the colorbar accurately reflects the mapping of data values to colors.

Returns:

mpl.cm.ScalarMappable ScalarMappable instance with the same colormap and normalization as the fitted bounds.

Raises:

ValueError – If accessed before fit() or fit_transform().

Methods#

MappedColormaps.fit(data=None, *, vmin=None, vmax=None)#

Determine and store the normalization bounds without producing colors

Bounds are derived from data (the full range, or the configured percentile range), unless explicit vmin/vmax are given, which override on a per-bound basis.

Parameters:

  • data (np.ndarray, optional) – Data from which to derive the bounds. Required unless both vmin and vmax are provided. NaNs are ignored.

  • vmin (float, optional) – Explicit lower bound, overriding the data-derived minimum.

  • vmax (float, optional) – Explicit upper bound, overriding the data-derived maximum.

Return type:

MappedColormaps

Returns:

MappedColormaps The fitted instance (self).

Raises:

ValueError – If a bound cannot be determined from data or explicit values.

Examples

Pin the colormap to fixed bounds without any data:

mapper = MappedColormaps(cmap="cmc.vik")
mapper.fit(vmin=0, vmax=1)
MappedColormaps.fit_transform(data, *, as_hex=False)#

Normalize data and transform it to colors

Convenience wrapper around fit() followed by transform(): the normalization bounds are derived from the data (the full range, or the configured percentile range) and the data is then mapped to colors. Values outside the normalization range are clamped to the colormap’s end colors. Use fit() and transform() separately to reuse one color scale across several arrays with differing ranges.

Parameters:

  • data (np.ndarray) – Data to be transformed into colors. Based on this data, the colormap will be normalized. Can be any shape; colors are returned in the same shape.

  • as_hex (bool, default=False) – If True, return hex color strings. If False, return RGBA tuples.

Return type:

ndarray

Returns:

np.ndarray Array of colors with the same shape as input data. If as_hex=False, the last dimension will be 4 (RGBA). If as_hex=True, returns array of hex strings.

Examples

Transform 1D data to colors:

import numpy as np
from alphapepttools.pl.colors import MappedColormaps

data = np.array([1, 2, 3, 100])  # 100 is outlier
mapper = MappedColormaps(cmap="sequential", percentile=(5, 95))
colors = mapper.fit_transform(data)
# Returns (4, 4) array of RGBA colors

Transform 2D heatmap data:

data = np.random.randn(10, 10)
mapper = MappedColormaps(cmap="diverging")
colors = mapper.fit_transform(data)
# Returns (10, 10, 4) array of RGBA colors

Get hex colors for plotting:

data = np.array([1, 2, 3, 4, 5])
mapper = MappedColormaps(cmap="sequential")
hex_colors = mapper.fit_transform(data, as_hex=True)
# Returns array of hex strings like ['#1a2b3c', ...]
MappedColormaps.transform(data, *, as_hex=False)#

Map data to colors using the previously fitted normalization bounds

Uses the vmin/vmax set by fit() or fit_transform() without re-deriving them from data. Values outside [vmin, vmax] are clamped to the colormap’s end colors.

Parameters:

  • data (np.ndarray) – Data to be transformed into colors. Can be any shape; colors are returned in the same shape.

  • as_hex (bool, default=False) – If True, return hex color strings. If False, return RGBA tuples.

Return type:

ndarray[tuple[Any, ...], dtype[Any]]

Returns:

np.ndarray Array of colors with the same shape as input data. If as_hex=False, the last dimension will be 4 (RGBA). If as_hex=True, returns array of hex strings.

Raises:

ValueError – If called before fit() or fit_transform().