The **-B** option
^^^^^^^^^^^^^^^^^

**Syntax**

.. _-B:

**-B**\ [**p**\|\ **s**]\ *parameters*
    Set map boundary frame and axes attributes. |Add_-B|

**Description**

This is potentially the most complicated option in GMT, but most examples of its usage are actually quite simple. We
distinguish between two sets of information: :ref:`Frame settings <reference/options:Frame settings>` and
:ref:`Axes settings <reference/options:Axes settings>`.  These are set separately by their own **-B** invocations; hence
multiple **-B** specifications may be specified. The :ref:`Frame settings <reference/options:Frame settings>` cover
things such as which axes should be plotted, canvas fill, plot title (and subtitle), and what type of gridlines be
drawn, whereas the :ref:`Axes settings <reference/options:Axes settings>` deal with annotation, tick, and gridline
intervals, axes labels, and annotation units.

Frame settings
^^^^^^^^^^^^^^

The Frame settings are specified by

   **-B**\ [*axes*][**+b**][**+g**\ *fill*][**+i**\ [*val*]][**+n**][**+o**\ *lon/lat*][**+s**\ *subtitle*]\
   [**+t**\ *title*][**+w**\ [*pen*]][**+x**\ *fill*][**+y**\ *fill*][**+z**\ *fill*]

The frame setting is optional but can be invoked once to override the defaults. The following directives and modifiers
can be appended to **-B** to control the Frame settings:

- *axes* to set which of the axes should be drawn and possibly annotated using a combination of the codes listed
  below [default is :doc:`theme dependent </theme-settings>`]. Borders omitted from the set of codes will not be drawn.
  For example, **WSn** denotes that the "western" (left) and "southern" (bottom) axes should be drawn with tick-marks
  and annotations by using **W** and **S**; that the "northern" (top) edge of the plot should be drawn with tick-marks
  and without annotations by using **n**; and that the "eastern" (right) axes should not be drawn by not including one
  of **E**\ \|\ **e**\ \|\ **r**.

   - **W**\ est, **E**\ ast, **S**\ outh, **N**\ orth, and/or (for 3-D plots) **Z** indicate axes that should be
     drawn with both tick-marks and annotations.
   - **w**\ est, **e**\ ast, **s**\ outh, **n**\ orth, and/or (for 3-D plots) **z** indicate axes that should be
     drawn with tick-marks but without annotations.
   - **l**\ (eft), **r**\ (ight), **b**\ (ottom), **t**\ (op) and/or (for 3-D plots) **u**\ (p) indicate axes that
     should be drawn without tick-marks or annotations.

- **Z**\|\ **z**\ *code* (for 3-D plots) where *code* is any combination of the corner ids **1**, **2**, **3**, **4**.
  By default, a single vertical axes will be plotted for 3-D plots at the most suitable map corner. *code* can be used
  to override this, where **1** represents the south-western (lower-left) corner, **2** the south-eastern (lower-right),
  **3** the north-eastern (upper-right), and **4** the north-western (upper-left) corner.

- **+w**\ [*pen*] (for 3-D plots) to draw the outlines of the x-z and y-z planes [default is no outlines]. Optionally,
  append *pen* to specify different :ref:`pen <-Wpen_attrib>` attributes [default is :term:`MAP_GRID_PEN_PRIMARY`].

- **+b** (for 3-D plots) to draw the foreground lines of the 3-D cube defined by :ref:`-R <option_-R>`.

- **+g**\ *fill* to paint the interior of the canvas with a color specified by :doc:`fill </gmtcolors>` [default is
  *no fill*]. This also sets fill for the two back-walls in 3-D plots.

- **+x**\ *fill* to paint the **yz** plane with a color specified by :doc:`fill </gmtcolors>` [default is
  *no fill*].

- **+y**\ *fill* to paint the **xz** plane with a color specified by :doc:`fill </gmtcolors>` [default is
  *no fill*].

- **+z**\ *fill* to paint the **xy** plane with a color specified by :doc:`fill </gmtcolors>` [default is
  *no fill*].

- **+i**\ [*val*] to annotate an internal meridian or parallel when the axis that normally would be drawn and
  annotated does not exist (e.g., for an azimuthal map with 360-degree range that has no latitude axis or a global
  Hammer map that has no longitude axis). *val* gives the meridian or parallel that should be annotated [default is
  **0**].

- **+o**\ *lon/lat* to produce oblique gridlines about another pole specified by *lon/lat* [default references to the
  North pole]. **+o** is ignored if no gridlines are requested. **Note**: One cannot specify oblique gridlines for non-geographic projections as well as the
  oblique Mercator projection.

- **+n** to have no frame and annotations at all [default is controlled by *axes*].

- **+t**\ *title* to place the string given in *title* centered above the plot frame [default is no title].

- **+s**\ *subtitle* (requires **+t**\ *title*) to place the string given in *subtitle* beneath the *title* [default is
  no subtitle].

**Note**: Both **+t**\ *title* and **+s**\ *subtitle* may be set over multiple lines by breaking them up using the
markers @^ or <break>.  To include LaTeX code as part of a single-line title or subtitle, enclose the expression
with @[ markers (or alternatively <math> ... </math>) (requires ``latex`` and ``dvips`` to be installed). See the
:doc:`/reference/gmt-latex` chapter for more details.

Axes settings
^^^^^^^^^^^^^

The Axes settings are specified by

   **-B**\ [**p**\|\ **s**][**x**\|\ **y**\|\ **z**]\ *intervals*\ [**+a**\ *angle*\|\ **n**\|\ **p**][**+f**]\
   [**+l**\ *label*][**+p**\ *prefix*][**+u**\ *unit*]

but you may also split this into two separate invocations for clarity, i.e.,

   | **-B**\ [**p**\|\ **s**][**x**\|\ **y**\|\ **z**][**+a**\ *angle*\|\ **n**\|\ **p**][**+e**\ [**l**\|\ **u**]][**+f**]\
     [**+l**\|\ **L**\ *label*][**+p**\ *prefix*][**+s**\|\ **S**\ *seclabel*][**+u**\ *unit*]
   | **-B**\ [**p**\|\ **s**][**x**\|\ **y**\|\ **z**]\ *intervals*

The following directives and modifiers can be appended to **-B** to control the Axes settings:

- **p**\|\ **s** to set whether the modifiers apply to the **p**\ (rimary) or **s**\ (econdary) axes [Default is **p**].
  These settings are mostly used for time axes annotations but are available for geographic axes as well. **Note**:
  Primary refers to annotations closest to the axis and secondary to annotations further away.  Hence, primary
  annotation-, tick-, and gridline-intervals must be shorter than their secondary counterparts. The terms "primary" and
  "secondary" do not reflect any hierarchical order of units: the "primary" annotation interval is usually smaller
  (e.g., days) while the "secondary" annotation interval typically is larger (e.g., months).
- **x**\|\ **y**\|\ **z** to set which axes the modifiers apply to [default is **xy**]. If you wish to give different
  annotation intervals or labels for the various axes then you must repeat the **B** option for each axis. For a
  3-D plot with the **-p** and **-Jz** options used, **-Bz** can be used to provide settings for the vertical axis.
- **+e** to give skip annotations that fall exactly at the ends of the axis.  Append **l** or **u** to only
  skip the lower or upper annotation, respectively.
- **+f** (for geographic axes only) to give fancy annotations with W\|\ E\|\ S\|\ N suffixes encoding the sign.
- **+l**\|\ **+L**\ *label* (for Cartesian plots only) to add a label to an axis. **+l** uses the default
  label orientation; **+L** forces a horizontal label for *y*-axes, which is useful for very short labels.
- **+s**\|\ **S**\ *seclabel* (for Cartesian plots only) to specify an alternate label for the right or upper axes.
  **+s** uses the default label orientation; **+S** forces a horizontal label for *y*-axes, which is useful for very
  short labels.
- **+p**\ *prefix* (for Cartesian plots only) to define a leading text prefix for the axis annotation (e.g., dollar sign for plots related to
  money). For geographic maps the addition of degree symbols, etc. is automatic and controlled by
  :term:`FORMAT_GEO_MAP`.
- **+u**\ *unit* (for Cartesian plots only) to append specific units to the annotations. For geographic maps the
  addition of degree symbols, etc. is automatic and controlled by :term:`FORMAT_GEO_MAP`.
- **+a**\ *angle* (for Cartesian plots only) to plot slanted annotations, where *angle* is measured with respect to
  the horizontal and must be in the -90 <= *angle* <= 90 range. **+an** can be used as a shorthand for normal
  (i.e., **+a**\ 90) [Default for y-axis] and **+ap** for parallel (i.e., **+a**\ 0) annotations [Default for
  x-axis]. These defaults can be changed via :term:`MAP_ANNOT_ORTHO`.
- *intervals* to define the intervals for annotations and major tick spacing, minor tick spacing, and/or grid line
  spacing. See :ref:`Intervals Specification <option_-B_int>` for the formatting associated with this modifier.

**NOTE**: To include LaTeX code as part of a label, enclose the expression with @[ markers (or alternatively <math>
... </math>). (requires ``latex`` and ``dvips`` to be installed). See the :doc:`/reference/gmt-latex` chapter for more
details.

**NOTE**: If any labels, prefixes, or units contain spaces or special characters you will need to enclose them in
quotes.

**NOTE**: Text items such as *title*, *subtitle*, *label* and *seclabel* are seen by GMT as part of a long string
containing everything passed to **-B**. Therefore, they cannot contain substrings that look like other modifiers. If
you need to embed such sequences (e.g., **+t**\ "Solving a+b=c") you need to replace those + symbols with their
:doc:`octal equivalent </reference/octal-codes>` \\053, (e.g., **+t**\ "Solving a\\053b=c").

**NOTE**: For non-geographical projections: Give negative scale (in **-Jx**) or axis length (in **-JX**) to change the
direction of increasing coordinates (i.e., to make the y-axis positive down).

.. _option_-B_int:

| **Intervals specification**
| The *intervals* specification is a concatenated string made up of substrings of the form

   [**a**\|\ **f**\|\ **g**]\ [*stride*][*phase*][*unit*].

The choice of **a**\|\ **f**\|\ **g** sets the axis item of interest, which are detailed in the Table
:ref:`interval types <tbl-inttype>`. Optionally, append *phase* to shift the annotations by that amount (positive or
negative with the sign being required). Optionally, append *unit* to specify the units of *stride*, where *unit* is one
of the 18 supported :ref:`unit codes <tbl-units>`. For custom annotations and intervals, *intervals* can be given as
**c**\ *intfile*, where *intfile* contains any number of records with *coord* *type* [*label*]. See the section
:ref:`Custom axes <custom_axes>` for more details.

.. _tbl-inttype:

+------------+-------------------------------------+
| **Flag**   | **Description**                     |
+============+=====================================+
| **a**      | Annotation and major tick spacing   |
+------------+-------------------------------------+
| **f**      | Minor tick spacing                  |
+------------+-------------------------------------+
| **g**      | Grid line spacing                   |
+------------+-------------------------------------+

**NOTE**: The appearance of certain time annotations (month-, week-, and day-names) may be affected by the
:term:`GMT_LANGUAGE`, :term:`FORMAT_TIME_PRIMARY_MAP`, and :term:`FORMAT_TIME_SECONDARY_MAP` settings.

*Automatic intervals*:
GMT will auto-select the spacing between the annotations and major ticks, minor ticks, and grid lines if *stride* is
not provided after **a**\|\ **f**\|\ **g**. This can be useful for automated plots where the region may not always be
the same, making it difficult to determine the appropriate *stride* in advance. For example, **-Bafg** will select all
three spacings automatically for both axes. In case of longitude–latitude plots, this will keep the spacing the same on
both axes. You can also use **-Bxafg -Byafg** to auto-select them separately. Note that given the myriad ways of
specifying time-axis annotations, the automatic selections may need to be overridden with manual settings to achieve
exactly what you need. When *stride* is omitted after **g**, the grid line are spaced the same as the minor ticks;
unless **g** is used in consort with **a**, in which case the grid lines are spaced the same as the annotations.

*Stride units*:
The *unit* flag can take on one of 18 codes which are listed in Table :ref:`Units <tbl-units>`. Almost all of these
units are time-axis specific. However, the **d**, **m**, and **s** units will be interpreted as arc degrees, minutes,
and arc seconds respectively when a map projection is in effect.

.. _tbl-units:

+------------+------------------+----------------------------------------------------------------------------------+
| **Flag**   | **Unit**         | **Description**                                                                  |
+============+==================+==================================================================================+
| **Y**      | year             | Plot using all 4 digits                                                          |
+------------+------------------+----------------------------------------------------------------------------------+
| **y**      | year             | Plot using last 2 digits                                                         |
+------------+------------------+----------------------------------------------------------------------------------+
| **O**      | month            | Format annotation using :term:`FORMAT_DATE_MAP`                                  |
+------------+------------------+----------------------------------------------------------------------------------+
| **o**      | month            | Plot as 2-digit integer (1–12)                                                   |
+------------+------------------+----------------------------------------------------------------------------------+
| **U**      | ISO week         | Format annotation using :term:`FORMAT_DATE_MAP`                                  |
+------------+------------------+----------------------------------------------------------------------------------+
| **u**      | ISO week         | Plot as 2-digit integer (1–53)                                                   |
+------------+------------------+----------------------------------------------------------------------------------+
| **r**      | Gregorian week   | 7-day stride from start of week (see :term:`TIME_WEEK_START`)                    |
+------------+------------------+----------------------------------------------------------------------------------+
| **K**      | ISO weekday      | Plot name of weekday in selected language                                        |
+------------+------------------+----------------------------------------------------------------------------------+
| **k**      | weekday          | Plot number of day in the week (1–7) (see :term:`TIME_WEEK_START`)               |
+------------+------------------+----------------------------------------------------------------------------------+
| **D**      | date             | Format annotation using :term:`FORMAT_DATE_MAP`                                  |
+------------+------------------+----------------------------------------------------------------------------------+
| **d**      | day              | Plot day of month (1–31) or day of year (1–366) (see :term:`FORMAT_DATE_MAP`)    |
+------------+------------------+----------------------------------------------------------------------------------+
| **R**      | day              | Same as **d**; annotations aligned with week (see :term:`TIME_WEEK_START`)       |
+------------+------------------+----------------------------------------------------------------------------------+
| **H**      | hour             | Format annotation using :term:`FORMAT_CLOCK_MAP`                                 |
+------------+------------------+----------------------------------------------------------------------------------+
| **h**      | hour             | Plot as 2-digit integer (0–24)                                                   |
+------------+------------------+----------------------------------------------------------------------------------+
| **M**      | minute           | Format annotation using :term:`FORMAT_CLOCK_MAP`                                 |
+------------+------------------+----------------------------------------------------------------------------------+
| **m**      | minute           | Plot as 2-digit integer (0–60)                                                   |
+------------+------------------+----------------------------------------------------------------------------------+
| **S**      | seconds          | Format annotation using :term:`FORMAT_CLOCK_MAP`                                 |
+------------+------------------+----------------------------------------------------------------------------------+
| **s**      | seconds          | Plot as 2-digit integer (0–60)                                                   |
+------------+------------------+----------------------------------------------------------------------------------+

**NOTE**: If your axis is in radians you can use multiples or fractions of **pi** to set such annotation intervals. The
format is [*s*]\ **pi**\ [*f*], for an optional integer scale *s* and optional integer fraction *f*. When GMT parses one
of these forms we alert the labeling machinery to look for certain combinations of **pi**, limited to *n*\ **pi**\ ,
3/2 **pi** (3\ **pi**\ 2), and fractions 3/4 (3\ **pi**\ 4), 2/3 (2\ **pi**\ 3), 1/2 (1\ **pi**\ 2), 1/3 (1\ **pi**\ 3),
and 1/4 (1\ **pi**\ 4) in the *interval* given to the **-B** axes settings.  When an annotated value is within
roundoff-error of these combinations we typeset the label using the Greek letter :math:`\pi` and required multiples or
fractions.

**NOTE**: These GMT parameters can affect the appearance of the map boundary:
    :term:`MAP_ANNOT_MIN_ANGLE`, :term:`MAP_ANNOT_MIN_SPACING`,
    :term:`FONT_ANNOT_PRIMARY`, :term:`FONT_ANNOT_SECONDARY`,
    :term:`MAP_ANNOT_OFFSET_PRIMARY`,
    :term:`MAP_ANNOT_OFFSET_SECONDARY`,
    :term:`MAP_ANNOT_ORTHO`, :term:`MAP_FRAME_AXES`, :term:`MAP_DEFAULT_PEN`,
    :term:`MAP_FRAME_TYPE`, :term:`FORMAT_GEO_MAP`, :term:`MAP_FRAME_PEN`,
    :term:`MAP_FRAME_WIDTH`, :term:`MAP_GRID_CROSS_SIZE_PRIMARY`,
    :term:`MAP_GRID_PEN_PRIMARY`, :term:`MAP_GRID_CROSS_SIZE_SECONDARY`,
    :term:`MAP_GRID_PEN_SECONDARY`, :term:`FONT_TITLE`, :term:`FONT_LABEL`,
    :term:`MAP_LINE_STEP`, :term:`MAP_ANNOT_OBLIQUE`,
    :term:`FORMAT_CLOCK_MAP`, :term:`FORMAT_DATE_MAP`,
    :term:`FORMAT_TIME_PRIMARY_MAP`, :term:`FORMAT_TIME_SECONDARY_MAP`,
    :term:`GMT_LANGUAGE`, :term:`TIME_WEEK_START`,
    :term:`MAP_TICK_LENGTH_PRIMARY`,
    and :term:`MAP_TICK_PEN_PRIMARY`; see the :doc:`/gmt.conf` man page for details.
