.\" Man page generated from reStructuredText.
.
.TH "SUBPLOT" "1gmt" "Sep 07, 2019" "6.0.0rc4" "GMT"
.SH NAME
subplot \- Manage modern mode figure subplot configuration and selection
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
The \fBsubplot\fP 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 \fBbegin\fP
directive that defines the layout of the subplots, while positioning to a particular subplot for
plotting is done via the \fBset\fP directive.  The subplot process is completed via the \fBend\fP directive.
.SH SYNOPSIS (BEGIN MODE)
.sp
\fBgmt subplot begin\fP \fInrows\fP\fBx\fP\fIncols\fP
\fB\-F\fP[\fBf\fP|\fBs\fP]\fIwidth\fP/\fIheight\fP[\fB+f\fP\fIwfracs\fP/\fIhfracs\fP][\fB+c\fP\fIdx/dy\fP][\fB+g\fP\fIfill\fP][\fB+p\fP\fIpen\fP][\fB+w\fP\fIpen\fP]
[ \fB\-A\fP\fIautolabel\fP ]
[ \fB\-C\fP[\fIside\fP]/\fIclearance\fP[\fBu\fP]]
[  \fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP ]
[  \fB\-J\fP\fIparameters\fP ]
[ \fB\-M\fP\fImargins\fP ]
[  \fB\-R\fP\fIregion\fP ]
[ \fB\-S\fP\fIlayout\fP ]
[ \fB\-T\fP\fItitle\fP ]
[  \fB\-V\fP[\fIlevel\fP] ]
[ \fB\-\-PAR\fP=\fIvalue\fP ]
.sp
\fBNote:\fP No space is allowed between the option flag and the associated arguments.
.SH DESCRIPTION
.sp
The \fBbegin\fP 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.
.SH REQUIRED ARGUMENTS
.INDENT 0.0
.TP
\fInrows\fP\fBx\fP\fIncols\fP
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.
.UNINDENT
.INDENT 0.0
.TP
\fB\-F\fP[\fBf\fP|\fBs\fP]\fIwidth(s)\fP/\fIheight(s)\fP[\fB+f\fP\fIwfracs\fP/\fIhfracs\fP][\fB+c\fP\fIdx/dy\fP][\fB+g\fP\fIfill\fP][\fB+p\fP\fIpen\fP]
Specify the dimensions of the figure.  There are two different ways to do this:
(\fBf\fP) Specify overall figure dimensions or (\fBs\fP) specify the dimensions of
a single subplot.
.TP
\fB\-Ff\fP
Specify the final \fBf\fPigure 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 \fB+f\fP followed by a comma\-separated list of width
fractions, a slash, and then the list of height fractions.  For example \fB\-Ff\fP10c/10c\fB+f\fP3,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].
.TP
\fB\-Fs\fP
Specify the dimensions of each \fBs\fPubplot 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 \fB\-Fs\fP5c,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 \fB\-R\fP and \fB\-J\fP 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 \fIheight\fP, or (2) you can select \fIheight\fP based on trial and error to suit your plot layout.
.sp
Optionally, you may draw or paint the figure rectangle behind the subplots, and even expand it via \fB+c\fP\&.  This
is most useful if you supply \fB\-B+n\fP to subplot begin, meaning no ticks or annotations will take place in the
subplots.
.UNINDENT
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
\fB\-A\fP\fIautolabel\fP
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.)
Use \fB+j\fP|\fBJ\fP\fIrefpoint\fP to specify where the tag should be placed in the subplot [TL].
Note: \fB+j\fP sets the justification of the tag to \fIrefpoint\fP (suitable for interior tags)
while \fB+J\fP instead selects the mirror opposite (suitable for exterior tags).
Append \fB+c\fP\fIdx\fP[/\fIdy\fP] to set the clearance between the tag and a surrounding text box
requested via \fB+g\fP or \fB+p\fP [3p/3p, i.e., 15% of the FONT_TAG size dimension].
Append \fB+g\fP\fIfill\fP to paint the tag\(aqs text box with \fIfill\fP [no painting].
Append \fB+o\fP\fIdx\fP[/\fIdy\fP] to offset the tag\(aqs reference point in the direction implied
by the justification [4p/4p, i.e., 20% of the FONT_TAG size].
Append \fB+p\fP\fIpen\fP to draw the outline of the tag\(aqs text box using selected \fIpen\fP [no outline].
Append \fB+r\fP to typeset your tag numbers using lowercase Roman numerals;
use \fB+R\fP for uppercase Roman numerals [Arabic numerals].
Append \fB+v\fP to increase tag numbers vertically down columns [horizontally across rows].
.UNINDENT
.INDENT 0.0
.TP
\fB\-B\fP[\fBp\fP|\fBs\fP]\fIparameters\fP (more ...)
Set map boundary frame and axes attributes.
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP[\fIside\fP]/\fIclearance\fP[\fBu\fP]
Reserve a space of dimension \fIclearance\fP between the margin and the subplot on the specified
side, using \fIside\fP values from \fBw\fP, \fBe\fP, \fBs\fP, or \fBn\fP, or \fBx\fP for both \fBw\fP and \fBe\fP
or \fBy\fP for both \fBs\fP and \fBn\fP\&.  No \fIside\fP 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 \fBbegin\fP directive apply
to all subplots, while settings under \fBset\fP only apply to the selected (active) subplot.  Note: Common options \fB\-X\fP
and \fB\-Y\fP are not available during subplots; use \fB\-C\fP instead.
.UNINDENT
.INDENT 0.0
.TP
\fB\-J\fP\fIparameters\fP (more ...)
Select map projection.  
.UNINDENT
.INDENT 0.0
.TP
\fB\-M\fP\fImargins\fP
This is margin space that is added \fIbetween\fP neighboring subplots (i.e., the interior margins) \fIin addition\fP
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).  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].
.UNINDENT
.INDENT 0.0
.TP
\fB\-R\fP\fIxmin\fP/\fIxmax\fP/\fIymin\fP/\fIymax\fP[\fB+r\fP][\fB+u\fP\fIunit\fP] (more ...)
Specify the region of interest. This is useful when all subplots share a common plot domain.
.UNINDENT
.INDENT 0.0
.TP
\fB\-S\fP\fIlayout\fP
Set subplot layout for shared axes. May be set separately for rows (\fB\-SR\fP) and columns (\fB\-SC\fP).
Considerations for \fB\-SC\fP: Use when all subplots in a \fBC\fPolumn share a common \fIx\fP\-range. The first (i.e., \fBt\fPop) and the last
(i.e., \fBb\fPottom) rows will have \fIx\fP annotations; append \fBt\fP or \fBb\fP to select only one of those two rows [both].
Append \fB+l\fP if annotated \fIx\fP\-axes should have a label [none]; optionally append the label if it is the same
for the entire subplot.
Append \fB+t\fP to make space for subplot titles for each row; use \fB+tc\fP 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\(aqs own \fB\-B\fP setting.
Considerations for \fB\-SR\fP: Use when all subplots in a \fBR\fPow share a common \fIy\fP\-range. The first (i.e., \fBl\fPeft) and the last
(i.e., \fBr\fPight) columns will have \fIy\fP\-annotations; append \fBl\fP or \fBr\fP to select only one of those two columns [both].
Append \fB+l\fP if annotated \fIy\fP\-axes will have a label [none]; optionally, append the label if it is the same
for the entire subplot.
Append \fB+p\fP to make all annotations axis\-parallel [horizontal]; if not used you may have to set \fB\-C\fP to secure
extra space for long horizontal annotations.
Append \fB+w\fP to draw horizontal and vertical lines between interior panels using selected pen [no lines].
.UNINDENT
.INDENT 0.0
.TP
\fB\-T\fP\fIheading\fP
While individual subplots can have titles (see \fB\-S\fP or \fB\-B\fP), the entire figure may also have a
overarching \fIheading\fP [no heading]. Font is determined by setting FONT_HEADING\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.INDENT 0.0
.TP
\fB\-^\fP or just \fB\-\fP
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use \fB\-\fP).
.TP
\fB\-+\fP or just \fB+\fP
Print an extensive usage (help) message, including the explanation of
any module\-specific option (but not the GMT common options), then exits.
.TP
\fB\-?\fP or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.
.TP
\fB\-\-PAR\fP=\fIvalue\fP
Temporarily override a GMT default setting; repeatable. See /gmt.conf for parameters.
.UNINDENT
.SH SYNOPSIS (SET MODE)
.sp
\fBgmt subplot set\fP [ \fIrow,col\fP|\fIindex\fP ] [ \fB\-A\fP\fIfixedlabel\fP] [ \fB\-C\fP\fIside\fP/\fIclearance\fP[\fBu\fP] ] [  \fB\-V\fP[\fIlevel\fP] ]
.sp
Before you start plotting you must first select the active subplot.
Note: If any \fB\-J\fP option is passed with \fB?\fP as scale or width when plotting subplots,
then the dimensions of the map are automatically determined by the subplot size and your region.
For Cartesian plots: If you want the scale to apply \fIequally\fP to both dimensions
then you must specify \fB\-Jx\fP [The default \fB\-JX\fP will fill the subplot by using unequal scales].
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
.B \fIrow,col\fP
Sets the current subplot until further notice.  Note: First \fIrow\fP or \fIcol is 0, not 1. If not given we go to the next subplot by order
specified via *\fP\-A**.  As an alternative, you may bypass the \fBset\fP mode and
instead supply the common option \fB\-c\fP[\fIrow,col\fP] 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
\fIindex\fP instead which starts at 0 and follows the row or column order set via \fB\-A\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-A\fP\fIfixedlabel\fP
Overrides the automatic labeling with the given string.  No modifiers are allowed.
Placement, justification, etc. are all inherited from how \fB\-A\fP was specified by the
initial \fBsubplot begin\fP command.
.UNINDENT
.INDENT 0.0
.TP
\fB\-C\fP\fIside\fP/\fIclearance\fP[\fBu\fP]
Reserve a space of dimension \fIclearance\fP between the margin and the subplot on the specified
side, using \fIside\fP values from \fBw\fP, \fBe\fP, \fBs\fP, or \fBn\fP\&.  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 \fB\-C\fP during \fBsubplot begin\fP\&.
.UNINDENT
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.sp
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 \fB\-S\fP option in \fBsubplot begin\fP\&.  In either case, should you need to set or override
frame and axis parameters then you must specify these \fB\-B\fP options with this first plot
command.  (2) The subplot machinery automatically uses the \fB\-X\fP and \fB\-Y\fP options under
the hood so these options are not available while a subplot is active.
.SH SYNOPSIS (END MODE)
.sp
\fBgmt subplot end\fP [  \fB\-V\fP[\fIlevel\fP] ]
.sp
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 \fB\-DJ\fP 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.
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.TP
\fB\-V\fP[\fIlevel\fP] (more ...)
Select verbosity level [c].  
.UNINDENT
.SH EXAMPLES
.sp
To make a minimalistic 2x2 basemap layout called panels.pdf, try
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
gmt begin panels pdf
  gmt subplot begin 2x2 \-Fs8c \-M5p \-A \-SCb \-SRl \-Bwstr
    gmt subplot set
    gmt basemap \-R0/80/0/10
    gmt subplot set
    gmt basemap
    gmt subplot set
    gmt basemap
    gmt subplot set
    gmt basemap
  gmt subplot end
gmt end show
.ft P
.fi
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.SH RESTRICTION
.sp
Currently, nesting of subplots is not implemented.
.SH SEE ALSO
.sp
begin,
clear,
docs,
end,
figure,
inset,
gmt
.SH COPYRIGHT
2019, The GMT Team
.\" Generated by docutils manpage writer.
.