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 modules that
plot scales, bars, text, etc. This setting overrides the common
clearances set by ``clearance`` in the initial
:meth:`pygmt.Figure.subplot` call.
{V}
"""
kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access
# allow for spaces in string with needing double quotes
kwargs["A"] = f'"{kwargs.get("A")}"' if kwargs.get(
"A") is not None else None
# convert tuple or list to comma-separated str
panel = ",".join(map(str, panel)) if is_nonstr_iter(panel) else panel
with Session() as lib:
arg_str = " ".join(["set", f"{panel}", build_arg_string(kwargs)])
lib.call_module(module="subplot", args=arg_str)
yield
def plot3d(self,
data=None,
x=None,
y=None,
z=None,
size=None,
direction=None,
**kwargs):
r"""
Plot lines, polygons, and symbols in 3-D.
Takes a matrix, (x,y,z) triplets, or a file name as input and plots
lines, polygons, or symbols at those locations in 3-D.
Must provide either ``data`` or ``x``/``y``/``z``.
If providing data through ``x/y/z``, ``color`` can be a 1d array
that will be mapped to a colormap.
If a symbol is selected and no symbol size given, then plot3d will
interpret the fourth column of the input data as symbol size. Symbols
whose size is <= 0 are skipped. If no symbols are specified then the
symbol code (see ``style`` below) must be present as last column in the
input. If ``style`` is not used, a line connecting the data points will
be drawn instead. To explicitly close polygons, use ``close``. Select a
fill with ``color``. If ``color`` is set, ``pen`` will control whether the
polygon outline is drawn or not. If a symbol is selected, ``color`` and
``pen`` determines the fill and outline/no outline, respectively.
Full option list at :gmt-docs:`plot3d.html`
{aliases}
Parameters
----------
data : str or {table-like}
Either a data file name, a 2d {table-classes}.
Optionally, use parameter ``incols`` to specify which columns are x, y,
z, color, and size, respectively.
x/y/z : float or 1d arrays
The x, y, and z coordinates, or arrays of x, y and z coordinates of
the data points
size : 1d array
The size of the data points in units specified in ``style``.
Only valid if using ``x``/``y``/``z``.
direction : list of two 1d arrays
If plotting vectors (using ``style='V'`` or ``style='v'``), then
should be a list of two 1d arrays with the vector directions. These
can be angle and length, azimuth and length, or x and y components,
depending on the style options chosen.
{J}
zscale/zsize : float or str
Set z-axis scaling or z-axis size.
{R}
straight_line : bool or str
[**m**\|\ **p**\|\ **x**\|\ **y**].
By default, geographic line segments are drawn as great circle
arcs. To draw them as straight lines, use ``straight_line``.
Alternatively, add **m** to draw the line by first following a
meridian, then a parallel. Or append **p** to start following a
parallel, then a meridian. (This can be practical to draw a line
along parallels, for example). For Cartesian data, points are
simply connected, unless you append **x** or **y** to draw
stair-case curves that whose first move is along *x* or *y*,
respectively. **Note**: The ``straight_line`` parameter requires
constant *z*-coordinates.
{B}
{CPT}
offset : str
*dx*/*dy*\ [/*dz*].
Offset the plot symbol or line locations by the given amounts
*dx*/*dy*\ [/*dz*] [Default is no offset].
{G}
*color* can be a 1d array, but it is only valid if using ``x``/``y``
and ``cmap=True`` is also required.
intensity : float or bool or 1d array
Provide an *intensity* value (nominally in the -1 to +1 range) to
modulate the fill color by simulating illumination. If using
``intensity=True``, we will instead read *intensity* from the first
data column after the symbol parameters (if given). *intensity* can
also be a 1d array to set varying intensity for symbols, but it is only
valid for ``x``/``y``/``z``.
close : str
[**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*]\
[**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*].
Force closed polygons. Full documentation is at
:gmt-docs:`plot3d.html#l`.
no_clip : bool or str
[**c**\|\ **r**].
Do NOT clip symbols that fall outside map border [Default plots
points whose coordinates are strictly inside the map border only].
This parameter does not apply to lines and polygons which are always
clipped to the map region. For periodic (360-longitude) maps we
must plot all symbols twice in case they are clipped by the
repeating boundary. ``no_clip=True`` will turn off clipping and not
plot repeating symbols. Use ``no_clip="r"`` to turn off clipping
but retain the plotting of such repeating symbols, or use
``no_clip="c"`` to retain clipping but turn off plotting of
repeating symbols.
no_sort : bool
Turn off the automatic sorting of items based on their distance
from the viewer. The default is to sort the items so that items in
the foreground are plotted after items in the background.
style : str
Plot symbols. Full documentation is at :gmt-docs:`plot3d.html#s`.
{U}
{V}
{W}
{XY}
zvalue : str
*value*\|\ *file*.
Instead of specifying a symbol or polygon fill and outline color
via ``color`` and ``pen``, give both a *value* via **zvalue** and a
color lookup table via ``cmap``. Alternatively, give the name of a
*file* with one z-value (read from the last column) for each
polygon in the input data. To apply it to the fill color, use
``color='+z'``. To apply it to the pen color, append **+z** to
``pen``.
{a}
{b}
{c}
{d}
{e}
{f}
{g}
{h}
{i}
{l}
{p}
{t}
*transparency* can also be a 1d array to set varying transparency
for symbols, but this option is only valid if using x/y/z.
{w}
"""
# pylint: disable=too-many-locals
kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access
kind = data_kind(data, x, y, z)
extra_arrays = []
if kwargs.get("S") is not None and kwargs["S"][
0] in "vV" and direction is not None:
extra_arrays.extend(direction)
elif (
kwargs.get("S") is None and kind == "geojson"
and data.geom_type.isin(["Point", "MultiPoint"]).all()
): # checking if the geometry of a geoDataFrame is Point or MultiPoint
kwargs["S"] = "u0.2c"
elif kwargs.get("S") is None and kind == "file" and str(data).endswith(
".gmt"):
# checking that the data is a file path to set default style
try:
with open(which(data), mode="r", encoding="utf8") as file:
line = file.readline()
if "@GMULTIPOINT" in line or "@GPOINT" in line:
# if the file is gmt style and geometry is set to Point
kwargs["S"] = "u0.2c"
except FileNotFoundError:
pass
if kwargs.get("G") is not None and is_nonstr_iter(kwargs["G"]):
if kind != "vectors":
raise GMTInvalidInput(
"Can't use arrays for color if data is matrix or file.")
extra_arrays.append(kwargs["G"])
del kwargs["G"]
if size is not None:
if kind != "vectors":
raise GMTInvalidInput(
"Can't use arrays for 'size' if data is a matrix or a file.")
extra_arrays.append(size)
for flag in ["I", "t"]:
if kwargs.get(flag) is not None and is_nonstr_iter(kwargs[flag]):
if kind != "vectors":
raise GMTInvalidInput(
f"Can't use arrays for {plot3d.aliases[flag]} if data is matrix or file."
)
extra_arrays.append(kwargs[flag])
kwargs[flag] = ""
with Session() as lib:
# Choose how data will be passed in to the module
file_context = lib.virtualfile_from_data(
check_kind="vector",
data=data,
x=x,
y=y,
z=z,
extra_arrays=extra_arrays,
required_z=True,
)
with file_context as fname:
lib.call_module(module="plot3d",
args=build_arg_string(kwargs, infile=fname))
def plot(self, x=None, y=None, data=None, size=None, direction=None, **kwargs):
r"""
Plot lines, polygons, and symbols in 2-D.
Takes a matrix, (x,y) pairs, or a file name as input and plots lines,
polygons, or symbols at those locations on a map.
Must provide either ``data`` or ``x``/``y``.
If providing data through ``x``/``y``, ``color`` can be a 1d array that
will be mapped to a colormap.
If a symbol is selected and no symbol size given, then plot will
interpret the third column of the input data as symbol size. Symbols
whose size is <= 0 are skipped. If no symbols are specified then the
symbol code (see ``style`` below) must be present as last column in the
input. If ``style`` is not used, a line connecting the data points will
be drawn instead. To explicitly close polygons, use ``close``. Select a
fill with ``color``. If ``color`` is set, ``pen`` will control whether the
polygon outline is drawn or not. If a symbol is selected, ``color`` and
``pen`` determines the fill and outline/no outline, respectively.
Full parameter list at :gmt-docs:`plot.html`
{aliases}
Parameters
----------
x/y : float or 1d arrays
The x and y coordinates, or arrays of x and y coordinates of the
data points
data : str or {table-like}
Pass in either a file name to an ASCII data table, a 2D
{table-classes}.
Use parameter ``columns`` to choose which columns are x, y, color, and
size, respectively.
size : 1d array
The size of the data points in units specified using ``style``.
Only valid if using ``x``/``y``.
direction : list of two 1d arrays
If plotting vectors (using ``style='V'`` or ``style='v'``), then
should be a list of two 1d arrays with the vector directions. These
can be angle and length, azimuth and length, or x and y components,
depending on the style options chosen.
{J}
{R}
straight_line : bool or str
[**m**\|\ **p**\|\ **x**\|\ **y**].
By default, geographic line segments are drawn as great circle
arcs. To draw them as straight lines, use ``straight_line``.
Alternatively, add **m** to draw the line by first following a
meridian, then a parallel. Or append **p** to start following a
parallel, then a meridian. (This can be practical to draw a line
along parallels, for example). For Cartesian data, points are
simply connected, unless you append **x** or **y** to draw
stair-case curves that whose first move is along *x* or *y*,
respectively.
{B}
{CPT}
offset : str
*dx*/*dy*.
Offset the plot symbol or line locations by the given amounts
*dx/dy* [Default is no offset]. If *dy* is not given it is set
equal to *dx*.
error_bar : bool or str
[**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*]\
[**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*].
Draw symmetrical error bars. Full documentation is at
:gmt-docs:`plot.html#e`.
connection : str
[**c**\|\ **n**\|\ **r**]\
[**a**\|\ **f**\|\ **s**\|\ **r**\|\ *refpoint*].
Alter the way points are connected (by specifying a *scheme*) and
data are grouped (by specifying a *method*). Append one of three
line connection schemes:
- **c** : Draw continuous line segments for each group [Default].
- **r** : Draw line segments from a reference point reset for each
group.
- **n** : Draw networks of line segments between all points in
each group.
Optionally, append the one of four segmentation methods to define
the group:
- **a** : Ignore all segment headers, i.e., let all points belong
to a single group, and set group reference point to the very
first point of the first file.
- **f** : Consider all data in each file to be a single separate
group and reset the group reference point to the first point of
each group.
- **s** : Segment headers are honored so each segment is a group;
the group reference point is reset to the first point of each
incoming segment [Default].
- **r** : Same as **s**, but the group reference point is reset
after each record to the previous point (this method is only
available with the ``connection='r'`` scheme).
Instead of the codes **a**\|\ **f**\|\ **s**\|\ **r** you may append
the coordinates of a *refpoint* which will serve as a fixed external
reference point for all groups.
{G}
*color* can be a 1d array, but it is only valid if using ``x``/``y``
and ``cmap=True`` is also required.
intensity : float or bool or 1d array
Provide an *intensity* value (nominally in the -1 to +1 range) to
modulate the fill color by simulating illumination. If using
``intensity=True``, we will instead read *intensity* from the first
data column after the symbol parameters (if given). *intensity* can
also be a 1d array to set varying intensity for symbols, but it is only
valid for ``x``/``y`` pairs.
close : str
[**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*]\
[**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*].
Force closed polygons. Full documentation is at
:gmt-docs:`plot.html#l`.
no_clip : bool or str
[**c**\|\ **r**].
Do NOT clip symbols that fall outside map border [Default plots
points whose coordinates are strictly inside the map border only].
The parameter does not apply to lines and polygons which are always
clipped to the map region. For periodic (360-longitude) maps we
must plot all symbols twice in case they are clipped by the
repeating boundary. ``no_clip=True`` will turn off clipping and not
plot repeating symbols. Use ``no_clip="r"`` to turn off clipping
but retain the plotting of such repeating symbols, or use
``no_clip="c"`` to retain clipping but turn off plotting of
repeating symbols.
style : str
Plot symbols (including vectors, pie slices, fronts, decorated or
quoted lines).
{W}
{U}
{V}
{XY}
zvalue : str
*value*\|\ *file*.
Instead of specifying a symbol or polygon fill and outline color
via ``color`` and ``pen``, give both a *value* via ``zvalue`` and a
color lookup table via ``cmap``. Alternatively, give the name of a
*file* with one z-value (read from the last column) for each
polygon in the input data. To apply it to the fill color, use
``color='+z'``. To apply it to the pen color, append **+z** to
``pen``.
{a}
{c}
{f}
{i}
label : str
Add a legend entry for the symbol or line being plotted.
{p}
{t}
*transparency* can also be a 1d array to set varying transparency
for symbols, but this option is only valid if using x/y.
"""
kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access
kind = data_kind(data, x, y)
extra_arrays = []
if "S" in kwargs and kwargs["S"][0] in "vV" and direction is not None:
extra_arrays.extend(direction)
if "G" in kwargs and not isinstance(kwargs["G"], str):
if kind != "vectors":
raise GMTInvalidInput(
"Can't use arrays for color if data is matrix or file."
)
extra_arrays.append(kwargs["G"])
del kwargs["G"]
if size is not None:
if kind != "vectors":
raise GMTInvalidInput(
"Can't use arrays for 'size' if data is a matrix or file."
)
extra_arrays.append(size)
for flag in ["I", "t"]:
if flag in kwargs and is_nonstr_iter(kwargs[flag]):
if kind != "vectors":
raise GMTInvalidInput(
f"Can't use arrays for {plot.aliases[flag]} if data is matrix or file."
)
extra_arrays.append(kwargs[flag])
kwargs[flag] = ""
with Session() as lib:
# Choose how data will be passed in to the module
file_context = lib.virtualfile_from_data(
check_kind="vector", data=data, x=x, y=y, extra_arrays=extra_arrays
)
with file_context as fname:
arg_str = " ".join([fname, build_arg_string(kwargs)])
lib.call_module("plot", arg_str)
def plot3d(self,
x=None,
y=None,
z=None,
data=None,
sizes=None,
direction=None,
**kwargs):
r"""
Plot lines, polygons, and symbols in 3-D.
Takes a matrix, (x,y,z) triplets, or a file name as input and plots
lines, polygons, or symbols at those locations in 3-D.
Must provide either ``data`` or ``x``/``y``/``z``.
If providing data through ``x/y/z``, ``color`` can be a 1d array
that will be mapped to a colormap.
If a symbol is selected and no symbol size given, then plot3d will
interpret the fourth column of the input data as symbol size. Symbols
whose size is <= 0 are skipped. If no symbols are specified then the
symbol code (see ``style`` below) must be present as last column in the
input. If ``style`` is not used, a line connecting the data points will
be drawn instead. To explicitly close polygons, use ``close``. Select a
fill with ``color``. If ``color`` is set, ``pen`` will control whether the
polygon outline is drawn or not. If a symbol is selected, ``color`` and
``pen`` determines the fill and outline/no outline, respectively.
Full parameter list at :gmt-docs:`plot3d.html`
{aliases}
Parameters
----------
x/y/z : float or 1d arrays
The x, y, and z coordinates, or arrays of x, y and z coordinates of
the data points
data : str or 2d array
Either a data file name or a 2d numpy array with the tabular data.
Use parameter ``columns`` to choose which columns are x, y, z,
color, and size, respectively.
sizes : 1d array
The sizes of the data points in units specified in ``style``.
Only valid if using ``x``/``y``/``z``.
direction : list of two 1d arrays
If plotting vectors (using ``style='V'`` or ``style='v'``), then
should be a list of two 1d arrays with the vector directions. These
can be angle and length, azimuth and length, or x and y components,
depending on the style options chosen.
{J}
zscale/zsize : float or str
Set z-axis scaling or z-axis size.
{R}
straight_line : bool or str
[**m**\|\ **p**\|\ **x**\|\ **y**].
By default, geographic line segments are drawn as great circle
arcs. To draw them as straight lines, use ``straight_line``.
Alternatively, add **m** to draw the line by first following a
meridian, then a parallel. Or append **p** to start following a
parallel, then a meridian. (This can be practical to draw a line
along parallels, for example). For Cartesian data, points are
simply connected, unless you append **x** or **y** to draw
stair-case curves that whose first move is along *x* or *y*,
respectively. **Note**: The ``straight_line`` parameter requires
constant *z*-coordinates.
{B}
{CPT}
offset : str
*dx*/*dy*\ [/*dz*].
Offset the plot symbol or line locations by the given amounts
*dx*/*dy*\ [/*dz*] [Default is no offset].
{G}
intensity : float or bool
Provide an *intens* value (nominally in the -1 to +1 range) to
modulate the fill color by simulating illumination [Default is None].
If using ``intensity=True``, we will instead read *intens* from the
first data column after the symbol parameters (if given).
close : str
[**+b**\|\ **d**\|\ **D**][**+xl**\|\ **r**\|\ *x0*]\
[**+yl**\|\ **r**\|\ *y0*][**+p**\ *pen*].
Force closed polygons. Full documentation is at
:gmt-docs:`plot3d.html#l`.
no_clip : bool or str
[**c**\|\ **r**].
Do NOT clip symbols that fall outside map border [Default plots
points whose coordinates are strictly inside the map border only].
This parameter does not apply to lines and polygons which are always
clipped to the map region. For periodic (360-longitude) maps we
must plot all symbols twice in case they are clipped by the
repeating boundary. ``no_clip=True`` will turn off clipping and not
plot repeating symbols. Use ``no_clip="r"`` to turn off clipping
but retain the plotting of such repeating symbols, or use
``no_clip="c"`` to retain clipping but turn off plotting of
repeating symbols.
no_sort : bool
Turn off the automatic sorting of items based on their distance
from the viewer. The default is to sort the items so that items in
the foreground are plotted after items in the background.
style : str
Plot symbols. Full documentation is at :gmt-docs:`plot3d.html#s`.
{U}
{V}
{W}
{XY}
zvalue : str
*value*\|\ *file*.
Instead of specifying a symbol or polygon fill and outline color
via ``color`` and ``pen``, give both a *value* via **zvalue** and a
color lookup table via ``cmap``. Alternatively, give the name of a
*file* with one z-value (read from the last column) for each
polygon in the input data. To apply it to the fill color, use
``color='+z'``. To apply it to the pen color, append **+z** to
``pen``.
{c}
label : str
Add a legend entry for the symbol or line being plotted.
{p}
{t}
*transparency* can also be a 1d array to set varying transparency
for symbols.
"""
kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access
kind = data_kind(data, x, y, z)
extra_arrays = []
if "S" in kwargs and kwargs["S"][0] in "vV" and direction is not None:
extra_arrays.extend(direction)
if "G" in kwargs and not isinstance(kwargs["G"], str):
if kind != "vectors":
raise GMTInvalidInput(
"Can't use arrays for color if data is matrix or file.")
extra_arrays.append(kwargs["G"])
del kwargs["G"]
if sizes is not None:
if kind != "vectors":
raise GMTInvalidInput(
"Can't use arrays for sizes if data is matrix or file.")
extra_arrays.append(sizes)
if "t" in kwargs and is_nonstr_iter(kwargs["t"]):
extra_arrays.append(kwargs["t"])
kwargs["t"] = ""
with Session() as lib:
# Choose how data will be passed in to the module
if kind == "file":
file_context = dummy_context(data)
elif kind == "matrix":
file_context = lib.virtualfile_from_matrix(data)
elif kind == "vectors":
file_context = lib.virtualfile_from_vectors(
np.atleast_1d(x), np.atleast_1d(y), np.atleast_1d(z),
*extra_arrays)
with file_context as fname:
arg_str = " ".join([fname, build_arg_string(kwargs)])
lib.call_module("plot3d", arg_str)
def text_(
self,
textfiles=None,
x=None,
y=None,
position=None,
text=None,
angle=None,
font=None,
justify=None,
**kwargs,
):
r"""
Plot or typeset text strings of variable size, font type, and orientation.
Must provide at least one of the following combinations as input:
- ``textfiles``
- ``x``/``y``, and ``text``
- ``position`` and ``text``
Full parameter list at :gmt-docs:`text.html`
{aliases}
Parameters
----------
textfiles : str or list
A text data file name, or a list of filenames containing 1 or more
records with (x, y[, angle, font, justify], text).
x/y : float or 1d arrays
The x and y coordinates, or an array of x and y coordinates to plot
the text
position : str
Sets reference point on the map for the text by using x,y
coordinates extracted from ``region`` instead of providing them
through ``x``/``y``. Specify with a two letter (order independent)
code, chosen from:
* Horizontal: **L**\ (eft), **C**\ (entre), **R**\ (ight)
* Vertical: **T**\ (op), **M**\ (iddle), **B**\ (ottom)
For example, ``position="TL"`` plots the text at the Upper Left corner
of the map.
text : str or 1d array
The text string, or an array of strings to plot on the figure
angle: int, float, str or bool
Set the angle measured in degrees counter-clockwise from
horizontal (e.g. 30 sets the text at 30 degrees). If no angle is
explicitly given (i.e. ``angle=True``) then the input to ``textfiles``
must have this as a column.
font : str or bool
Set the font specification with format *size*\ ,\ *font*\ ,\ *color*
where *size* is text size in points, *font* is the font to use, and
*color* sets the font color. For example,
``font="12p,Helvetica-Bold,red"`` selects a 12p, red, Helvetica-Bold
font. If no font info is explicitly given (i.e. ``font=True``), then
the input to ``textfiles`` must have this information in one of its
columns.
justify : str or bool
Set the alignment which refers to the part of the text string that
will be mapped onto the (x,y) point. Choose a 2 character
combination of **L**, **C**, **R** (for left, center, or right) and
**T**, **M**, **B** for top, middle, or bottom. E.g., **BL** for lower
left. If no justification is explicitly given (i.e. ``justify=True``),
then the input to ``textfiles`` must have this as a column.
{J}
{R}
*Required if this is the first plot command.*
clearance : str
[*dx/dy*][**+to**\|\ **O**\|\ **c**\|\ **C**].
Adjust the clearance between the text and the surrounding box
[Default is 15% of the font size]. Only used if ``pen`` or ``fill`` are
specified. Append the unit you want (*c* for cm, *i* for inch, or *p*
for point; if not given we consult **PROJ_LENGTH_UNIT**) or *%* for a
percentage of the font size. Optionally, use modifier **+t** to set
the shape of the textbox when using ``fill`` and/or ``pen``. Append
lower case **o** to get a straight rectangle [Default is **o**]. Append
upper case **O** to get a rounded rectangle. In paragraph mode
(*paragraph*) you can also append lower case **c** to get a concave
rectangle or append upper case **C** to get a convex rectangle.
fill : str
Sets the shade or color used for filling the text box [Default is
no fill].
offset : str
[**j**\|\ **J**]\ *dx*\[/*dy*][**+v**\[*pen*]].
Offsets the text from the projected (x,y) point by *dx*,\ *dy* [0/0].
If *dy* is not specified then it is set equal to *dx*. Use **j** to
offset the text away from the point instead (i.e., the text
justification will determine the direction of the shift). Using
**J** will shorten diagonal offsets at corners by sqrt(2).
Optionally, append **+v** which will draw a line from the original
point to the shifted point; append a pen to change the attributes
for this line.
pen : str
Sets the pen used to draw a rectangle around the text string
(see ``clearance``) [Default is width = default, color = black,
style = solid].
no_clip : bool
Do NOT clip text at map boundaries [Default is will clip].
{U}
{V}
{XY}
{a}
{c}
{e}
{f}
{h}
{i}
{p}
{t}
*transparency* can also be a 1d array to set varying transparency
for texts, but this option is only valid if using x/y/text.
{w}
"""
# pylint: disable=too-many-locals
# pylint: disable=too-many-branches
kwargs = self._preprocess(**kwargs) # pylint: disable=protected-access
# Ensure inputs are either textfiles, x/y/text, or position/text
if position is None:
kind = data_kind(textfiles, x, y, text)
else:
if x is not None or y is not None:
raise GMTInvalidInput(
"Provide either position only, or x/y pairs, not both")
kind = "vectors"
if kind == "vectors" and text is None:
raise GMTInvalidInput("Must provide text with x/y pairs or position")
# Build the -F option in gmt text.
if "F" not in kwargs and ((position is not None or angle is not None
or font is not None or justify is not None)):
kwargs.update({"F": ""})
if angle is True:
kwargs["F"] += "+a"
elif isinstance(angle, (int, float, str)):
kwargs["F"] += f"+a{str(angle)}"
if font is True:
kwargs["F"] += "+f"
elif isinstance(font, str):
kwargs["F"] += f"+f{font}"
if justify is True:
kwargs["F"] += "+j"
elif isinstance(justify, str):
kwargs["F"] += f"+j{justify}"
if isinstance(position, str):
kwargs["F"] += f'+c{position}+t"{text}"'
extra_arrays = []
# If an array of transparency is given, GMT will read it from
# the last numerical column per data record.
if "t" in kwargs and is_nonstr_iter(kwargs["t"]):
extra_arrays.append(kwargs["t"])
kwargs["t"] = ""
with Session() as lib:
file_context = dummy_context(textfiles) if kind == "file" else ""
if kind == "vectors":
if position is not None:
file_context = dummy_context("")
else:
file_context = lib.virtualfile_from_vectors(
np.atleast_1d(x),
np.atleast_1d(y),
*extra_arrays,
# text must be in str type, see issue #706
np.atleast_1d(text).astype(str),
)
with file_context as fname:
arg_str = " ".join([fname, build_arg_string(kwargs)])
lib.call_module("text", arg_str)
