pygmt.Figure.legend

Figure.legend(spec=None, position=None, width=None, height=None, line_spacing=None, box=False, scale=None, projection=None, region=None, frame=False, verbose=False, panel=False, perspective=False, transparency=None, **kwargs)

Plot a legend.

Makes legends that can be overlaid on plots. It reads specific legend-related information from an input file, a io.StringIO object, or automatically creates legend entries from plotted symbols that have labels. Unless otherwise noted, annotations will be made using the primary annotation font and size in effect (i.e., FONT_ANNOT_PRIMARY).

Full GMT docs at https://docs.generic-mapping-tools.org/6.7/legend.html.

Aliases:

B = frame
D = position, +w: width/height, +l: line_spacing
F = box
J = projection

R = region
S = scale
V = verbose

c = panel
p = perspective
t = transparency

Parameters:

spec (str | PathLike | StringIO | None, default: None) –
The legend specification. It can be:
- None which means using the automatically generated legend specification file
- Path to the legend specification file
- A io.StringIO object containing the legend specification
See https://docs.generic-mapping-tools.org/6.7/legend.html for the definition of the legend specification.
position (Position | Sequence[float | str] | Literal['TL', 'TC', 'TR', 'ML', 'MC', 'MR', 'BL', 'BC', 'BR'] | None, default: None) –
Position of the legend 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 Top Right corner inside the plot with a 0.2-cm offset.
width (float | str | None, default: None)
height (float | str | None, default: None) –
Width and height of the legend box. If not given, the width and height are computed automatically based on the contents of the legend specification. If unit is % (percentage) then width is computed as that fraction of the plot width. If height is given as percentage then height is recomputed as that fraction of the legend width (not plot height).

Note: Currently, the automatic width calculation only works when legend codes D, H, L, S, or V are used and that the number of symbol columns (N) is 1. If height is zero or not given, GMT estimates it based on the expected vertical extent of the items to be placed. A legend containing paragraph text may require an explicit height.
line_spacing (float | None, default: None) – The line-spacing factor between legend entries in units of the current font size [Default is 1.1].
box (Box | bool, default: False) – Draw a background box behind the legend. 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.
scale (float | None, default: None) – Scale all symbol sizes by a common scale [Default is 1.0, i.e., no scaling].
projection (str | None, default: None) – projcode[projparams/]width|scale. Select map projection.
region (Sequence[float | str] | str | None, default: None) – [xmin, xmax, ymin, ymax] or xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.
frame (Frame | Axis | Literal['none'] | str | Sequence[str] | bool, default: False) – Set frame and axes attributes for the plot. It can be a bool, "none", a pygmt.params.Frame or pygmt.params.Axis object. Raw GMT strings or sequences of strings are also supported for backward compatibility. If frame=True, the frame will be drawn with the default attributes. If frame="none", no frame will be drawn. Use a pygmt.params.Frame or pygmt.params.Axis object for more control over the attributes of the frame and axes. A tutorial is available at frame and axes attributes. Full documentation is at https://docs.generic-mapping-tools.org/6.7/gmt.html#b-full.
verbose (Literal['quiet', 'error', 'warning', 'timing', 'info', 'compat', 'debug'] | bool, default: False) – 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 (Perspective | float | Sequence[float] | bool, default: False) – Select perspective view and set the viewpoint. Pass a pygmt.params.Perspective object to control the viewpoint. Alternatively, set perspective=True to reuse the perspective setting from the previous plotting method. It also accepts following shortcuts: a single value azimuth, a sequence of two values (azimuth, elevation), or a sequence of three values (azimuth, elevation, level). Refer to pygmt.params.Perspective for meaning of the parameters.
transparency (float | None, default: None) – 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).