pygmt.Figure.colorbar

Figure.colorbar(position=None, length=None, width=None, orientation=None, reverse=False, nan_rectangle=False, nan_rectangle_position=None, sidebar_triangles=False, sidebar_triangles_height=None, move_text=None, label_as_column=False, box=False, truncate=None, shading=False, log=False, scale=None, projection=None, region=None, frame=False, verbose=False, panel=False, perspective=False, transparency=None, **kwargs)

Plot gray scale or color scale bar.

Both horizontal and vertical colorbars are supported. For CPTs with gradational colors (i.e., the lower and upper boundary of an interval have different colors) we will interpolate to give a continuous scale. Variations in intensity due to shading/illumination may be displayed by setting the shading parameter. Colors may be spaced according to a linear scale, all be equal size, or by providing a file with individual tile widths.

Note

For GMT >=6.5.0, the fontsizes of the colorbar x-label, x-annotations, and y-label are scaled based on the width of the colorbar following \(\sqrt{colorbar\_width / 15}\). To set a desired fontsize via the GMT default parameters FONT_ANNOT_PRIMARY, FONT_ANNOT_SECONDARY, and FONT_LABEL (or jointly FONT) users have to divide the desired fontsize by the value calculated with the formula given above before passing it to the default parameters. To only affect fontsizes related to the colorbar, the defaults can be changed locally only using with pygmt.config(...):.

Full GMT docs at https://docs.generic-mapping-tools.org/6.6/colorbar.html.

Aliases:

C = cmap
L = equalsize
Z = zfile
B = frame
D = position, +w: length/width, +h/+v: orientation, +r: reverse, +n: nan_rectangle/nan_rectangle_position, +e: sidebar_triangles/scalebar_triangles_height, +m: move_text/label_as_column
F = box

G = truncate
I = shading
J = projection
Q = log
R = region

V = verbose
W = scale
c = panel
p = perspective
t = transparency

Parameters:

cmap (str) – File name of a CPT file or a series of comma-separated colors (e.g., color1,color2,color3) to build a linear continuous CPT from those colors automatically.
position (Position | Sequence[float | str] | Literal['TL', 'TC', 'TR', 'ML', 'MC', 'MR', 'BL', 'BC', 'BR'] | None, default: None) –
Position of the GMT logo on the plot. It can be specified in multiple ways:
- A pygmt.params.Position object to fully control the reference point, anchor point, and offset.
- A sequence of two values representing the x- and y-coordinates in plot coordinates, e.g., (1, 2) or ("1c", "2c").
- A 2-character justification code for a position inside the plot, e.g., "TL" for Top Left corner inside the plot.
If not specified, defaults to the Bottom Center outside of the plot.
length (float | str | None, default: None)
width (float | str | None, default: None) – Length and width of the color bar. If length is given with a unit % then it is in percentage of the corrresponding plot side dimension (i.e., plot width for a horizontal colorbar, or plot height for a vertical colorbar). If width is given with unit % then it is in percentage of the bar length. [Length default to 80% of the corresponding plot side dimension, and width default to 4% of the bar length].
orientation (Literal['horizontal', 'vertical'] | None, default: None) – Set the colorbar orientation to either "horizontal" or "vertical". [Default is vertical, unless position is set to bottom-center or top-center with cstype="outside" or cstype="inside", then horizontal is the default].
reverse (bool, default: False) – Reverse the positive direction of the bar.
nan_rectangle (bool | str, default: False) – Draw a rectangle filled with the NaN color (via the N entry in the CPT or COLOR_NAN if no such entry) at the start of the colorbar. If a string is given, use that string as the label for the NaN color.
nan_rectangle_position (Literal['start', 'end'] | None, default: None) – Set the position of the NaN rectangle. Choose from "start" or "end". [Default is "start"].
sidebar_triangles (bool | Literal['foreground', 'background'], default: False) – Draw sidebar triangles for back- and/or foreground colors. If set to True, both triangles are drawn. Alternatively, set it to "foreground" or "background" to draw only one triangle. The back- and/or foreground colors are taken from the B and F entries in the CPT. If no such entries exist, then the system default colors for B and F are used instead ( COLOR_BACKGROUND and COLOR_FOREGROUND).
sidebar_triangles_height (float | None, default: None) – Height of the sidebar triangles [Default is half the bar width].
move_text (Sequence[str] | None, default: None) – Move text (annotations, label, and unit) to opposite side. Accept a sequence of strings containing one or more of "annotations", "label", and "unit". The default placement of these texts depends on the colorbar orientation and position.
label_as_column (bool, default: False) – Print a vertical label as a column of characters (does not work with special characters).
box (Box | bool, default: False) – Draw a background box behind the colorbar. If set to True, a simple rectangular box is drawn using MAP_FRAME_PEN. To customize the box appearance, pass a pygmt.params.Box object to control style, fill, pen, and other box properties.
truncate (Sequence[float] | None, default: None) – (zlow, zhigh). Truncate the incoming CPT so that the lowest and highest z-levels are to zlow and zhigh. If one of these equal NaN then we leave that end of the CPT alone. The truncation takes place before the plotting.
scale (float | None, default: None) – Multiply all z-values in the CPT by the provided scale. By default, the CPT is used as is.
shading (float | Sequence[float] | bool, default: False) –
Add illumination effects [Default is no illumination].
- If True, a default intensity range of -1 to +1 is used.
- Passing a single numerical value max_intens sets the range of intensities from -max_intens to +max_intens.
- Passing a sequence of two numerical values (low, high) sets the intensity range from low to high to specify an asymmetric range.
equalsize (float or str) – [i][gap]. Equal-sized color rectangles. By default, the rectangles are scaled according to the z-range in the CPT (see also zfile). If gap is appended and the CPT is discrete each annotation is centered on each rectangle, using the lower boundary z-value for the annotation. If i is prepended the interval range is annotated instead. If shading is used each rectangle will have its constant color modified by the specified intensity.
log (bool, default: False) – Select logarithmic scale and power of ten annotations. All z-values in the CPT will be converted to \(p = \log_{10}(z)\) and only integer p values will be annotated using the \(10^{p}\) format [Default is linear scale].
zfile (str) – File with colorbar-width per color entry. By default, the width of the entry is scaled to the color range, i.e., z = 0-100 gives twice the width as z = 100-150 (see also equalsize). Note: The widths may be in plot distance units or given as relative fractions and will be automatically scaled so that the sum of the widths equals the requested colorbar length.
projection (str | None, default: None) – projcode[projparams/]width|scale. Select map projection.
region (str or list) – xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.
frame (str or list) – Set colorbar boundary frame, labels, and axes attributes.
verbose (bool or str) – Select verbosity level [Full usage].
panel (int | Sequence[int] | bool, default: False) –
Select a specific subplot panel. Only allowed when used in Figure.subplot mode.
- True to advance to the next panel in the selected order.
- index to specify the index of the desired panel.
- (row, col) to specify the row and column of the desired panel.
The panel order is determined by the Figure.subplot method. row, col and index all start at 0.
perspective (float | Sequence[float] | str | bool, default: False) –
Select perspective view and set the azimuth and elevation of the viewpoint.

Accepts a single value or a sequence of two or three values: azimuth, (azimuth, elevation), or (azimuth, elevation, zlevel).
- azimuth: Azimuth angle of the viewpoint in degrees [Default is 180, i.e., looking from south to north].
- elevation: Elevation angle of the viewpoint above the horizon [Default is 90, i.e., looking straight down at nadir].
- zlevel: Z-level at which 2-D elements (e.g., the map frame) are drawn. Only applied when used together with zsize or zscale. [Default is at the bottom of the z-axis].
Alternatively, set perspective=True to reuse the perspective setting from the previous plotting method, or pass a string following the full GMT syntax for finer control (e.g., adding +w or +v modifiers to select an axis location other than the plot origin). See https://docs.generic-mapping-tools.org/6.6/gmt.html#perspective-full for details.
transparency (float) – Set transparency level, in [0-100] percent range [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

Example

>>> import pygmt
>>> # Create a new figure instance with pygmt.Figure()
>>> fig = pygmt.Figure()
>>> # Create a basemap
>>> fig.basemap(region=[0, 10, 0, 3], projection="X10c/3c", frame=True)
>>> # Call the colorbar method for the plot
>>> fig.colorbar(
...     # Set cmap to the "roma" CPT
...     cmap="roma",
...     # Label the x-axis "Velocity" and the y-axis "m/s"
...     frame=["x+lVelocity", "y+lm/s"],
... )
>>> # Show the plot
>>> fig.show()