subplot

Manage modern mode figure subplot configuration and selection

The subplot module is used to split the current figure into a rectangular layout of subplots that each may contain a single self-contained figure. A subplot setup is started with the begin directive that defines the layout of the subplots, while positioning to a particular subplot for plotting is done via the set directive. The subplot process is completed via the end directive.

Synopsis (begin mode)

gmt subplot begin nrowsxncols -F[f|s]width(s)/height(s)[+af|s][+cdx[/dy]][+fwfracs/hfracs][+gfill][+ppen][+wpen] [ -Aautotag ] [ -C[side]clearance ] [ -D ] [ -B[p|s]parameters ] [ -Jparameters ] [ -Mmargins ] [ -Rregion ] [ -Sc|r[layout][mods] ] [ -Ttitle ] [ -V[level] ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ --PAR=value ]

Note: No space is allowed between the option flag and the associated arguments.

Description

The begin directive of subplot defines the layout of the entire multi-panel illustration. Several options are available to specify the systematic layout, labeling, dimensions, and more for the subplots.

Required Arguments (begin mode)

nrowsxncols

Specifies the number of rows and columns of subplots. Each row will have the same number of subplots. Note: You are not required to place a plot in each subplot.

-F[f|s]width(s)/height(s)[+af|s][+cdx[/dy]][+fwfracs/hfracs][+gfill][+ppen][+wpen]

Specify the dimensions of the figure. There are two different ways to do this. Select one of the directives:

  • f - Specify overall final figure dimensions. The subplot dimensions are then calculated from the figure dimensions after accounting for the space that optional tick marks, annotations, labels, and margins occupy between subplots. As for other figures, annotations, ticks, and labels along the outside perimeter are not counted as part of the figure dimensions. To specify different subplot dimensions for each row (or column), append +f followed by a comma-separated list of width fractions, a slash, and then the list of height fractions. For example -Ff10c/10c+f3,1/1,2 will make the first column three times as wide as the second, while the second row will be twice as tall as the first row. A single number means constant widths (or heights) [Default].

  • s - Specify the dimensions of a single subplot directly. Then, the figure dimensions are computed from the subplot dimensions after adding the space that optional tick marks, annotations, labels, and margins occupy between subplots. As for other figures, annotations, ticks, and labels along the outside perimeter are not counted as part of the figure dimensions. To specify different subplot dimensions for each row (or column), append a comma-separated list of widths, a slash, and then the comma-separated list of heights. A single number means constant widths (or heights) [Default]. For example -Fs5c,8c/8c will make the first column 5 cm wide and the second column 8 cm wide, with all having a constant height of 8 cm. The number of values must either be one (constant across the rows or columns) or exactly match the number of rows (or columns).

For geographic maps, the height of each subplot depends on your map region and projection. There are two options: (1) Specify both -R and -J and we use these to compute the height of each subplot. All subplots must share the same region and projection and you specify a zero height, or (2) you can select height based on trial and error to suit your plot layout.

Several modifiers can be used to adjust the layout. These are most useful if you supply -B+n to subplot begin, meaning no ticks or annotations will take place in the subplots:

  • +a - Normally (append f [Default]) we auto-scale the fonts and pens based on the geometric mean dimension of the entire figure. Alternatively, append s to determine the scaling from the geometric mean subplot dimension instead.

  • +c - Expand the panels by the appended plot unit increments dx[/dy].

  • +f - To specify different subplot dimensions for each row (or column), append a comma-separated list of width fractions, a slash, and then the list of height fractions. For example -Ff10c/10c+f3,1/1,2 will make the first column three times as wide as the second, while the second row will be twice as tall as the first row. A single number means constant widths (or heights) [Default].

  • +g - Paint the figure rectangle behind the subplot panels with the appended fill.

  • +p - Draw the outline of the figure rectangle behind the subplot panels with the appended pen.

  • +w - Draw dividing lines between panels using the appended pen.

Optional Arguments (begin mode)

-A[autotag][+cdx[/dy]][+gfill][+j|Jrefpoint][+odx[/dy]][+ppen][+r|R][+s[[dx/dy][/shade]]][+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 (Note: In UNIX shells you may need to escape these parentheses.). Placement, box outline and fill etc are controlled by modifiers:

  • +c - Append dx[/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].

  • +g - Append fill to paint the tag’s text box [default is no painting].

  • +j - Append the refpoint justification of the tag (suitable for interior tags) using the nine standard justification codes [B|M|T][L|C|R] shown in text [TL].

  • +J - As +j, but instead selects the mirror opposite location (suitable for exterior tags).

  • +o - Append dx[/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].

  • +p - Supply a pen to draw the outline of the tag’s text box [default is no outline].

  • +r - Typeset your tag numbers using lowercase Roman numerals.

  • +R - Same for uppercase Roman numerals [default is Arabic numerals].

  • +s - Place an offset background shaded rectangle. Here, dx/dy indicates the shift relative to the tag box [default is 2p/-2p] and shade sets the fill style to use for shading [default is gray50].

  • +v - Increase tag numbers vertically down columns [default is horizontally across rows].

Note: Currently you cannot use LaTeX expressions in the panel tag. The workaround is to place such tags separately via text.

-B[p|s]parameters

Set map boundary frame and axes attributes. (See full description) (See cookbook information).

-C[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. The option is repeatable to set aside space on more than one side. Such space will be left untouched by the main map plotting but can be accessed by modules that plot scales, bars, text, etc. Settings specified under begin directive apply to all subplots, while settings under set only apply to the selected (active) subplot. Note: Common options -X and -Y are not available during subplots; use -C instead. Also note that -C does not affect the positioning of panel tags via -A.

-D

Use the prevailing defaults settings (via gmt.conf or --PAR=value) and the selections made via -B, -C, -M and -S to determine the panel sizes (if using -Ff) and panel spacings only, but do not draw and annotate any frames. This option is useful if you wish to lay down a partial subplot with annotations and frames, but then want to plot data inside it separately later without redrawing the frames. With different -B, -C, -M and -S choices the two subplots may not align, but with -D they will. Note: It is assumed that -F stays the same [Draw and annotate frames as indicated].

-Jparameters

Specify the projection. (See full description) (See cookbook summary) (See projections table).

-Mmargins

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 a single value (for same margin on all sides), a pair of values separated by slashes (for setting separate horizontal and vertical margins), or the full set of four slash-separated margins (for setting separate left, right, bottom, and top margins). Append units as desired [Default is set by PROJ_LENGTH_UNIT]. 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].

-Rxmin/xmax/ymin/ymax[+r][+uunit]

Specify the region of interest. This is useful when all subplots share a common plot domain. In this module, the chosen region will also become the default for any data region needed by computational modules. (See full description) (See cookbook information).

-Sc|r[layout][mods]

Set subplot layout for shared axes. May be set separately for rows (-Sr) and columns (-Sc). Considerations for -Sc: Use when all subplots in a column share a common x-range. The first (i.e., top) and the last (i.e., bottom) rows will have x annotations; append t or 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. Optionally, use +s to set a separate (secondary) label. Append +t to make space for subplot titles for each row; use +tc for top row titles only [no subplot titles]. Labels and titles that depends on which row or column are specified as usual via a subplot’s own -B setting. Considerations for -Sr: Use when all subplots in a row share a common y-range. The first (i.e., left) and the last (i.e., right) columns will have y-annotations; append l or 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. Optionally, use +s to set a separate (secondary) label. Append +p to make all annotations axis-parallel [horizontal]; if not used you may have to set -C to secure extra space for long horizontal annotations. Append +w to the -F argument to draw horizontal and vertical lines between interior panels using selected pen [no lines].

-Theading

While individual subplots can have titles (see -S or -B), the entire figure may also have a overarching heading [no heading]. Font is determined by setting FONT_HEADING.

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

-X[a|c|f|r][xshift]

Shift plot origin. (See full description) (See cookbook information).

-Y[a|c|f|r][yshift]

Shift plot origin. (See full description) (See cookbook information).

-^ or just -

Print a short message about the syntax of the command, then exit (Note: on Windows just use -).

-+ or just +

Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exit.

-? or no arguments

Print a complete usage (help) message, including the explanation of all options, then exit.

--PAR=value

Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

Synopsis (set mode)

gmt subplot set [ row,col|index ] [ -Afixedtag] [ -Csideclearance ] [ -V[level] ]

Before you start plotting you must first select the active subplot. Note: If any -J option is passed without the scale or width when you first are plotting inside the subplot, then the scale of the map is automatically determined by the subplot size and your region. For Cartesian plots: If you want the scale to apply equally to both dimensions then you must specify -Jx [The default projection of -JX will fill the subplot by using unequal scales].

Optional Arguments (set mode)

row,col

Sets the current subplot until further notice. Note: First row or col is 0, not 1. If not given we go to the next subplot by order specified via -A. As an alternative, you may bypass the set mode and instead supply the common option -c[row,col] to the first plot command you issue in that subplot. GMT maintains information about the current figure and subplot. Also, you may give the one-dimensional index instead which starts at 0 and follows the row or column order set via -A.

-Afixedtag

Overrides the automatic labeling with the given string. No modifiers are allowed. Placement, justification, etc. are all inherited from how -A was specified by the initial subplot begin command. Note: Overriding means you initiate the tag machinery with -A when subplot begin was called, otherwise the option is ignored. To not set any tag for this panel, use -A-.

-C[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. The option is repeatable to set aside space on more than one side. Such space will be left untouched by the main map plotting but can be accessed by modules that plot scales, bars, text, etc. This setting overrides the common clearances set by -C during subplot begin.

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

Any number of plotting command can now take place and all output will be directed to the selected subplot. There are a few other rules that need to be followed: (1) The subplot machinery expects the first plotting command in a new subplot window to take care of plotting the base frame. The particulars of this frame may have been specified by the -S option in subplot begin. In either case, should you need to set or override frame and axis parameters then you must specify these -B options with this first plot command. (2) The subplot machinery automatically uses the -X and -Y options under the hood so these options are not available while a subplot is active.

Synopsis (end mode)

gmt subplot end [ -V[level] ]

This command finalizes the current subplot, including any placement of tags, and updates the gmt.history to reflect the dimensions and linear projection required to draw the entire figure outline. This allows subsequent commands, such as colorbar, to use -DJ to place bars with reference to the complete figure dimensions. We also reset the current plot location to where it was prior to the subplot.

Optional Arguments (end mode)

-V[level]

Select verbosity level [w]. (See full description) (See cookbook information).

Examples

To make a minimalistic 2x2 basemap layout called panels.pdf, try:

gmt begin panels pdf
  gmt subplot begin 2x2 -Fs8c -M5p -A -Scb -Srl -R0/80/0/10
    gmt subplot set
    gmt basemap
    gmt subplot set
    gmt basemap
    gmt subplot set
    gmt basemap
    gmt subplot set
    gmt basemap
  gmt subplot end
gmt end show

Restrictions

  1. Currently, nesting of subplots is not implemented.

  2. If auto-legend option -l is used then you must complete plotting in one panel before moving to another.

  3. Specifying separate primary and secondary annotations via -Bp and -Bs have not yet been implemented.

See Also

begin, clear, docs, end, figure, inset, gmt