pygmt.Figure.magnetic_rose

Figure.magnetic_rose(position=None, width=None, labels=False, outer_pen=False, inner_pen=False, declination=None, declination_label=None, intervals=None, box=False, verbose=False, panel=False, perspective=False, transparency=None)

Add a magnetic rose to the map.

Parameters:

  • position (Position | Sequence[float | str] | Literal['TL', 'TC', 'TR', 'ML', 'MC', 'MR', 'BL', 'BC', 'BR'] | None, default: None) –

    Position of the magnetic rose on the plot. It can be specified in multiple ways:

    • A pygmt.params.Position object to fully control the reference point, anchor point, and offset.

    • A sequence of two values representing the x- and y-coordinates in plot coordinates, e.g., (1, 2) or ("1c", "2c").

    • A 2-character justification code for a position inside the plot, e.g., "TL" for Top Left corner inside the plot.

    If not specified, defaults to the Bottom Left corner of the plot (position (0, 0) with anchor "BL").

  • width (float | str | None, default: None) – Width of the rose in plot coordinates, or append unit % for a size in percentage of plot width [Default is 15%].

  • labels (Sequence[str] | bool, default: False) – A sequence of four strings to label the cardinal points W, E, S, N. Use an empty string to skip a specific label. If the north label is "*", then a north star is plotted instead of the north label. If set to True, use the default labels ["W", "E", "S", "N"].

  • outer_pen (str | bool, default: False) – Draw the outer circle of the magnetic rose, using the given pen attributes.

  • inner_pen (str | bool, default: False) – Draw the inner circle of the magnetic rose, using the given pen attributes.

  • declination (float | None, default: None) – Magnetic declination in degrees. By default, only a geographic north is plotted. With this parameter set, a magnetic north is also plotted. A magnetic compass needle is drawn inside the rose to indicate the direction to magnetic north.

  • declination_label (str | None, default: None) – Label for the magnetic compass needle. Default is to format a label based on declination. To bypass the label, set to "-".

  • intervals (Sequence[float] | None, default: None) – Specify the annotation and tick intervals for the geographic and magnetic directions. It can be a sequence of three or six values. If three values are given, they are used for both geographic and magnetic directions. If six values are given, the first three are used for geographic directions and the last three for magnetic directions. [Default is (30, 5, 1)]. Note: If MAP_EMBELLISHMENT_MODE is "auto" and the compass size is smaller than 2.5 cm then the interval defaults are reset to (90,30, 3, 45, 15, 3).

  • box (Box | bool, default: False) – Draw a background box behind the magnetic rose. If set to True, a simple rectangular box is drawn using MAP_FRAME_PEN. To customize the box appearance, pass a pygmt.params.Box object to control style, fill, pen, and other box properties.

  • perspective (str | bool, default: False) –

    Select perspective view and set the azimuth and elevation of the viewpoint.

    Accepts a single value or a sequence of two or three values: azimuth, (azimuth, elevation), or (azimuth, elevation, zlevel).

    • azimuth: Azimuth angle of the viewpoint in degrees [Default is 180, i.e., looking from south to north].

    • elevation: Elevation angle of the viewpoint above the horizon [Default is 90, i.e., looking straight down at nadir].

    • zlevel: Z-level at which 2-D elements (e.g., the map frame) are drawn. Only applied when used together with zsize or zscale. [Default is at the bottom of the z-axis].

    Alternatively, set perspective=True to reuse the perspective setting from the previous plotting method, or pass a string following the full GMT syntax for finer control (e.g., adding +w or +v modifiers to select an axis location other than the plot origin). See https://docs.generic-mapping-tools.org/6.6/gmt.html#perspective-full for details.

  • verbose (bool or str) – Select verbosity level [Full usage].

  • transparency (float) – Set transparency level, in [0-100] percent range [Default is 0, i.e., opaque]. Only visible when PDF or raster format output is selected. Only the PNG format selection adds a transparency layer in the image (for further processing).

Examples

>>> import pygmt
>>> from pygmt.params import Position
>>> fig = pygmt.Figure()
>>> fig.basemap(region=[-10, 10, -10, 10], projection="M15c", frame=True)
>>> fig.magnetic_rose(
...     position=Position((-5, -5), cstype="mapcoords"),
...     width="4c",
...     labels=["W", "E", "S", "*"],
...     intervals=(45, 15, 3, 60, 20, 4),
...     outer_pen="1p,red",
...     inner_pen="1p,blue",
...     declination=11.5,
...     declination_label="11.5°E",
... )
>>> fig.show()