diff --git a/doc/api/index.rst b/doc/api/index.rst index 7828a225652..de563b4d07c 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -27,6 +27,7 @@ Plotting map elements Figure.basemap Figure.coast Figure.colorbar + Figure.directional_rose Figure.hlines Figure.inset Figure.legend diff --git a/pygmt/figure.py b/pygmt/figure.py index 474cd91179b..c9d7fd4f664 100644 --- a/pygmt/figure.py +++ b/pygmt/figure.py @@ -435,6 +435,7 @@ def _repr_html_(self) -> str: coast, colorbar, contour, + directional_rose, grdcontour, grdimage, grdview, diff --git a/pygmt/src/__init__.py b/pygmt/src/__init__.py index 8905124f917..1e34c3ba669 100644 --- a/pygmt/src/__init__.py +++ b/pygmt/src/__init__.py @@ -10,6 +10,7 @@ from pygmt.src.config import config from pygmt.src.contour import contour from pygmt.src.dimfilter import dimfilter +from pygmt.src.directional_rose import directional_rose from pygmt.src.filter1d import filter1d from pygmt.src.grd2cpt import grd2cpt from pygmt.src.grd2xyz import grd2xyz diff --git a/pygmt/src/basemap.py b/pygmt/src/basemap.py index b28009ab55d..bd4e5cfa46b 100644 --- a/pygmt/src/basemap.py +++ b/pygmt/src/basemap.py @@ -2,6 +2,8 @@ basemap - Plot base maps and frames. """ +import warnings + from pygmt.alias import Alias, AliasSystem from pygmt.clib import Session from pygmt.helpers import build_arg_list, fmt_docstring, kwargs_to_strings, use_alias @@ -72,8 +74,11 @@ def basemap(self, projection=None, **kwargs): [Default is ``"4p/-4p"``] and shade sets the fill style to use for shading [Default is ``"gray50"``]. rose : str - Draw a map directional rose on the map at the location defined by - the reference and anchor points. + Draw a map directional rose on the map. + + .. deprecated:: v0.17.0 + + Use :py:func:`pygmt.Figure.directional_rose` instead. compass : str Draw a map magnetic rose on the map at the location defined by the reference and anchor points. @@ -87,5 +92,14 @@ def basemap(self, projection=None, **kwargs): aliasdict = AliasSystem( J=Alias(projection, name="projection"), ).merge(kwargs) + + if aliasdict.get("Td"): + warnings.warn( + "Parameter 'rose' is deprecated and will be removed in a future version. " + "Use 'Figure.directional_rose' instead.", + DeprecationWarning, + stacklevel=2, + ) + with Session() as lib: lib.call_module(module="basemap", args=build_arg_list(aliasdict)) diff --git a/pygmt/src/directional_rose.py b/pygmt/src/directional_rose.py new file mode 100644 index 00000000000..c3588a27e20 --- /dev/null +++ b/pygmt/src/directional_rose.py @@ -0,0 +1,119 @@ +""" +directional_rose - Add a map directional rose. +""" + +from collections.abc import Sequence +from typing import Literal + +from pygmt._typing import AnchorCode +from pygmt.alias import Alias, AliasSystem +from pygmt.clib import Session +from pygmt.helpers import build_arg_list + + +def directional_rose( # noqa: PLR0913 + self, + position: Sequence[str | float] | AnchorCode, + position_type: Literal[ + "mapcoords", + "boxcoords", + "plotcoords", + "inside", + "outside", + ] = "mapcoords", + width: float | str | None = None, + justify: AnchorCode | None = None, + anchor_offset: Sequence[float | str] | None = None, + label: Sequence[str] | bool = False, + fancy: Literal[1, 2, 3] | bool = False, + box=None, + perspective=None, + verbose=None, + transparency=None, +): + r""" + Add a directional rose to the map. + + Parameters + ---------- + position/position_type + Location of the directional rose. The actual meaning of this parameter depends + on the ``position_type`` parameter. + + - ``position_type="mapcoords"``: *position* is given as (x, y) in user + coordinates. + - ``position_type="boxcoords"``: *position* is given as (nx, ny) in normalized + coordinates, where (0, 0) is the lower-left corner and (1, 1) is the + upper-right corner of the plot. + - ``position_type="plotcoords"``: *position* is given as (x, y) in plot + coordinates, i.e., the distances in inches, centimeters, or points from the + lower left plot origin. + - ``position_type="inside"``: *position* is given as a two-character + justification code, meaning the anchor point of the rose is inside the plot + bounding box. + - ``position_type="outside"``: *position* is given as a two-character + justification code, but the rose is outside the plot bounding box. + width + Width of the rose in plot coordinates (append **i** (inch), + **cm** (centimeters), or **p** (points)), or append % for a size in percentage + of map width [Default is 10 %]. + label + A sequence of four strings to label the cardinal points W,E,S,N. Use an empty + string to skip a specific label. If set to ``True``, use the default labels + ``["W", "E", "S", "N"]``. + fancy + Get a fancy rose. The fanciness level can be set to 1, 2, or 3: + + - Level 1 draws the two principal E-W, N-S orientations + - Level 2 adds the two intermediate NW-SE and NE-SW orientations + - Level 3 adds the four minor orientations WNW-ESE, NNW-SSE, NNE-SSW, and + ENE-WSW + + If set to ``True``, it defaults to level 1. + anchor_offset + *offset* or (*offset_x*, *offset_y*). + Offset the anchor point by *offset_x* and *offset_y*. If a single value *offset* + is given, *offset_y* = *offset_x* = *offset*. + justify + Set the anchor point. Specify a two-character (order independent) code. Choose + from vertical **T**\(op), **M**\(iddle), or **B**\(ottom) and horizontal + **L**\(eft), **C**\(entre), or **R**\(ight). + + Examples + -------- + >>> import pygmt + >>> fig = pygmt.Figure() + >>> fig.basemap(region=[0, 80, -30, 30], projection="M10c", frame=True) + >>> fig.directional_rose(position=(10, 10), position_type="mapcoords") + >>> fig.show() + """ + self._activate_figure() + + aliasdict = AliasSystem( + F=Alias(box, name="box"), + Td=[ + Alias( + position_type, + name="position_type", + mapping={ + "mapcoords": "g", + "boxcoords": "n", + "plotcoords": "x", + "inside": "j", + "outside": "J", + }, + ), + Alias(position, name="position", sep="/", size=2), + Alias(width, name="width", prefix="+w"), + Alias(fancy, name="fancy", prefix="+f"), + Alias(justify, name="justify", prefix="+j"), + Alias(label, name="label", prefix="+l", sep=",", size=4), + Alias(anchor_offset, name="anchor_offset", prefix="+o", sep="/", size=2), + ], + V=Alias(verbose, name="verbose"), + p=Alias(perspective, name="perspective"), + t=Alias(transparency, name="transparency"), + ) + + with Session() as lib: + lib.call_module(module="basemap", args=build_arg_list(aliasdict))