Source code for pygmt.src.subplot

"""
subplot - Manage modern mode figure subplot configuration and selection.
"""

import contextlib

from pygmt.clib import Session
from pygmt.exceptions import GMTInvalidInput
from pygmt.helpers import (
    build_arg_list,
    fmt_docstring,
    kwargs_to_strings,
    use_alias,
)


@fmt_docstring
@contextlib.contextmanager
@use_alias(
    Ff="figsize",
    Fs="subsize",
    A="autolabel",
    B="frame",
    C="clearance",
    J="projection",
    M="margins",
    R="region",
    SC="sharex",
    SR="sharey",
    T="title",
    V="verbose",
)
@kwargs_to_strings(Ff="sequence", Fs="sequence", M="sequence", R="sequence")
def subplot(self, nrows=1, ncols=1, **kwargs):
    r"""
    Create multi-panel subplot figures.

    This method 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 :gmt-docs:`subplot.html#synopsis-begin-mode`

    {aliases}

    Parameters
    ----------
    nrows : int
        Number of vertical rows of the subplot grid.
    ncols : int
        Number of horizontal columns of the subplot grid.
    figsize : list
        Specify the final figure dimensions as [*width*, *height*].
    subsize : list
        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*][**+c**\ *dx*\ [/*dy*]][**+g**\ *fill*][**+j**\|\ **J**\
        *refpoint*][**+o**\ *dx*\ [/*dy*]][**+p**\ *pen*][**+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**\|\ **J**\ *refpoint* 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
        **+c**\ *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 :gmt-term:`FONT_TAG` size dimension]. Append **+g**\ *fill* to
        paint the tag's text box with *fill* [no painting]. Append
        **+o**\ *dx*\ [/*dy*] to offset the tag's reference point in the
        direction implied by the justification [4p/4p, i.e., 20% of the
        :gmt-term:`FONT_TAG` size]. Append **+p**\ *pen* 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}
    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 methods that plot
        scales, bars, text, etc.
    {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}
    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.,
        **t**\ op) and the last (i.e., **b**\ ottom) 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.,
        **l**\ eft) and the last (i.e., **r**\ ight) 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 :gmt-term:`FONT_HEADING`.
    {verbose}
    """
    kwargs = self._preprocess(**kwargs)

    if nrows < 1 or ncols < 1:
        raise GMTInvalidInput("Please ensure that both 'nrows'>=1 and 'ncols'>=1.")
    if kwargs.get("Ff") and kwargs.get("Fs"):
        raise GMTInvalidInput(
            "Please provide either one of 'figsize' or 'subsize' only."
        )

    # Need to use separate sessions for "subplot begin" and "subplot end".
    # Otherwise, "subplot end" will use the last session, which may cause
    # strange positioning issues for later plotting calls.
    # See https://github.com/GenericMappingTools/pygmt/issues/2426.
    try:
        with Session() as lib:
            lib.call_module(
                module="subplot",
                args=["begin", f"{nrows}x{ncols}", *build_arg_list(kwargs)],
            )
            yield
    finally:
        with Session() as lib:
            lib.call_module(
                module="subplot", args=["end", *build_arg_list({"V": kwargs.get("V")})]
            )


@fmt_docstring
@contextlib.contextmanager
@use_alias(A="fixedlabel", C="clearance", V="verbose")
@kwargs_to_strings(panel="sequence_comma")
def set_panel(self, panel=None, **kwargs):
    r"""
    Set the current subplot panel to plot on.

    Before you start plotting you must first select the active subplot.
    **Note**: If any *projection* option is passed with the question mark
    **?** 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 equally to
    both dimensions then you must specify ``projection="x"`` [The default
    ``projection="X"`` will fill the subplot by using unequal scales].

    {aliases}

    Parameters
    ----------
    panel : str or list
        *row,col*\|\ *index*.
        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 ``autolabel`` in :meth:`pygmt.Figure.subplot`. As an
        alternative, you may bypass using :meth:`pygmt.Figure.set_panel` and
        instead supply the common option **panel**\ =[*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 ``autolabel`` in :meth:`pygmt.Figure.subplot`.

    fixedlabel : str
        Overrides the automatic labeling with the given string. No modifiers
        are allowed. Placement, justification, etc. are all inherited from how
        ``autolabel`` was specified by the initial :meth:`pygmt.Figure.subplot`
        command.

    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**. 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 methods that
        plot scales, bars, text, etc. This setting overrides the common
        clearances set by ``clearance`` in the initial
        :meth:`pygmt.Figure.subplot` call.

    {verbose}
    """
    kwargs = self._preprocess(**kwargs)

    with Session() as lib:
        lib.call_module(
            module="subplot", args=["set", str(panel), *build_arg_list(kwargs)]
        )
        yield