add_colorbar

Maps.add_colorbar(pos=0.4, inherit_position=None, orientation='horizontal', hist_bins=256, hist_size=0.8, out_of_range_vals='clip', tick_precision=2, dynamic_shade_indicator=False, extend=None, extend_frac=0.025, log=False, label=None, outline=False, hist_kwargs=None, hist_label=None, margin=None, divider_linestyle=None, layer=None, **kwargs)

Add a colorbar to the map.

The colorbar always represents the data of the associated Maps-object that was assigned in the last call to Maps.plot_map().

By default, the colorbar will only be visible on the layer of the associated Maps-object.

After the colorbar has been created, it can be accessed via:

>>> cb = m.colorbar

For more details, see ColorBar.

Parameters:

  • pos (float or 4-tuple, optional) –

    • float: fraction of the axis size that is used to create the colorbar. The axes of the Maps-object will be shrunk accordingly to make space for the colorbar.

    • 4-tuple (x0, y0, width, height): Absolute position of the colorbar in relative figure-units (0-1). In this case, existing axes are NOT automatically re-positioned!

    Note: By default, multiple colorbars on different layers share their position! To force placement of a colorbar, use “inherit_position=False”.

    The default is 0.4.

  • inherit_position (bool or None optional) –

    Indicator if the colorbar should share its position with other colorbars that represent datasets on the same plot-axis.

    • If True, and there is already another colorbar for the given plot-axis, the value of “pos” will be ignored and the new colorbar will share its position with the parent-colorbar. (e.g. all colorbars for a given axis will overlap and moving a colorbar in one layer will move all other relevant colorbars accordingly).

    • If None: If the colorbar is added on a different layer than the parent colorbar, use “inherit_position=True”, else use “inherit_position=False”.

    The default is None

  • extend (str or None, optional) –

    Set how extension-arrows should be added.

    • None: extension-arrow behavior is determined by the provided dataset in conjunction with the limits (e.g. vmin and vmax).

    • ”neither”: extension arrows are never added

    • ”min” or “max”: only min / max extension arrows are added

    • ”both”: both min and max extension arrows are added

    Note: If the colorbar inherits its position from a colorbar on a different layer, the extend-behavior is inherited as well!

    The default is None.

  • extend_frac (float, optional) – The fraction of the colorbar-size to use for extension-arrows. (Extension-arrows are added if out-of-range values are found!) The default is 0.025.

  • orientation (str, optional) – The orientation of the colorbar (“horizontal” or “vertical”). The default is “horizontal”.

  • dynamic_shade_indicator (bool, optional) –

    ONLY relevant if data-shading is used! (“shade_raster” or “shade_points”)

    • False: The colorbar represents the actual (full) dataset

    • True: The colorbar is dynamically updated and represents the density of the shaded pixel values within the current field of view.

    The default is False.

  • outline (bool or dict) –

    Indicator if an outline should be added to the histogram. (e.g. a line encompassing the histogram) If a dict is provided, it is passed to plt.step() to style the line. (e.g. with ordinary matplotlib parameters such as color, lw, ls etc.) If True, the following properties are used:

    • {“color”: “k”, “lw”: 1}

    The default is False.

  • tick_precision (int or None) – The precision of the tick-labels in the colorbar. (e.g. a precision of 2 means that 0.12345 will be shown as 0.12) The default is 2.

  • log (bool, optional) – Indicator if the y-axis of the plot should be logarithmic or not. The default is False.

  • out_of_range_vals (str or None) –

    Set how to treat histogram values outside the visible range of values.

    • if “mask”: out-of range values will be masked. (e.g. values outside the colorbar limits are not represented in the histogram and NO extend-arrows are added)

    • if “clip”: out-of-range values will be clipped. (e.g. values outside the colorbar limits will be represented in the min/max bins of the histogram)

    The default is “clip”

  • label (str, optional) – The label used for the colorbar. Use ColorBar.set_labels() to set the labels (and styling) for the colorbar and the histogram. The default is None.

  • hist_size (float or None) –

    The fraction of the colorbar occupied by the histogram.

    • None: no histogram will be drawn

    • 0:

    • 0.9: 90% histogram, 10% colorbar

    • 1: only histogram

  • hist_bins (int, list, tuple, array or "bins", optional) –

    • If int: The number of histogram-bins to use for the colorbar.

    • If list, tuple or numpy-array: the bins to use

    • If “bins”: use the bins obtained from the classification (ONLY possible if a classification scheme is used!)

    The default is 256.

  • hist_label (str, optional) – The label used for the y-axis of the colorbar. The default is None

  • hist_kwargs (dict) – A dictionary with keyword-arguments passed to the creation of the histogram (e.g. passed to plt.hist() )

  • layer (str) – The layer at which the colorbar will be drawn. NOTE: In most cases you should NOT need to adjust the layer! The layer is automatically assigned to the layer at which the data was plotted and Colorbars are only visible on the assigned layer!

  • divider_linestyle (dict or None) – A dictionary that specifies the style of the line between the histogram and the colorbar. If None a black dashed line is drawn (e.g. {“color”: “k”, “linestyle”:”–“}). The default is None.

  • kwargs – All additional kwargs are passed to the creation of the colorbar (e.g. plt.colorbar())

See also

ColorBar.set_bin_labels

Use custom names for classified colorbar bins.

Examples

>>> x = y = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> data = [1, 2, 6, 6, 6, 8, 7, 3, 9, 10]
>>> m = Maps()
>>> m.set_data(data, x, y)
>>> m.plot_map()
>>> m.add_colorbar(label="some data")

>>> x = y = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> data = [1, 2, 6, 6, 6, 8, 7, 3, 9, 10]
>>> m = Maps()
>>> m.set_data(data, x, y)
>>> m.set_classify.Quantiles(k=6)
>>> m.plot_map()
>>> m.add_colorbar(hist_bins="bins", label="some data")