polartoolkit.maps

polartoolkit.maps#

Attributes#

`display`
`gv`
`crs`
`ipyleaflet`
`ipywidgets`

Classes#

Figure

A simple class that inherits from a pygmt Figure instance and stores additional

Functions#

`add_coast`(fig[, hemisphere, region, projection, ...])	deprecated function, use class method add_coast instead
`add_gridlines`(fig[, region, projection, x_spacing, ...])	deprecated function, use class method add_gridlines instead
`add_faults`(fig[, region, projection, fault_activity, ...])	deprecated function, use class method add_faults instead
`add_imagery`(fig[, hemisphere, transparency])	deprecated function, use class method add_imagery instead
`add_modis`(fig[, hemisphere, version, transparency, cmap])	deprecated function, use class method add_modis instead
`add_simple_basemap`(fig[, hemisphere, version, ...])	deprecated function, use class method add_simple_basemap instead
`add_inset`(fig[, hemisphere, region, inset_position, ...])	deprecated function, use class method add_inset instead
`add_scalebar`(fig[, region, projection])	deprecated function, use class method add_scalebar instead
`add_north_arrow`(fig, **kwargs)	deprecated function, use class method add_north_arrow instead
`add_box`(fig, box[, pen, verbose])	deprecated function, use class method add_box instead
`add_colorbar`(fig[, hist, cpt_lims, cbar_frame, verbose])	deprecated function, use class method add_colorbar instead
`basemap`([region, hemisphere, coast, north_arrow, ...])	Create a figure basemap in polar stereographic projection, and add a range of
`set_cmap`(cmap[, grid, points, modis, grd2cpt, ...])	Function used to set the PyGMT colormap for a figure.
`plot_grd`(grid[, region, hemisphere, cmap, coast, ...])	Plot a grid (either a filename or a load dataarray) with PyGMT in a polar
`interactive_map`([hemisphere, center_yx, zoom, ...])	Plot an interactive map with satellite imagery. Clicking gives the cursor location
`subplots`(grids[, hemisphere, region, dims, fig_title, ...])	Plot a series of grids as individual suplots. This will automatically configure the
`plot_3d`(grids, cmaps, exaggeration[, drapegrids, ...])	create a 3D perspective plot of a list of grids
`interactive_data`([hemisphere, coast, grid, grid_cmap, ...])	plot points or grids on an interactive map using GeoViews
`geoviews_points`(points[, points_z, points_color, ...])	Add points to a geoviews map instance.

Module Contents#

display = None[source]#

gv = None[source]#

crs = None[source]#

ipyleaflet = None[source]#

ipywidgets = None[source]#

class Figure(fig=None, reg=None, hemisphere=None, height=None, width=None)[source]#

Bases: pygmt.Figure

A simple class that inherits from a pygmt Figure instance and stores additional figure parameters for easy access and provides addition methods.

Parameters:

fig (pygmt.Figure | None)
reg (tuple[float, float, float, float] | None)
hemisphere (str | None)
height (float | None)
width (float | None)

reg = None[source]#

hemisphere: str = None[source]#

reg_latlon[source]#

origin_shift: str | None = None[source]#

shift_figure(origin_shift=None, yshift_amount=-1, xshift_amount=1, xshift_extra=0.4, yshift_extra=0.4)[source]#

Determine if and how much to shift origin of figure

Parameters:

origin_shift (str | None)
yshift_amount (float)
xshift_amount (float)
xshift_extra (float)
yshift_extra (float)

Return type:

None

add_imagery(transparency=0)[source]#

Add satellite imagery to a figure. For southern hemisphere uses LIMA imagery, but for northern hemisphere uses MODIS imagery.

Parameters:: transparency (int, optional) – transparency of the imagery, by default 0
Return type:: None

add_coast(no_coast=False, pen=None, version=None, label=None)[source]#

add coastline and or groundingline to figure.

Parameters:

no_coast (bool) – If True, only plot groundingline, not coastline, by default is False
pen (None) – GMT pen string, by default “0.6p,black”
version (str, optional) – version of groundingline to plot, by default is ‘BAS’ for north hemisphere and ‘measures-v2’ for south hemisphere
label (str, optional) – label to add to the legend, by default is None

Return type:

None

add_gridlines(x_spacing=None, y_spacing=None, annotation_offset='20p')[source]#

add lat lon grid lines and annotations to a figure. Use kwargs x_spacing and y_spacing to customize the interval of gridlines and annotations.

Parameters:

x_spacing (float, optional) – spacing for x gridlines in degrees, by default is None
y_spacing (float, optional) – spacing for y gridlines in degrees, by default is None
annotation_offset (str, optional) – offset for gridline annotations, by default “20p”

Return type:

None

add_faults(fault_activity=None, fault_motion=None, fault_exposure=None, pen=None, style=None, label=None)[source]#

add various types of faults from GeoMap to a map, from Cox et al.[1] and Cox et al.[2]

Parameters:

fault_activity (str, optional) – type of fault activity, options are active or inactive, by default both
fault_motion (str, optional) – type of fault motion, options are sinistral, dextral, normal, or reverse, by default all
fault_exposure (str, optional) – type of fault exposure, options are exposed or inferred, by default both
pen (str, optional) – GMT pen string, by default “1p,magenta,-”
style (str, optional) – GMT style string, by default None
label (str, optional) – label to add to the legend, by default None

Return type:

None

add_modis(version=None, transparency=0, cmap='grayC')[source]#

Add MODIS imagery to a figure.

Parameters:

version (str | None, optional) – which version (resolution) of MODIS imagery to use, by default “750m” for southern hemisphere and “500m” for northern hemisphere.
transparency (int, optional) – transparency of the MODIS imagery, by default 0
cmap (str, optional) – colormap to use for MODIS imagery, by default “grayC”

Return type:

None

add_simple_basemap(version=None, transparency=0, pen='0.2p,black', grounded_color='grey', floating_color='skyblue')[source]#

Add a simple basemap to a figure with grounded ice shown as grey and floating ice as blue.

Parameters:

version (str | None, optional) – which version of shapefiles to use for grounding line / coastline, by default “measures-v2” for southern hemisphere and “BAS” for northern hemisphere
transparency (int, optional) – transparency of all the plotted elements, by default 0
pen (str, optional) – GMT pen string for the coastline, by default “0.2p,black”
grounded_color (str, optional) – color for the grounded ice, by default “grey”
floating_color (str, optional) – color for the floating ice, by default “skyblue”

Return type:

None

add_box(box, pen='2p,black', verbose='w')[source]#

Plot a GMT region as a box.

Parameters:

box (tuple[float, float, float, float]) – region in EPSG3031 in format [xmin, xmax, ymin, ymax] in meters
pen (str, optional) – GMT pen string used for the box, by default “2p,black”
verbose (str, optional) – verbosity level for pygmt, by default “w” for warnings

Return type:

None

add_inset(inset_position='jTL+jTL+o0/0', inset_width=0.25, inset_reg=None, **kwargs)[source]#

add an inset map showing the figure region relative to the Antarctic continent.

Parameters:

inset_position (str, optional) – GMT location string for inset map, by default ‘jTL+jTL+o0/0’ (top left)
inset_width (float, optional) – Inset width as percentage of the smallest figure dimension, by default is 25% (0.25)
inset_reg (tuple[float, float, float, float], optional) – Region of Antarctica/Greenland to plot for the inset map, by default is whole area
kwargs (Any)

Return type:

None

add_scalebar(**kwargs)[source]#

add a scalebar to a figure.

Parameters:: kwargs (Any)
Return type:: None

add_north_arrow(**kwargs)[source]#

add a north arrow to a figure

Parameters:: kwargs (Any)
Return type:: None

add_grid(grid, cmap='viridis', shading=False, nan_transparent=True, colorbar=True, **kwargs)[source]#

Add a grid to the figure.

Parameters:

grid (str or xr.DataArray) – Path to the grid file or an xarray DataArray containing the grid data.
cmap (str or bool, optional) – Colormap to use for the grid, by default “viridis”. If True, last used colormap will be used.
shading (bool or str, optional) – If True, apply shading to the grid. If a string, it will be passed to pygmt.grdshade as the shading argument. By default, False (no shading).
nan_transparent (bool, optional) – If True, set NaN values to be transparent in the grid image. Default is True unless shading is False, in which case it is set to False.
colorbar (bool, optional) – If True, add a colorbar to the figure. Default is True.
**kwargs (Any) – Additional keyword arguments to pass

Return type:

None

add_points(points, cmap='viridis', fill='black', style='c.2c', pen=None, label=None, colorbar=True, **kwargs)[source]#

Add points to the figure.

Parameters:

points (pd.DataFrame or gpd.GeoDataFrame) – DataFrame containing point data with columns ‘x’ and ‘y’ or ‘easting’ and ‘northing’.
cmap (str or bool, optional) – Colormap to use for the points, by default “viridis”. If True, last used colormap will be used.
**kwargs (Any) – Additional keyword arguments.
fill (str)
style (str)
pen (str | None)
label (str | None)
colorbar (bool)
**kwargs

Return type:

None

add_colorbar(hist=False, cpt_lims=None, cbar_frame=None, verbose='w', **kwargs)[source]#

Add a colorbar based on the last cmap used by PyGMT and optionally a histogram of the data values.

Parameters:

hist (bool, optional) – choose whether to add a colorbar histogram, by default False
cpt_lims (tuple[float, float], optional) – cpt lims to use for the colorbar histogram, must match those used to create the colormap. If not supplied, will attempt to get values from kwargs grid, by default None
cbar_frame (list[str] | str, optional) – frame for the colorbar, by default None
verbose (str, optional) – verbosity level for pygmt, by default “w” for warnings
**kwargs (Any) – additional keyword arguments to pass

Return type:

None

add_coast(fig, hemisphere=None, region=None, projection=None, no_coast=False, pen=None, version=None, label=None)[source]#

deprecated function, use class method add_coast instead

Parameters:

fig (pygmt.Figure)
hemisphere (str | None)
region (tuple[float, float, float, float] | None)
projection (str | None)
no_coast (bool)
pen (str | None)
version (str | None)
label (str | None)

Return type:

None

add_gridlines(fig, region=None, projection=None, x_spacing=None, y_spacing=None, annotation_offset='20p')[source]#

deprecated function, use class method add_gridlines instead

Parameters:

fig (pygmt.Figure)
region (tuple[float, float, float, float] | None)
projection (str | None)
x_spacing (float | None)
y_spacing (float | None)
annotation_offset (str)

Return type:

None

add_faults(fig, region=None, projection=None, fault_activity=None, fault_motion=None, fault_exposure=None, pen=None, style=None, label=None)[source]#

deprecated function, use class method add_faults instead

Parameters:

fig (pygmt.Figure)
region (tuple[float, float, float, float] | None)
projection (str | None)
fault_activity (str | None)
fault_motion (str | None)
fault_exposure (str | None)
pen (str | None)
style (str | None)
label (str | None)

Return type:

None

add_imagery(fig, hemisphere=None, transparency=0)[source]#

deprecated function, use class method add_imagery instead

Parameters:

fig (pygmt.Figure)
hemisphere (str | None)
transparency (int)

Return type:

None

add_modis(fig, hemisphere=None, version=None, transparency=0, cmap='grayC')[source]#

deprecated function, use class method add_modis instead

Parameters:

fig (pygmt.Figure)
hemisphere (str | None)
version (str | None)
transparency (int)
cmap (str)

Return type:

None

add_simple_basemap(fig, hemisphere=None, version=None, transparency=0, pen='0.2p,black', grounded_color='grey', floating_color='skyblue')[source]#

deprecated function, use class method add_simple_basemap instead

Parameters:

fig (pygmt.Figure)
hemisphere (str | None)
version (str | None)
transparency (int)
pen (str)
grounded_color (str)
floating_color (str)

Return type:

None

add_inset(fig, hemisphere=None, region=None, inset_position='jTL+jTL+o0/0', inset_width=0.25, inset_reg=None, **kwargs)[source]#

deprecated function, use class method add_inset instead

Parameters:

fig (pygmt.Figure)
hemisphere (str | None)
region (tuple[float, float, float, float] | None)
inset_position (str)
inset_width (float)
inset_reg (tuple[float, float, float, float] | None)
kwargs (Any)

Return type:

None

add_scalebar(fig, region=None, projection=None, **kwargs)[source]#

deprecated function, use class method add_scalebar instead

Parameters:

fig (pygmt.Figure)
region (tuple[float, float, float, float] | None)
projection (str | None)
kwargs (Any)

Return type:

None

add_north_arrow(fig, **kwargs)[source]#

deprecated function, use class method add_north_arrow instead

Parameters:

fig (pygmt.Figure)
kwargs (Any)

Return type:

None

add_box(fig, box, pen='2p,black', verbose='w')[source]#

deprecated function, use class method add_box instead

Parameters:

fig (pygmt.Figure)
box (tuple[float, float, float, float])
pen (str)
verbose (str)

Return type:

None

add_colorbar(fig, hist=False, cpt_lims=None, cbar_frame=None, verbose='w', **kwargs)[source]#

deprecated function, use class method add_colorbar instead

Parameters:

fig (pygmt.Figure)
hist (bool)
cpt_lims (tuple[float, float] | None)
cbar_frame (list[str] | str | None)
verbose (str)
kwargs (Any)

Return type:

None

basemap(region=None, hemisphere=None, coast=False, north_arrow=False, scalebar=False, faults=False, simple_basemap=False, imagery_basemap=False, modis_basemap=False, title=None, inset=False, points=None, gridlines=False, origin_shift=None, fig=None, **kwargs)[source]#

Create a figure basemap in polar stereographic projection, and add a range of features such as coastline and grounding lines, inset figure location maps, background imagery, scalebars, gridlines and northarrows. Plot supplied points with either constant color or colored by a colormap. Reuse the figure instance to either plot additional features on top, or shift the plot to create subplots. There are many keyword arguments which can either be passed along to the various functions in the maps module, or specified specifically. Kwargs can be passed directly to the following functions: add_colorbar, add_north_arrow, add_scalebar, add_inset, set_cmap. Other kwargs are specified below.

Parameters:

region (tuple[float, float, float, float] | None, optional) – region for the figure in format [xmin, xmax, ymin, ymax], by default None
hemisphere (str, optional) – set whether to plot in “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031), can be set manually, or will read from the environment variable: “POLARTOOLKIT_HEMISPHERE”
coast (bool, optional) – choose whether to plot coastline and grounding line, by default False. Version of shapefiles to plots depends on hemisphere, and can be changed with kwargs coast_version, which defaults to BAS for the northern hemisphere and measures-v2 for the southern.
north_arrow (bool, optional) – choose to add a north arrow to the plot, by default is False.
scalebar (bool, optional) – choose to add a scalebar to the plot, by default is False. See add_scalebar for additional kwargs
faults (bool, optional) – choose to plot faults on the map, by default is False
simple_basemap (bool, optional) – choose to plot a simple basemap with floating ice colored blue and grounded ice colored grey, with boarders defined by simple_basemap_version.
simple_basemap_transparency (int, optional) – transparency to use for the simple basemap, by default is 0
simple_basemap_version (str, optional) – version of the simple basemap to plot, by default is None
imagery_basemap (bool, optional) – choose to add a background imagery basemap, by default is False. If true, will use LIMA for southern hemisphere and MODIS MoG for the northern hemisphere.
imagery_transparency (int, optional) – transparency to use for the imagery basemap, by default is 0
modis_basemap (bool, optional) – choose to add a MODIS background imagery basemap, by default is False.
modis_transparency (int, optional) – transparency to use for the MODIS basemap, by default is 0
modis_version (str, optional) – version of the MODIS basemap to plot, by default is None
title (str | None, optional) – title to add to the figure, by default is None
inset (bool, optional) – choose to plot inset map showing figure location, by default is False
points (pandas.DataFrame | None, optional) – points to plot on map, must contain columns ‘x’ and ‘y’ or ‘easting’ and ‘northing’.
gridlines (bool, optional) – choose to plot lat/lon grid lines, by default is False
origin_shift (str, | None, optional) – choose what to do with the plot when creating the figure. By default is ‘initialize’ which will create a new figure instance. To plot additional grids on top of the existing figure provide a figure instance to fig and set origin_shift to None. To create subplots, provide the existing figure instance to fig, and set origin_shift to ‘x’ to add the the new plot to the right of previous plot, ‘y’ to add the new plot above the previous plot, or ‘both’ to add the new plot to the right and above the old plot. By default each of this shifts will be the width/height of the figure instance, this can be changed with kwargs xshift_amount and yshift_amount, which are in multiples of figure width/height.
fig (pygmt.Figure, optional) – supply a figure instance for adding subplots or using other PyGMT plotting methods, by default None
fig_height (int or float) – height in cm for figures, by default is 15cm.
fig_width (int or float) – width in cm for figures, by default is None and is determined by fig_height and the projection.
xshift_amount (int or float) – amount to shift the origin in the x direction in multiples of current figure instance width, by default is 1.
yshift_amount (int or float) – amount to shift the origin in the y direction in multiples of current figure instance height, by default is -1.
frame (str | bool) – GMT frame string to use for the basemap, by default is “nesw+gwhite”
frame_pen (str) – GMT pen string to use for the frame, by default is “auto”
frame_font (str) – GMT font string to use for the frame, by default is “auto”
transparency (int) – transparency to use for the basemap, by default is 0
inset_position (str) – position for inset map with PyGMT syntax, by default is “jTL+jTL+o0/0”
title_font (str) – font to use for the title, by default is ‘auto’
show_region (tuple[float, float, float, float]) – show a rectangular region on the map, in the format [xmin, xmax, ymin, ymax].
region_pen (str) – GMT pen string to use for the region box, by default is None
x_spacing (float) – spacing for x gridlines in degrees, by default is None
y_spacing (float) – spacing for y gridlines in degrees, by default is None
points_style (str) – style of points to plot in GMT format, by default is ‘c.2c’.
points_fill (str) – fill color of points, either string of color name or column name to color points by, by default is ‘black’.
points_pen (str) – pen color and width of points, by default is ‘1p,black’ if constant color or None if using a cmap.
points_label (str) – label to add to legend, by default is None
points_cmap (str) – GMT color scale to use for coloring points, by default ‘viridis’. If True, will use the last used in PyGMT.
cpt_lims (str or tuple]) – limits to use for color scale max and min, by default is max and min of data.
cmap_region (str or tuple[float, float, float, float]) – region to use to define color scale limits, in format [xmin, xmax, ymin, ymax], by default is region
robust (bool) – use the 2nd and 98th percentile (or those specified with ‘robust_percentiles’) of the data to set color scale limits, by default is False.
robust_percentiles (tuple[float, float]) – percentiles to use for robust colormap limits, by default is (0.02, 0.98).
reverse_cpt (bool) – reverse the color scale, by default is False.
cbar_label (str) – label to add to colorbar.
colorbar (bool) – choose to add a colorbar for the points to the plot, by default is False.
scalebar_font_color (str) – color of the scalebar font, by default is ‘black’.
scale_font_color (str) – deprecated, use scalebar_font_color.
scalebar_length_perc (float) – percentage of the min dimension of the figure region to use for the scalebar, by default is 0.25.
scale_length_perc (float) – deprecated, use scalebar_length_perc.
scalebar_position (str) – position of the scalebar on the figure, by default is ‘n.5/.05’ which is bottom center of the plot.
scale_position (str) – deprecated, use scalebar_position.
coast_pen (str) – GMT pen string to use for the coastlines, by default is None
no_coast (bool) – choose to not plot coastlines, just grounding lines, by default is False
coast_version (str) – version of coastlines to plot, by default depends on the hemisphere
coast_label (str) – label to add to coastlines, by default is None
fault_label (str) – label to add to faults, by default is None
fault_pen (str) – GMT pen string to use for the faults, by default is None
fault_style (str) – GMT style string to use for the faults, by default is None
fault_activity (str) – column name in faults to use for activity, by default is None
fault_motion (str) – column name in faults to use for motion, by default is None
fault_exposure (str) – column name in faults to use for exposure, by default is None
kwargs (Any)

Returns:

Returns a figure object, which can be passed to the fig kwarg to add subplots or other PyGMT plotting methods.

Return type:

pygmt.Figure

Example

>>> from polartoolkit import maps, regions
...
>>> fig = maps.basemap(region=regions.ross_ice_shelf)
...
>>> fig.show()

set_cmap(cmap, grid=None, points=None, modis=False, grd2cpt=False, cpt_lims=None, cmap_region=None, robust=False, robust_percentiles=(0.02, 0.98), absolute=False, reverse_cpt=False, shp_mask=None, hemisphere=None, colorbar=True, **kwargs)[source]#

Function used to set the PyGMT colormap for a figure.

Parameters:

cmap (str | bool) – a string of either a PyGMT cpt file (.cpt), or a preset PyGMT color ramp, or alternatively a value of True will use the last used cmap.
grid (str | xarray.DataArray | None, optional) – grid used to determine colormap limits and grd2cpt colormap equalization, by default None
points (pandas.Series | numpy.ndarray | None, optional) – point values to use to determine colormap limits, by default None
modis (bool, optional) – choose appropriate cmap for plotting modis data, by default False
grd2cpt (bool, optional) – equalized the colormap to the grid data values, by default False
cpt_lims (tuple[float, float] | None, optional) – limits to set for the colormap, by default None
cmap_region (tuple[float, float, float, float] | None, optional) – extract colormap limits from a subset of the grid or points, in format [xmin, xmax, ymin, ymax], by default None
robust (bool, optional) – use the 2nd and 98th percentile of the data from the grid or points, by default False
robust_percentiles (tuple[float, float], optional) – percentiles to use for robust colormap limits, by default (0.02, 0.98)
absolute (bool, optional) – use the absolute value of the data from the grid or points, by default False
reverse_cpt (bool, optional) – change the direction of the cmap, by default False
shp_mask (geopandas.GeoDataFrame | str | None, optional) – a shapefile to mask the grid or points by before extracting limits, by default None
hemisphere (str | None, optional) – “north” or “south” hemisphere needed for using shp_mask, by default None
colorbar (bool, optional) – tell subsequent plotting functions whether to add a colorbar, by default True
kwargs (Any)

Returns:

a tuple with the pygmt colormap, as a string or boolean, a boolean of whether to plot the colorbar, and a tuple of 2 floats with the cpt limits.

Return type:

tuple[str | bool, bool, tuple[float,float] | None]

plot_grd(grid, region=None, hemisphere=None, cmap='viridis', coast=False, north_arrow=False, scalebar=False, faults=False, simple_basemap=False, imagery_basemap=False, modis_basemap=False, title=None, inset=False, points=None, gridlines=False, origin_shift='initialize', fig=None, **kwargs)[source]#

Plot a grid (either a filename or a load dataarray) with PyGMT in a polar stereographic projection, and add a range of features such as coastline and grounding lines, inset figure location maps, background imagery, colorbar histogram, scalebars, gridlines and northarrows. Reuse the figure instance to either plot additional features on top, or shift the plot to create subplots. There are many keyword arguments which can either be passed along to the various functions in the maps module, or specified specifically. Kwargs can be passed directly to the following functions: add_colorbar, add_north_arrow, add_scalebar, add_inset, set_cmap. Other kwargs are specified below.

Parameters:

grid (str or xarray.DataArray) – grid file to plot, either loaded xarray.DataArray or string of the path to a gridded data file, such as a netCDF, geotiff or zarr file.
region (tuple[float, float, float, float], optional) – region for the figure in format [xmin, xmax, ymin, ymax], by default is the extent of the input grid. If provided, the grid will be cut to this region before plotting.
hemisphere (str, optional) – set whether to plot in “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031), can be set manually, or will read from the environment variable: “POLARTOOLKIT_HEMISPHERE”
cmap (str or bool, optional) – GMT color scale to use, by default ‘viridis’. If True, will use the last use cmap from PyGMT. See available options at https://docs.generic-mapping-tools.org/6.2/cookbook/cpts.html.
coast (bool, optional) – choose whether to plot coastline and grounding line, by default False. Version of shapefiles to plots depends on hemisphere, and can be changed with kwargs coast_version, which defaults to BAS for the northern hemisphere and measures-v2 for the southern.
north_arrow (bool, optional) – choose to add a north arrow to the plot, by default is False.
scalebar (bool, optional) – choose to add a scalebar to the plot, by default is False. See add_scalebar for additional kwargs
faults (bool, optional) – choose to plot faults on the map, by default is False
simple_basemap (bool, optional) – choose to plot a simple basemap with floating ice colored blue and grounded ice colored grey.
simple_basemap_transparency (int, optional) – transparency to use for the simple basemap, by default is 0
simple_basemap_version (str, optional) – version of the simple basemap to plot, by default is None
imagery_basemap (bool, optional) – choose to add a background imagery basemap, by default is False. If true, will use LIMA for southern hemisphere and MODIS MoG for the northern hemisphere.
imagery_transparency (int, optional) – transparency to use for the imagery basemap, by default is 0
modis_basemap (bool, optional) – choose to add a MODIS background imagery basemap, by default is False.
modis_transparency (int, optional) – transparency to use for the MODIS basemap, by default is 0
modis_version (str, optional) – version of the MODIS basemap to plot, by default is None
title (str | None, optional) – title to add to the figure, by default is None
inset (bool, optional) – choose to plot inset map showing figure location, by default is False
points (pandas.DataFrame | None, optional) – points to plot on map, must contain columns ‘x’ and ‘y’ or ‘easting’ and ‘northing’.
gridlines (bool, optional) – choose to plot lat/lon grid lines, by default is False
origin_shift (str, | None, optional) – choose what to do with the plot when creating the figure. By default is ‘initialize’ which will create a new figure instance. To plot additional grids on top of the existing figure provide a figure instance to fig and set origin_shift to None. To create subplots, provide the existing figure instance to fig, and set origin_shift to ‘x’ to add the the new plot to the right of previous plot, ‘y’ to add the new plot above the previous plot, or ‘both’ to add the new plot to the right and above the old plot. By default each of this shifts will be the width/height of the figure instance, this can be changed with kwargs xshift_amount and yshift_amount, which are in multiples of figure width/height.
fig (pygmt.Figure, optional) – supply a figure instance for adding subplots or using other PyGMT plotting methods, by default None
fig_height (int or float) – height in cm for figures, by default is 15cm.
fig_width (int or float) – width in cm for figures, by default is None and is determined by fig_height and the projection.
xshift_amount (int or float) – amount to shift the origin in the x direction in multiples of current figure instance width, by default is 1.
yshift_amount (int or float) – amount to shift the origin in the y direction in multiples of current figure instance height, by default is -1.
frame (str | bool) – GMT frame string to use for the basemap, by default is “nesw+gwhite”
frame_pen (str) – GMT pen string to use for the frame, by default is “auto”
frame_font (str) – GMT font string to use for the frame, by default is “auto”
transparency (int) – transparency to use for the basemap, by default is 0
modis (bool) – set to True if plotting MODIS data to use a nice colorscale.
grd2cpt (bool) – use GMT module grd2cpt to set color scale from grid values, by default is False
cpt_lims (str or tuple]) – limits to use for color scale max and min, by default is max and min of data.
cmap_region (str or tuple[float, float, float, float]) – region to use to define color scale limits, in format [xmin, xmax, ymin, ymax], by default is region
robust (bool) – use the 2nd and 98th percentile (or those specified with ‘robust_percentiles’) of the data to set color scale limits, by default is False.
robust_percentiles (tuple[float, float]) – percentiles to use for robust colormap limits, by default is (0.02, 0.98).
reverse_cpt (bool) – reverse the color scale, by default is False.
shp_mask (geopandas.GeoDataFrame | str) – shapefile to use to mask the grid before extracting limits, by default is None.
colorbar (bool) – choose to add a colorbar to the plot, by default is True.
cbar_label (str) – label to add to colorbar.
shading (str) – GMT shading string to use for the basemap, by default is None
grid_transparency (int) – transparency of the grid, by default is 0
inset_position (str) – position for inset map with PyGMT syntax, by default is “jTL+jTL+o0/0”
title_font (str) – font to use for the title, by default is ‘auto’
show_region (tuple[float, float, float, float]) – show a rectangular region on the map, in the format [xmin, xmax, ymin, ymax].
region_pen (str) – GMT pen string to use for the region box, by default is None
x_spacing (float) – spacing for x gridlines in degrees, by default is None
y_spacing (float) – spacing for y gridlines in degrees, by default is None
points_style (str) – style of points to plot in GMT format, by default is ‘c.2c’.
points_fill (str) – fill color of points, either string of color name or column name to color points by, by default is ‘black’.
points_pen (str) – pen color and width of points, by default is ‘1p,black’ if constant color or None if using a cmap.
points_label (str) – label to add to legend, by default is None
points_cmap (str) – colormap to use for points, by default is None.
scalebar_font_color (str) – color of the scalebar font, by default is ‘black’.
scale_font_color (str) – deprecated, use scalebar_font_color.
scalebar_length_perc (float) – percentage of the min dimension of the figure region to use for the scalebar, by default is 0.25.
scale_length_perc (float) – deprecated, use scalebar_length_perc.
scalebar_position (str) – position of the scalebar on the figure, by default is ‘n.5/.05’ which is bottom center of the plot.
scale_position (str) – deprecated, use scalebar_position.
coast_pen (str) – GMT pen string to use for the coastlines, by default is None
no_coast (bool) – choose to not plot coastlines, just grounding lines, by default is False
coast_version (str) – version of coastlines to plot, by default depends on the hemisphere
coast_label (str) – label to add to coastlines, by default is None
fault_label (str) – label to add to faults, by default is None
fault_pen (str) – GMT pen string to use for the faults, by default is None
fault_style (str) – GMT style string to use for the faults, by default is None
fault_activity (str) – column name in faults to use for activity, by default is None
fault_motion (str) – column name in faults to use for motion, by default is None
fault_exposure (str) – column name in faults to use for exposure, by default is None
kwargs (Any)

Returns:

Returns a figure object, which can be passed to the fig kwarg to add subplots or other PyGMT plotting methods.

Return type:

pygmt.Figure

Example

>>> from polartoolkit import maps
...
>>> fig = maps.plot_grd('grid1.nc')
>>> fig = maps.plot_grd(
... 'grid2.nc',
... origin_shift = 'x',
... fig = fig,
... )
...
>>> fig.show()

interactive_map(hemisphere=None, center_yx=None, zoom=None, display_xy=True, points=None, basemap_type=None, **kwargs)[source]#

Plot an interactive map with satellite imagery. Clicking gives the cursor location in a Polar Stereographic projection [x,y]. Requires ipyleaflet

Parameters:

hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres
center_yx (tuple, optional) – choose center coordinates in EPSG3031 [y,x], by default [0,0]
zoom (float, optional) – choose zoom level, by default None
display_xy (bool, optional) – choose if you want clicks to show the xy location, by default True
show (bool, optional) – choose whether to display the map, by default True
points (pandas.DataFrame, optional) – choose to plot points supplied as columns ‘x’, ‘y’, or ‘easting’, ‘northing’, in EPSG:3031 in a dataframe
basemap_type (str, optional) – choose what basemap to plot, options are ‘BlueMarble’, ‘Imagery’, ‘Basemap’, and “IceVelocity”, by default ‘BlueMarble’ for northern hemisphere and ‘Imagery’ for southern hemisphere.
kwargs (Any)

Returns:

interactive map

Return type:

Any

subplots(grids, hemisphere=None, region=None, dims=None, fig_title=None, fig_x_axis_title=None, fig_y_axis_title=None, fig_title_font='30p,Helvetica-Bold', subplot_labels=True, subplot_labels_loc='TL', row_titles=None, column_titles=None, **kwargs)[source]#

Plot a series of grids as individual suplots. This will automatically configure the layout to be closest to a square. Add any parameters from plot_grd() here as keyword arguments for further customization.

Parameters:

grids (list) – list of xarray.DataArray’s to be plotted
hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres, by default None
region (tuple[float, float, float, float], optional) – choose to subset the grids to a specified region, in format [xmin, xmax, ymin, ymax], by default None
dims (tuple, optional) – customize the subplot dimensions (# rows, # columns), by default will use utils.square_subplots() to make a square(~ish) layout.
fig_title (str, optional) – add a title to the figure, by default None
fig_x_axis_title (str, optional) – add a title to the x axis of the figure, by default None
fig_y_axis_title (str, optional) – add a title to the y axis of the figure, by default None
fig_title_font (str, optional) – font for the figure title, by default “30p,Helvetica-Bold”
subplot_labels (bool, optional) – add subplot labels (a, b, c …), by default True
subplot_labels_loc (str, optional) – location of subplot labels, by default “TL”
row_titles (list, optional) – add titles to the left of each row, by default None
column_titles (list, optional) – add titles above each column, by default None
kwargs (Any)

Returns:

Returns a figure object, which can be used by other PyGMT plotting functions.

Return type:

pygmt.Figure

plot_3d(grids, cmaps, exaggeration, drapegrids=None, view=(170, 30), vlims=None, region=None, hemisphere=None, shp_mask=None, polygon_mask=None, colorbar=True, cbar_perspective=True, **kwargs)[source]#

create a 3D perspective plot of a list of grids

Parameters:

grids (list or xarray.DataArray) – xarray DataArrays to be plotted in 3D
cmaps (list or str) – list of PyGMT colormap names to use for each grid
exaggeration (list or float) – list of vertical exaggeration factors to use for each grid
view (tuple, optional) – tuple of azimuth and elevation angles for the view, by default [170, 30]
vlims (tuple, optional) – tuple of vertical limits for the plot, by default is z range of grids
region (tuple[float, float, float, float], optional) – region for the figure in format [xmin, xmax, ymin, ymax], by default None
hemisphere (str, optional) – choose between plotting in the “north” or “south” hemispheres, by default None
shp_mask (Union[str or geopandas.GeoDataFrame], optional) – shapefile or geodataframe to clip the grids with, by default None
colorbar (bool, optional) – whether to plot a colorbar, by default True
cbar_perspective (bool, optional) – whether to plot the colorbar in perspective, by default True
drapegrids (list[xarray.DataArray] | None)
polygon_mask (list[float] | None)
kwargs (Any)

Returns:

Returns a figure object, which can be used by other PyGMT plotting functions.

Return type:

pygmt.Figure

interactive_data(hemisphere=None, coast=True, grid=None, grid_cmap='inferno', points=None, points_z=None, points_color='red', points_cmap='viridis', **kwargs)[source]#

plot points or grids on an interactive map using GeoViews

Parameters:

hemisphere (str, optional) – set whether to plot in “north” hemisphere (EPSG:3413) or “south” hemisphere (EPSG:3031)
coast (bool, optional) – choose whether to plot coastline data, by default True
grid (xarray.DataArray, optional) – display a grid on the map, by default None
grid_cmap (str, optional) – colormap to use for the grid, by default ‘inferno’
points (pandas.DataFrame, optional) – points to display on the map, must have columns ‘x’ and ‘y’, by default None
points_z (str, optional) – name of column to color points by, by default None
points_color (str, optional) – if no points_z supplied, color to use for all points, by default ‘red’
points_cmap (str, optional) – colormap to use for the points, by default ‘viridis’
kwargs (Any)

Returns:

holoview/geoviews map instance

Return type:

holoviews.Overlay

Example

>>> from polartoolkit import regions, utils, maps
...
>>> bedmap2_bed = fetch.bedmap2(layer='bed', region=regions.ross_ice_shelf)
>>> GHF_point_data = fetch.ghf(version='burton-johnson-2020', points=True)
...
>>> image = maps.interactive_data(
...    hemisphere="south",
...    grid = bedmap2_bed,
...    points = GHF_point_data[['x','y','GHF']],
...    points_z = 'GHF',
...    )
>>> image

geoviews_points(points, points_z=None, points_color='red', points_cmap='viridis', **kwargs)[source]#

Add points to a geoviews map instance. :param points: points to plot on the map, by default None :type points: pandas.DataFrame :param points_z: column name to color the points by, by default None :type points_z: str | None, optional :param points_color: color for the points, by default “red” :type points_color: str, optional :param points_cmap: colormap to use to color the points based on points_z, by default “viridis” :type points_cmap: str, optional

Returns:

the instance of points

Return type:

holoviews.element.Points

Parameters:

points (pandas.DataFrame)
points_z (str | None)
points_color (str)
points_cmap (str)
kwargs (Any)