branca.colormap

Colormap

Utility module for dealing with colormaps.

class branca.colormap.ColorMap(vmin: float = 0.0, vmax: float = 1.0, caption: str = '', text_color: str = 'black', max_labels: int = 10)[source]

Bases: MacroElement

A generic class for creating colormaps.

Parameters:

  • vmin (float) – The left bound of the color scale.

  • vmax (float) – The right bound of the color scale.

  • caption (str) – A caption to draw with the colormap.

  • text_color (str, default "black") – The color for the text.

  • max_labels (int, default 10) – Maximum number of legend tick labels

render(**kwargs)[source]

Renders the HTML representation of the element.

rgb_bytes_tuple(x: float) → Tuple[int, int, int][source]

Provides the color corresponding to value x in the form of a tuple (R,G,B) with int values between 0 and 255.

rgb_hex_str(x: float) → str[source]

Provides the color corresponding to value x in the form of a string of hexadecimal values “#RRGGBB”.

rgba_bytes_tuple(x: float) → Tuple[int, int, int, int][source]

Provides the color corresponding to value x in the form of a tuple (R,G,B,A) with int values between 0 and 255.

rgba_floats_tuple(x: float) → Tuple[float, float, float, float][source]

This class has to be implemented for each class inheriting from Colormap. This has to be a function of the form float -> (float, float, float, float) describing for each input float x, the output color in RGBA format; Each output value being between 0 and 1.

rgba_hex_str(x: float) → str[source]

Provides the color corresponding to value x in the form of a string of hexadecimal values “#RRGGBBAA”.

class branca.colormap.LinearColormap(colors: Sequence[Tuple[int, int, int] | Tuple[float, float, float] | Tuple[int, int, int, int] | Tuple[float, float, float, float] | str], index: Sequence[float] | None = None, vmin: float = 0.0, vmax: float = 1.0, caption: str = '', text_color: str = 'black', max_labels: int = 10, tick_labels: Sequence[float] | None = None)[source]

Bases: ColorMap

Creates a ColorMap based on linear interpolation of a set of colors over a given index.

Parameters:

  • colors (list-like object with at least two colors.) – The set of colors to be used for interpolation. Colors can be provided in the form: * tuples of RGBA ints between 0 and 255 (e.g: (255, 255, 0) or (255, 255, 0, 255)) * tuples of RGBA floats between 0. and 1. (e.g: (1.,1.,0.) or (1., 1., 0., 1.)) * HTML-like string (e.g: “#ffff00) * a color name or shortcut (e.g: “y” or “yellow”)

  • index (list of floats, default None) – The values corresponding to each color. It has to be sorted, and have the same length as colors. If None, a regular grid between vmin and vmax is created.

  • vmin (float, default 0.) – The minimal value for the colormap. Values lower than vmin will be bound directly to colors[0].

  • vmax (float, default 1.) – The maximal value for the colormap. Values higher than vmax will be bound directly to colors[-1].

  • caption (str) – A caption to draw with the colormap.

  • text_color (str, default "black") – The color for the text.

  • max_labels (int, default 10) – Maximum number of legend tick labels

  • tick_labels (list of floats, default None) – If given, used as the positions of ticks.

rgba_floats_tuple(x: float) → Tuple[float, float, float, float][source]

Provides the color corresponding to value x in the form of a tuple (R,G,B,A) with float values between 0. and 1.

scale(vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10) → LinearColormap[source]

Transforms the colorscale so that the minimal and maximal values fit the given parameters.

to_step(n: int | None = None, index: Sequence[float] | None = None, data: Sequence[float] | None = None, method: str = 'linear', quantiles: Sequence[float] | None = None, round_method: str | None = None, max_labels: int = 10) → StepColormap[source]

Splits the LinearColormap into a StepColormap.

Parameters:

  • n (int, default None) – The number of expected colors in the output StepColormap. This will be ignored if index is provided.

  • index (list of floats, default None) – The values corresponding to each color bounds. It has to be sorted. If None, a regular grid between vmin and vmax is created.

  • data (list of floats, default None) – A sample of data to adapt the color map to.

  • method (str, default 'linear') – The method used to create data-based colormap. It can be ‘linear’ for linear scale, ‘log’ for logarithmic, or ‘quant’ for data’s quantile-based scale.

  • quantiles (list of floats, default None) – Alternatively, you can provide explicitly the quantiles you want to use in the scale.

  • round_method (str, default None) – The method used to round thresholds. * If ‘int’, all values will be rounded to the nearest integer. * If ‘log10’, all values will be rounded to the nearest order-of-magnitude integer. For example, 2100 is rounded to 2000, 2790 to 3000.

  • max_labels (int, default 10) – Maximum number of legend tick labels

Returns:

  • A StepColormap with n=len(index)-1 colors.

  • Examples

  • >> lc.to_step(n=12)

  • >> lc.to_step(index=[0, 2, 4, 6, 8, 10])

  • >> lc.to_step(data=some_list, n=12)

  • >> lc.to_step(data=some_list, n=12, method=’linear’)

  • >> lc.to_step(data=some_list, n=12, method=’log’)

  • >> lc.to_step(data=some_list, n=12, method=’quantiles’)

  • >> lc.to_step(data=some_list, quantiles=[0, 0.3, 0.7, 1])

  • >> lc.to_step(data=some_list, quantiles=[0, 0.3, 0.7, 1],

  • … round_method=’log10’)

class branca.colormap.StepColormap(colors: Sequence[Tuple[int, int, int] | Tuple[float, float, float] | Tuple[int, int, int, int] | Tuple[float, float, float, float] | str], index: Sequence[float] | None = None, vmin: float = 0.0, vmax: float = 1.0, caption: str = '', text_color: str = 'black', max_labels: int = 10, tick_labels: Sequence[float] | None = None)[source]

Bases: ColorMap

Creates a ColorMap based on linear interpolation of a set of colors over a given index.

Parameters:

  • colors (list-like object) – The set of colors to be used for interpolation. Colors can be provided in the form: * tuples of int between 0 and 255 (e.g: (255,255,0) or (255, 255, 0, 255)) * tuples of floats between 0. and 1. (e.g: (1.,1.,0.) or (1., 1., 0., 1.)) * HTML-like string (e.g: “#ffff00) * a color name or shortcut (e.g: “y” or “yellow”)

  • index (list of floats, default None) – The bounds of the colors. The lower value is inclusive, the upper value is exclusive. It has to be sorted, and have the same length as colors. If None, a regular grid between vmin and vmax is created.

  • vmin (float, default 0.) – The minimal value for the colormap. Values lower than vmin will be bound directly to colors[0].

  • vmax (float, default 1.) – The maximal value for the colormap. Values higher than vmax will be bound directly to colors[-1].

  • caption (str) – A caption to draw with the colormap.

  • text_color (str, default "black") – The color for the text.

  • max_labels (int, default 10) – Maximum number of legend tick labels

  • tick_labels (list of floats, default None) – If given, used as the positions of ticks.

rgba_floats_tuple(x: float) → Tuple[float, float, float, float][source]

Provides the color corresponding to value x in the form of a tuple (R,G,B,A) with float values between 0. and 1.

scale(vmin: float = 0.0, vmax: float = 1.0, max_labels: int = 10) → StepColormap[source]

Transforms the colorscale so that the minimal and maximal values fit the given parameters.

to_linear(index: Sequence[float] | None = None, max_labels: int = 10) → LinearColormap[source]

Transforms the StepColormap into a LinearColormap.

Parameters:

  • index (list of floats, default None) – The values corresponding to each color in the output colormap. It has to be sorted. If None, a regular grid between vmin and vmax is created.

  • max_labels (int, default 10) – Maximum number of legend tick labels