polartoolkit.basemap

basemap(region=None, hemisphere=None, epsg=None, coast=False, north_arrow=False, scalebar=False, faults=False, geologic_units=False, simple_basemap=False, imagery_basemap=False, modis_basemap=False, bed_type=False, title=None, inset=False, points=None, gridlines=False, origin_shift=None, 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.

Parameters:

• region (tuple[float, float, float, float] | None) – region for the figure in format [xmin, xmax, ymin, ymax], by default None

• hemisphere (str | None) – 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”

• epsg (str | None) – set which EPSG projection to use for plotting, can be set manually, or will read from the environment variable: “POLARTOOLKIT_EPSG”, by default None

• coast (bool) – choose whether to plot coastline and grounding line, by default False. Version of shapefiles to plots depends on the set projection, and can be changed with kwargs coast_version, which defaults to BAS for the northern hemisphere, measures-v2 for the southern hemisphere, and GSHHG from GMT for other regions.

• north_arrow (bool) – choose to add a north arrow to the plot, by default is False.

• scalebar (bool) – choose to add a scalebar to the plot, by default is False. See add_scalebar for additional kwargs

• faults (bool) – choose to plot faults on the map, by default is False

• geologic_units (bool) – choose to plot geologic units on the map, by default is False

• simple_basemap (bool) – 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) – 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) – 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

• bed_type (bool) – choose to plot bed type classification, by default is False

• title (str | None) – title to add to the figure, by default is None

• inset (bool) – choose to plot inset map showing figure location, by default is False

• points (DataFrame | None) – points to plot on map, must contain columns ‘x’ and ‘y’ or ‘easting’ and ‘northing’.

• gridlines (bool) – choose to plot lat/lon grid lines, by default is False

• origin_shift (str | None) – choose what to do with the plot when creating the figure. By default is None 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 (Figure | None) – 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 projection

• coast_label (str) – label to add to coastlines, by default is None

• faults_label (str) – label to add to faults, by default is None

• faults_pen (str) – GMT pen string to use for the faults, by default is None

• faults_style (str) – GMT style string to use for the faults, by default is None

• faults_activity (str) – column name in faults to use for activity, by default is None

• faults_motion (str) – column name in faults to use for motion, by default is None

• faults_exposure (str) – column name in faults to use for exposure, by default is None

• faults_legend (bool) – choose to add a legend for the faults, by default is False

• faults_legend_loc (str | None) – location of the faults legend, by default is lower left

• geologic_units_legend (bool) – choose to add a legend for the geologic units, by default is False

• geologic_units_legend_loc (str | None) – location of the geologic units legend, by default is lower right

• bed_type_legend (bool) – choose to add a legend for the bed type, by default is False

• bed_type_legend_loc (str | None) – location of the bed type legend, by default is upper right

• bed_type_transparency (int) – transparency to use for the bed type, by default is 0

Returns:

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

Return type:

Figure

Example

>>> import polartoolkit as ptk
...
>>> fig = ptk.basemap(region=ptk.regions.ross_ice_shelf)
...
>>> fig.show()

Parameters:

kwargs (Any)