polartoolkit.maps ================= .. py:module:: polartoolkit.maps Attributes ---------- .. autoapisummary:: polartoolkit.maps.ENGINE polartoolkit.maps.display polartoolkit.maps.gv polartoolkit.maps.crs polartoolkit.maps.ipyleaflet polartoolkit.maps.ipywidgets Functions --------- .. autoapisummary:: polartoolkit.maps._set_figure_spec polartoolkit.maps.basemap polartoolkit.maps.set_cmap polartoolkit.maps.plot_grd polartoolkit.maps.add_colorbar polartoolkit.maps.add_coast polartoolkit.maps.add_gridlines polartoolkit.maps.add_faults polartoolkit.maps.add_imagery polartoolkit.maps.add_modis polartoolkit.maps.add_simple_basemap polartoolkit.maps.add_inset polartoolkit.maps.add_scalebar polartoolkit.maps.add_north_arrow polartoolkit.maps.add_box polartoolkit.maps.interactive_map polartoolkit.maps.subplots polartoolkit.maps.plot_3d polartoolkit.maps.interactive_data polartoolkit.maps.geoviews_points Module Contents --------------- .. py:data:: ENGINE :value: 'pyogrio' .. py:data:: display :value: None .. py:data:: gv :value: None .. py:data:: crs :value: None .. py:data:: ipyleaflet :value: None .. py:data:: ipywidgets :value: None .. py:function:: _set_figure_spec(region, origin_shift = 'initialize', fig = None, fig_height = None, fig_width = None, hemisphere = None, yshift_amount = -1, xshift_amount = 1, xshift_extra = 0.4, yshift_extra = 0.4) determine what to do with figure .. py:function:: 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 = 'initialize', fig = None, **kwargs) 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. :param region: region for the figure in format [xmin, xmax, ymin, ymax], by default None :type region: tuple[float, float, float, float] | None, optional :param hemisphere: 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" :type hemisphere: str, optional :param coast: 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. :type coast: bool, optional :param north_arrow: choose to add a north arrow to the plot, by default is False. :type north_arrow: bool, optional :param scalebar: choose to add a scalebar to the plot, by default is False. See `add_scalebar` for additional kwargs :type scalebar: bool, optional :param faults: choose to plot faults on the map, by default is False :type faults: bool, optional :param simple_basemap: choose to plot a simple basemap with floating ice colored blue and grounded ice colored grey, with boarders defined by `simple_basemap_version`. :type simple_basemap: bool, optional :param simple_basemap_transparency: transparency to use for the simple basemap, by default is 0 :type simple_basemap_transparency: int, optional :param simple_basemap_version: version of the simple basemap to plot, by default is None :type simple_basemap_version: str, optional :param imagery_basemap: 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. :type imagery_basemap: bool, optional :param imagery_transparency: transparency to use for the imagery basemap, by default is 0 :type imagery_transparency: int, optional :param modis_basemap: choose to add a MODIS background imagery basemap, by default is False. :type modis_basemap: bool, optional :param modis_transparency: transparency to use for the MODIS basemap, by default is 0 :type modis_transparency: int, optional :param modis_version: version of the MODIS basemap to plot, by default is None :type modis_version: str, optional :param title: title to add to the figure, by default is None :type title: str | None, optional :param inset: choose to plot inset map showing figure location, by default is False :type inset: bool, optional :param points: points to plot on map, must contain columns 'x' and 'y' or 'easting' and 'northing'. :type points: pandas.DataFrame | None, optional :param gridlines: choose to plot lat/lon grid lines, by default is False :type gridlines: bool, optional :param origin_shift: 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. :type origin_shift: str, | None, optional :param fig: supply a figure instance for adding subplots or using other PyGMT plotting methods, by default None :type fig: pygmt.Figure, optional :param fig_height: height in cm for figures, by default is 15cm. :type fig_height: int or float :param fig_width: width in cm for figures, by default is None and is determined by fig_height and the projection. :type fig_width: int or float :param xshift_amount: amount to shift the origin in the x direction in multiples of current figure instance width, by default is 1. :type xshift_amount: int or float :param yshift_amount: amount to shift the origin in the y direction in multiples of current figure instance height, by default is -1. :type yshift_amount: int or float :param frame: GMT frame string to use for the basemap, by default is "nesw+gwhite" :type frame: str | bool :param frame_pen: GMT pen string to use for the frame, by default is "auto" :type frame_pen: str :param frame_font: GMT font string to use for the frame, by default is "auto" :type frame_font: str :param transparency: transparency to use for the basemap, by default is 0 :type transparency: int :param inset_position: position for inset map with PyGMT syntax, by default is "jTL+jTL+o0/0" :type inset_position: str :param title_font: font to use for the title, by default is 'auto' :type title_font: str :param show_region: show a rectangular region on the map, in the format [xmin, xmax, ymin, ymax]. :type show_region: tuple[float, float, float, float] :param region_pen: GMT pen string to use for the region box, by default is None :type region_pen: str :param x_spacing: spacing for x gridlines in degrees, by default is None :type x_spacing: float :param y_spacing: spacing for y gridlines in degrees, by default is None :type y_spacing: float :param points_style: style of points to plot in GMT format, by default is 'c.2c'. :type points_style: str :param points_fill: fill color of points, either string of color name or column name to color points by, by default is 'black'. :type points_fill: str :param points_pen: pen color and width of points, by default is '1p,black' if constant color or None if using a cmap. :type points_pen: str :param points_label: label to add to legend, by default is None :type points_label: str :param points_cmap: GMT color scale to use for coloring points, by default 'viridis'. If True, will use the last used in PyGMT. :type points_cmap: str :param cpt_lims: limits to use for color scale max and min, by default is max and min of data. :type cpt_lims: str or tuple] :param cmap_region: region to use to define color scale limits, in format [xmin, xmax, ymin, ymax], by default is region :type cmap_region: str or tuple[float, float, float, float] :param robust: use the 2nd and 98th percentile (or those specified with 'robust_percentiles') of the data to set color scale limits, by default is False. :type robust: bool :param robust_percentiles: percentiles to use for robust colormap limits, by default is (0.02, 0.98). :type robust_percentiles: tuple[float, float] :param reverse_cpt: reverse the color scale, by default is False. :type reverse_cpt: bool :param cbar_label: label to add to colorbar. :type cbar_label: str :param colorbar: choose to add a colorbar for the points to the plot, by default is False. :type colorbar: bool :param scalebar_font_color: color of the scalebar font, by default is 'black'. :type scalebar_font_color: str :param scale_font_color: deprecated, use scalebar_font_color. :type scale_font_color: str :param scalebar_length_perc: percentage of the min dimension of the figure region to use for the scalebar, by default is 0.25. :type scalebar_length_perc: float :param scale_length_perc: deprecated, use scalebar_length_perc. :type scale_length_perc: float :param scalebar_position: position of the scalebar on the figure, by default is 'n.5/.05' which is bottom center of the plot. :type scalebar_position: str :param scale_position: deprecated, use scalebar_position. :type scale_position: str :param coast_pen: GMT pen string to use for the coastlines, by default is None :type coast_pen: str :param no_coast: choose to not plot coastlines, just grounding lines, by default is False :type no_coast: bool :param coast_version: version of coastlines to plot, by default depends on the hemisphere :type coast_version: str :param coast_label: label to add to coastlines, by default is None :type coast_label: str :param fault_label: label to add to faults, by default is None :type fault_label: str :param fault_pen: GMT pen string to use for the faults, by default is None :type fault_pen: str :param fault_style: GMT style string to use for the faults, by default is None :type fault_style: str :param fault_activity: column name in faults to use for activity, by default is None :type fault_activity: str :param fault_motion: column name in faults to use for motion, by default is None :type fault_motion: str :param fault_exposure: column name in faults to use for exposure, by default is None :type fault_exposure: str :returns: Returns a figure object, which can be passed to the `fig` kwarg to add subplots or other `PyGMT` plotting methods. :rtype: pygmt.Figure .. rubric:: Example >>> from polartoolkit import maps, regions ... >>> fig = maps.basemap(region=regions.ross_ice_shelf) ... >>> fig.show() .. py:function:: 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), reverse_cpt = False, shp_mask = None, hemisphere = None, colorbar = True, **kwargs) Function used to set the PyGMT colormap for a figure. :param cmap: 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. :type cmap: str | bool :param grid: grid used to determine colormap limits and grd2cpt colormap equalization, by default None :type grid: str | xarray.DataArray | None, optional :param points: point values to use to determine colormap limits, by default None :type points: pandas.Series | numpy.ndarray | None, optional :param modis: choose appropriate cmap for plotting modis data, by default False :type modis: bool, optional :param grd2cpt: equalized the colormap to the grid data values, by default False :type grd2cpt: bool, optional :param cpt_lims: limits to set for the colormap, by default None :type cpt_lims: tuple[float, float] | None, optional :param cmap_region: extract colormap limits from a subset of the grid or points, in format [xmin, xmax, ymin, ymax], by default None :type cmap_region: tuple[float, float, float, float] | None, optional :param robust: use the 2nd and 98th percentile of the data from the grid or points, by default False :type robust: bool, optional :param robust_percentiles: percentiles to use for robust colormap limits, by default (0.02, 0.98) :type robust_percentiles: tuple[float, float], optional :param reverse_cpt: change the direction of the cmap, by default False :type reverse_cpt: bool, optional :param shp_mask: a shapefile to mask the grid or points by before extracting limits, by default None :type shp_mask: geopandas.GeoDataFrame | str | None, optional :param hemisphere: "north" or "south" hemisphere needed for using shp_mask, by default None :type hemisphere: str | None, optional :param colorbar: tell subsequent plotting functions whether to add a colorbar, by default True :type colorbar: bool, optional :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. :rtype: tuple[str | bool, bool, tuple[float,float] | None] .. py:function:: 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) 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. :param grid: 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. :type grid: str or xarray.DataArray :param region: 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. :type region: tuple[float, float, float, float], optional :param hemisphere: 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" :type hemisphere: str, optional :param cmap: 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. :type cmap: str or bool, optional :param coast: 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. :type coast: bool, optional :param north_arrow: choose to add a north arrow to the plot, by default is False. :type north_arrow: bool, optional :param scalebar: choose to add a scalebar to the plot, by default is False. See `add_scalebar` for additional kwargs :type scalebar: bool, optional :param faults: choose to plot faults on the map, by default is False :type faults: bool, optional :param simple_basemap: choose to plot a simple basemap with floating ice colored blue and grounded ice colored grey. :type simple_basemap: bool, optional :param simple_basemap_transparency: transparency to use for the simple basemap, by default is 0 :type simple_basemap_transparency: int, optional :param simple_basemap_version: version of the simple basemap to plot, by default is None :type simple_basemap_version: str, optional :param imagery_basemap: 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. :type imagery_basemap: bool, optional :param imagery_transparency: transparency to use for the imagery basemap, by default is 0 :type imagery_transparency: int, optional :param modis_basemap: choose to add a MODIS background imagery basemap, by default is False. :type modis_basemap: bool, optional :param modis_transparency: transparency to use for the MODIS basemap, by default is 0 :type modis_transparency: int, optional :param modis_version: version of the MODIS basemap to plot, by default is None :type modis_version: str, optional :param title: title to add to the figure, by default is None :type title: str | None, optional :param inset: choose to plot inset map showing figure location, by default is False :type inset: bool, optional :param points: points to plot on map, must contain columns 'x' and 'y' or 'easting' and 'northing'. :type points: pandas.DataFrame | None, optional :param gridlines: choose to plot lat/lon grid lines, by default is False :type gridlines: bool, optional :param origin_shift: 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. :type origin_shift: str, | None, optional :param fig: supply a figure instance for adding subplots or using other PyGMT plotting methods, by default None :type fig: pygmt.Figure, optional :param fig_height: height in cm for figures, by default is 15cm. :type fig_height: int or float :param fig_width: width in cm for figures, by default is None and is determined by fig_height and the projection. :type fig_width: int or float :param xshift_amount: amount to shift the origin in the x direction in multiples of current figure instance width, by default is 1. :type xshift_amount: int or float :param yshift_amount: amount to shift the origin in the y direction in multiples of current figure instance height, by default is -1. :type yshift_amount: int or float :param frame: GMT frame string to use for the basemap, by default is "nesw+gwhite" :type frame: str | bool :param frame_pen: GMT pen string to use for the frame, by default is "auto" :type frame_pen: str :param frame_font: GMT font string to use for the frame, by default is "auto" :type frame_font: str :param transparency: transparency to use for the basemap, by default is 0 :type transparency: int :param modis: set to True if plotting MODIS data to use a nice colorscale. :type modis: bool :param grd2cpt: use GMT module grd2cpt to set color scale from grid values, by default is False :type grd2cpt: bool :param cpt_lims: limits to use for color scale max and min, by default is max and min of data. :type cpt_lims: str or tuple] :param cmap_region: region to use to define color scale limits, in format [xmin, xmax, ymin, ymax], by default is region :type cmap_region: str or tuple[float, float, float, float] :param robust: use the 2nd and 98th percentile (or those specified with 'robust_percentiles') of the data to set color scale limits, by default is False. :type robust: bool :param robust_percentiles: percentiles to use for robust colormap limits, by default is (0.02, 0.98). :type robust_percentiles: tuple[float, float] :param reverse_cpt: reverse the color scale, by default is False. :type reverse_cpt: bool :param shp_mask: shapefile to use to mask the grid before extracting limits, by default is None. :type shp_mask: geopandas.GeoDataFrame | str :param colorbar: choose to add a colorbar to the plot, by default is True. :type colorbar: bool :param cbar_label: label to add to colorbar. :type cbar_label: str :param shading: GMT shading string to use for the basemap, by default is None :type shading: str :param grid_transparency: transparency of the grid, by default is 0 :type grid_transparency: int :param inset_position: position for inset map with PyGMT syntax, by default is "jTL+jTL+o0/0" :type inset_position: str :param title_font: font to use for the title, by default is 'auto' :type title_font: str :param show_region: show a rectangular region on the map, in the format [xmin, xmax, ymin, ymax]. :type show_region: tuple[float, float, float, float] :param region_pen: GMT pen string to use for the region box, by default is None :type region_pen: str :param x_spacing: spacing for x gridlines in degrees, by default is None :type x_spacing: float :param y_spacing: spacing for y gridlines in degrees, by default is None :type y_spacing: float :param points_style: style of points to plot in GMT format, by default is 'c.2c'. :type points_style: str :param points_fill: fill color of points, either string of color name or column name to color points by, by default is 'black'. :type points_fill: str :param points_pen: pen color and width of points, by default is '1p,black' if constant color or None if using a cmap. :type points_pen: str :param points_label: label to add to legend, by default is None :type points_label: str :param points_cmap: colormap to use for points, by default is None. :type points_cmap: str :param scalebar_font_color: color of the scalebar font, by default is 'black'. :type scalebar_font_color: str :param scale_font_color: deprecated, use scalebar_font_color. :type scale_font_color: str :param scalebar_length_perc: percentage of the min dimension of the figure region to use for the scalebar, by default is 0.25. :type scalebar_length_perc: float :param scale_length_perc: deprecated, use scalebar_length_perc. :type scale_length_perc: float :param scalebar_position: position of the scalebar on the figure, by default is 'n.5/.05' which is bottom center of the plot. :type scalebar_position: str :param scale_position: deprecated, use scalebar_position. :type scale_position: str :param coast_pen: GMT pen string to use for the coastlines, by default is None :type coast_pen: str :param no_coast: choose to not plot coastlines, just grounding lines, by default is False :type no_coast: bool :param coast_version: version of coastlines to plot, by default depends on the hemisphere :type coast_version: str :param coast_label: label to add to coastlines, by default is None :type coast_label: str :param fault_label: label to add to faults, by default is None :type fault_label: str :param fault_pen: GMT pen string to use for the faults, by default is None :type fault_pen: str :param fault_style: GMT style string to use for the faults, by default is None :type fault_style: str :param fault_activity: column name in faults to use for activity, by default is None :type fault_activity: str :param fault_motion: column name in faults to use for motion, by default is None :type fault_motion: str :param fault_exposure: column name in faults to use for exposure, by default is None :type fault_exposure: str :returns: Returns a figure object, which can be passed to the `fig` kwarg to add subplots or other `PyGMT` plotting methods. :rtype: pygmt.Figure .. rubric:: Example >>> from polartoolkit import maps ... >>> fig = maps.plot_grd('grid1.nc') >>> fig = maps.plot_grd( ... 'grid2.nc', ... origin_shift = 'x', ... fig = fig, ... ) ... >>> fig.show() .. py:function:: add_colorbar(fig, hist = False, cpt_lims = None, cbar_frame = None, verbose = 'w', **kwargs) Add a colorbar based on the last cmap used by PyGMT and optionally a histogram of the data values. :param fig: pygmt figure instance to add to :type fig: pygmt.Figure :param hist: choose whether to add a colorbar histogram, by default False :type hist: bool, optional :param cpt_lims: 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 :type cpt_lims: tuple[float, float], optional :param cbar_frame: frame for the colorbar, by default None :type cbar_frame: list[str] | str, optional :param verbose: verbosity level for pygmt, by default "w" for warnings :type verbose: str, optional :param \*\*kwargs: additional keyword arguments to pass :type \*\*kwargs: typing.Any .. py:function:: add_coast(fig, hemisphere = None, region = None, projection = None, no_coast = False, pen = None, version = None, label = None) add coastline and or groundingline to figure. :param fig: :type fig: pygmt.Figure :param hemisphere: choose between plotting in the "north" or "south" hemispheres :type hemisphere: str, optional :param region: region for the figure in format [xmin, xmax, ymin, ymax], if not provided will try to extract from the current figure. :type region: tuple[float, float, float, float], optional :param projection: GMT projection string, by default is last used by PyGMT :type projection: str, optional :param no_coast: If True, only plot groundingline, not coastline, by default is False :type no_coast: bool :param pen: GMT pen string, by default "0.6p,black" :type pen: None :param version: version of groundingline to plot, by default is 'BAS' for north hemisphere and 'measures-v2' for south hemisphere :type version: str, optional :param label: label to add to the legend, by default is None :type label: str, optional .. py:function:: add_gridlines(fig, region = None, projection = None, x_spacing = None, y_spacing = None, annotation_offset = '20p') 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. :param fig: :type fig: pygmt.Figure :param region: region for the figure in format [xmin, xmax, ymin, ymax], if not provided will try to extract from the current figure. :type region: tuple[float, float, float, float], optional :param projection: GMT projection string in lat lon, if your previous pygmt.Figure call used a cartesian projection, you will need to provide a projection in lat/lon here, use utils.set_proj() to make this projection. :type projection: str, optional :param x_spacing: spacing for x gridlines in degrees, by default is None :type x_spacing: float, optional :param y_spacing: spacing for y gridlines in degrees, by default is None :type y_spacing: float, optional :param annotation_offset: offset for gridline annotations, by default "20p" :type annotation_offset: str, optional .. py:function:: add_faults(fig, region = None, projection = None, fault_activity = None, fault_motion = None, fault_exposure = None, pen = None, style = None, label = None) add various types of faults from GeoMap to a map, from :footcite:t:`coxcontinentwide2023` and :footcite:t:`coxgeomap2023` :param fig: :type fig: pygmt.Figure :param region: region for the figure in format [xmin, xmax, ymin, ymax], if not provided will try to extract from the current figure. :type region: tuple[float, float, float, float], optional :param projection: GMT projection string in lat lon, if your previous pygmt.Figure call used a cartesian projection, you will need to provide a projection in lat/lon here, use utils.set_proj() to make this projection. :type projection: str, optional :param fault_activity: type of fault activity, options are active or inactive, by default both :type fault_activity: str, optional :param fault_motion: type of fault motion, options are sinistral, dextral, normal, or reverse, by default all :type fault_motion: str, optional :param fault_exposure: type of fault exposure, options are exposed or inferred, by default both :type fault_exposure: str, optional :param pen: GMT pen string, by default "1p,magenta,-" :type pen: str, optional :param style: GMT style string, by default None :type style: str, optional :param label: label to add to the legend, by default None :type label: str, optional .. py:function:: add_imagery(fig, hemisphere = None, transparency = 0) Add satellite imagery to a figure. For southern hemisphere uses LIMA imagery, but for northern hemisphere uses MODIS imagery. :param fig: PyGMT figure instance to add to :type fig: pygmt.Figure :param hemisphere: hemisphere to get data for, by default None :type hemisphere: str | None, optional :param transparency: transparency of the imagery, by default 0 :type transparency: int, optional .. py:function:: add_modis(fig, hemisphere = None, version = None, transparency = 0) Add MODIS imagery to a figure. :param fig: PyGMT figure instance to add to :type fig: pygmt.Figure :param hemisphere: hemisphere to get MODIS data for, by default None :type hemisphere: str | None, optional :param version: which version (resolution) of MODIS imagery to use, by default "750m" for southern hemisphere and "500m" for northern hemisphere. :type version: str | None, optional :param transparency: transparency of the MODIS imagery, by default 0 :type transparency: int, optional .. py:function:: add_simple_basemap(fig, hemisphere = None, version = None, transparency = 0, pen = '0.2p,black', grounded_color = 'grey', floating_color = 'skyblue') Add a simple basemap to a figure with grounded ice shown as grey and floating ice as blue. :param fig: PyGMT figure instance to add to :type fig: pygmt.Figure :param hemisphere: hemisphere to get coastline data for, by default None :type hemisphere: str | None, optional :param version: which version of shapefiles to use for grounding line / coastline, by default "measures-v2" for southern hemisphere and "BAS" for northern hemisphere :type version: str | None, optional :param transparency: transparency of all the plotted elements, by default 0 :type transparency: int, optional :param pen: GMT pen string for the coastline, by default "0.2,black" :type pen: str, optional :param grounded_color: color for the grounded ice, by default "grey" :type grounded_color: str, optional :param floating_color: color for the floating ice, by default "skyblue" :type floating_color: str, optional .. py:function:: add_inset(fig, hemisphere = None, region = None, inset_position = 'jTL+jTL+o0/0', inset_width = 0.25, inset_reg = None, **kwargs) add an inset map showing the figure region relative to the Antarctic continent. :param fig: :type fig: pygmt.Figure :param hemisphere: choose between plotting in the "north" or "south" hemispheres :type hemisphere: str, optional :param region: region for the figure in format [xmin, xmax, ymin, ymax], if not provided will try to extract from the current figure. :type region: tuple[float, float, float, float], optional :param inset_position: GMT location string for inset map, by default 'jTL+jTL+o0/0' (top left) :type inset_position: str, optional :param inset_width: Inset width as percentage of the smallest figure dimension, by default is 25% (0.25) :type inset_width: float, optional :param inset_reg: Region of Antarctica/Greenland to plot for the inset map, by default is whole area :type inset_reg: tuple[float, float, float, float], optional .. py:function:: add_scalebar(fig, region = None, projection = None, **kwargs) add a scalebar to a figure. :param fig: :type fig: pygmt.Figure :param region: region for the figure in format [xmin, xmax, ymin, ymax], if not provided will try to extract from the current figure. :type region: tuple[float, float, float, float], optional :param projection: GMT projection string in lat lon, if your previous pygmt.Figure call used a cartesian projection, you will need to provide a projection in lat/lon here, use utils.set_proj() to make this projection. :type projection: str, optional .. py:function:: add_north_arrow(fig, region = None, projection = None, **kwargs) add a north arrow to a figure :param fig: :type fig: pygmt.Figure :param region: region for the figure in format [xmin, xmax, ymin, ymax], if not provided will try to extract from the current figure. :type region: tuple[float, float, float, float], optional :param projection: GMT projection string in lat lon, if your previous pygmt.Figure call used a cartesian projection, you will need to provide a projection in lat/lon here, use utils.set_proj() to make this projection. :type projection: str, optional .. py:function:: add_box(fig, box, pen = '2p,black', verbose = 'w') Plot a GMT region as a box. :param fig: Figure to plot on :type fig: pygmt.Figure :param box: region in EPSG3031 in format [xmin, xmax, ymin, ymax] in meters :type box: tuple[float, float, float, float] :param pen: GMT pen string used for the box, by default "2p,black" :type pen: str, optional :param verbose: verbosity level for pygmt, by default "w" for warnings :type verbose: str, optional .. py:function:: interactive_map(hemisphere = None, center_yx = None, zoom = 0, display_xy = True, show = True, points = None, basemap_type = 'BlueMarble', **kwargs) Plot an interactive map with satellite imagery. Clicking gives the cursor location in a Polar Stereographic projection [x,y]. Requires ipyleaflet :param hemisphere: choose between plotting in the "north" or "south" hemispheres :type hemisphere: str, optional :param center_yx: choose center coordinates in EPSG3031 [y,x], by default [0,0] :type center_yx: tuple, optional :param zoom: choose zoom level, by default 0 :type zoom: float, optional :param display_xy: choose if you want clicks to show the xy location, by default True :type display_xy: bool, optional :param show: choose whether to display the map, by default True :type show: bool, optional :param points: choose to plot points supplied as columns 'x', 'y', or 'easting', 'northing', in EPSG:3031 in a dataframe :type points: pandas.DataFrame, optional :param basemap_type: choose what basemap to plot, options are 'BlueMarble', 'Imagery', 'Basemap', and "IceVelocity", by default 'BlueMarble' :type basemap_type: str, optional :returns: interactive map :rtype: ipyleaflet.Map .. py:function:: 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) 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. :param grids: list of xarray.DataArray's to be plotted :type grids: list :param hemisphere: choose between plotting in the "north" or "south" hemispheres, by default None :type hemisphere: str, optional :param region: choose to subset the grids to a specified region, in format [xmin, xmax, ymin, ymax], by default None :type region: tuple[float, float, float, float], optional :param dims: customize the subplot dimensions (# rows, # columns), by default will use `utils.square_subplots()` to make a square(~ish) layout. :type dims: tuple, optional :param fig_title: add a title to the figure, by default None :type fig_title: str, optional :param fig_x_axis_title: add a title to the x axis of the figure, by default None :type fig_x_axis_title: str, optional :param fig_y_axis_title: add a title to the y axis of the figure, by default None :type fig_y_axis_title: str, optional :param fig_title_font: font for the figure title, by default "30p,Helvetica-Bold" :type fig_title_font: str, optional :param subplot_labels: add subplot labels (a, b, c ...), by default True :type subplot_labels: bool, optional :param subplot_labels_loc: location of subplot labels, by default "TL" :type subplot_labels_loc: str, optional :param row_titles: add titles to the left of each row, by default None :type row_titles: list, optional :param column_titles: add titles above each column, by default None :type column_titles: list, optional :returns: Returns a figure object, which can be used by other PyGMT plotting functions. :rtype: pygmt.Figure .. py:function:: plot_3d(grids, cmaps, exaggeration, view = (170, 30), vlims = None, region = None, hemisphere = None, shp_mask = None, polygon_mask = None, colorbar = True, cbar_perspective = True, **kwargs) create a 3D perspective plot of a list of grids :param grids: xarray DataArrays to be plotted in 3D :type grids: list or xarray.DataArray :param cmaps: list of PyGMT colormap names to use for each grid :type cmaps: list or str :param exaggeration: list of vertical exaggeration factors to use for each grid :type exaggeration: list or float :param view: tuple of azimuth and elevation angles for the view, by default [170, 30] :type view: tuple, optional :param vlims: tuple of vertical limits for the plot, by default is z range of grids :type vlims: tuple, optional :param region: region for the figure in format [xmin, xmax, ymin, ymax], by default None :type region: tuple[float, float, float, float], optional :param hemisphere: choose between plotting in the "north" or "south" hemispheres, by default None :type hemisphere: str, optional :param shp_mask: shapefile or geodataframe to clip the grids with, by default None :type shp_mask: Union[str or geopandas.GeoDataFrame], optional :param colorbar: whether to plot a colorbar, by default True :type colorbar: bool, optional :param cbar_perspective: whether to plot the colorbar in perspective, by default True :type cbar_perspective: bool, optional :returns: Returns a figure object, which can be used by other PyGMT plotting functions. :rtype: pygmt.Figure .. py:function:: interactive_data(hemisphere = None, coast = True, grid = None, grid_cmap = 'inferno', points = None, points_z = None, points_color = 'red', points_cmap = 'viridis', **kwargs) plot points or grids on an interactive map using GeoViews :param hemisphere: set whether to plot in "north" hemisphere (EPSG:3413) or "south" hemisphere (EPSG:3031) :type hemisphere: str, optional :param coast: choose whether to plot coastline data, by default True :type coast: bool, optional :param grid: display a grid on the map, by default None :type grid: xarray.DataArray, optional :param grid_cmap: colormap to use for the grid, by default 'inferno' :type grid_cmap: str, optional :param points: points to display on the map, must have columns 'x' and 'y', by default None :type points: pandas.DataFrame, optional :param points_z: name of column to color points by, by default None :type points_z: str, optional :param points_color: if no `points_z` supplied, color to use for all points, by default 'red' :type points_color: str, optional :param points_cmap: colormap to use for the points, by default 'viridis' :type points_cmap: str, optional :returns: holoview/geoviews map instance :rtype: holoviews.Overlay .. rubric:: 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 .. py:function:: geoviews_points(points, points_z = None, points_color = 'red', points_cmap = 'viridis', **kwargs) 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 :rtype: holoviews.element.Points