Figure.subplot(nrows=1, ncols=1, **kwargs)

Create multi-panel subplot figures.

This function is used to split the current figure into a rectangular layout of subplots that each may contain a single self-contained figure. Begin by defining the layout of the entire multi-panel illustration. Several parameters are available to specify the systematic layout, labeling, dimensions, and more for the subplots.

Full option list at


  • A = autolabel

  • B = frame

  • C = clearance

  • Ff = figsize

  • Fs = subsize

  • J = projecton

  • M = margins

  • R = region

  • SC = sharex

  • SR = sharey

  • T = title

  • V = verbose

  • X = xshift

  • Y = yshift

  • nrows (int) – Number of vertical rows of the subplot grid.

  • ncols (int) – Number of horizontal columns of the subplot grid.

  • figsize (tuple) – Specify the final figure dimensions as (width, height).

  • subsize (tuple) – Specify the dimensions of each subplot directly as (width, height). Note that only one of figsize or subsize can be provided at once.

  • autolabel (bool or str) – [autolabel][+cdx[/dy]][+gfill][+j|Jrefpoint][+odx[/dy]][+ppen][+r|R] [+v]. Specify automatic tagging of each subplot. Append either a number or letter [a]. This sets the tag of the first, top-left subplot and others follow sequentially. Surround the number or letter by parentheses on any side if these should be typeset as part of the tag. Use +j|Jrefpoint to specify where the tag should be placed in the subplot [TL]. Note: +j sets the justification of the tag to refpoint (suitable for interior tags) while +J instead selects the mirror opposite (suitable for exterior tags). Append +cdx[/dy] to set the clearance between the tag and a surrounding text box requested via +g or +p [3p/3p, i.e., 15% of the FONT_TAG size dimension]. Append +gfill to paint the tag’s text box with fill [no painting]. Append +odx[/dy] to offset the tag’s reference point in the direction implied by the justification [4p/4p, i.e., 20% of the FONT_TAG size]. Append +ppen to draw the outline of the tag’s text box using selected pen [no outline]. Append +r to typeset your tag numbers using lowercase Roman numerals; use +R for uppercase Roman numerals [Arabic numerals]. Append +v to increase tag numbers vertically down columns [horizontally across rows].

  • frame (bool or str or list) – Set map boundary frame and axes attributes.

  • clearance (str or list) – [side]clearance. Reserve a space of dimension clearance between the margin and the subplot on the specified side, using side values from w, e, s, or n; or x for both w and e; or y for both s and n. No side means all sides (i.e. clearance='1c' would set a clearance of 1 cm on all sides). The option is repeatable to set aside space on more than one side (e.g. clearance=['w1c', 's2c'] would set a clearance of 1 cm on west side and 2 cm on south side). Such space will be left untouched by the main map plotting but can be accessed by modules that plot scales, bars, text, etc.

  • projection (str) – Required if this is the first plot command. projcode[projparams/]width. Select map projection.

  • margins (str or list) –

    This is margin space that is added between neighboring subplots (i.e., the interior margins) in addition to the automatic space added for tick marks, annotations, and labels. The margins can be specified as either:

    • a single value (for same margin on all sides). E.g. ‘5c’.

    • a pair of values (for setting separate horizontal and vertical margins). E.g. [‘5c’, ‘3c’].

    • a set of four values (for setting separate left, right, bottom, and top margins). E.g. [‘1c’, ‘2c’, ‘3c’, ‘4c’].

    The actual gap created is always a sum of the margins for the two opposing sides (e.g., east plus west or south plus north margins) [Default is half the primary annotation font size, giving the full annotation font size as the default gap].

  • region (str or list) – Required if this is the first plot command. xmin/xmax/ymin/ymax[+r][+uunit]. Specify the region of interest.

  • sharex (bool or str) – Set subplot layout for shared x-axes. Use when all subplots in a column share a common x-range. If sharex=True, the first (i.e., top) and the last (i.e., bottom) rows will have x-annotations; use sharex='t' or sharex='b' to select only one of those two rows [both]. Append +l if annotated x-axes should have a label [none]; optionally append the label if it is the same for the entire subplot. Append +t to make space for subplot titles for each row; use +tc for top row titles only [no subplot titles].

  • sharey (bool or str) –

    Set subplot layout for shared y-axes. Use when all subplots in a row share a common y-range. If sharey=True, the first (i.e., left) and the last (i.e., right) columns will have y-annotations; use sharey='l' or sharey='r' to select only one of those two columns [both]. Append +l if annotated y-axes will have a label [none]; optionally, append the label if it is the same for the entire subplot. Append +p to make all annotations axis-parallel [horizontal]; if not used you may have to set clearance to secure extra space for long horizontal annotations.

    Notes for sharex/sharey:

    • Labels and titles that depends on which row or column are specified as usual via a subplot’s own frame setting.

    • Append +w to the figsize or subsize parameter to draw horizontal and vertical lines between interior panels using selected pen [no lines].

  • title (str) – While individual subplots can have titles (see sharex/sharey or frame), the entire figure may also have an overarching heading [no heading]. Font is determined by setting FONT_HEADING.

  • verbose (bool or str) –

    Select verbosity level [Default is w], which modulates the messages written to stderr. Choose among 7 levels of verbosity:

    • q - Quiet, not even fatal error messages are produced

    • e - Error messages only

    • w - Warnings [Default]

    • t - Timings (report runtimes for time-intensive algorithms);

    • i - Informational messages (same as verbose=True)

    • c - Compatibility warnings

    • d - Debugging messages

  • xshift (str) – [a|c|f|r][xshift]. Shift plot origin in x-direction.

  • yshift (str) – [a|c|f|r][yshift]. Shift plot origin in y-direction. Full documentation is at

Examples using pygmt.Figure.subplot