API Reference

Creating maps

These are the core functions for creating maps and plotting data. These functions all wrap the Figure class (below) to allow the various Figure methods to be called from a single function. They are designed for convenience, so users don’t need to call each of the Figure methods individually.

basemap([region, hemisphere, epsg, coast, ...])	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_grid(grid[, region, hemisphere, epsg, ...])	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.
plot_3d(grids, cmaps, exaggeration[, ...])	create a 3D perspective plot of a list of grids
subplots(grids[, hemisphere, epsg, region, ...])	Plot a series of grids as individual suplots.

Figure class

The Figure class and it’s methods are the core of the plotting functionality. The Figure class is a wrapper around the GMT figure class and adds some useful attributes which help with plots which are focused on data in projected units (such as the Polar Stereographic projections commonly used in polar research). The methods allow you to quick add map elements such as coastlines, gridlines, imagery, inset maps, as well as plot gridded and point datasets. The figure instances can be used directly with any PyGMT plotting functions.

Figure.add_grid(grid[, cmap, shading, ...])	Add a grid to the figure.
Figure.add_points(points[, cmap, fill, ...])	Add points to the figure.
Figure.add_imagery([transparency])	Add satellite imagery to a figure.
Figure.add_modis([version, transparency, cmap])	Add MODIS imagery to a figure.
Figure.add_coast([no_coast, pen, version, label])	add coastline and or groundingline to figure.
Figure.add_gridlines([x_spacing, y_spacing, ...])	add lat lon grid lines and annotations to a figure.
Figure.add_colorbar([hist, cpt_lims, ...])	Add a colorbar based on the last cmap used by PyGMT and optionally a histogram of the data values.
Figure.add_simple_basemap([version, ...])	Add a simple basemap to a figure with grounded ice / land shown as grey and floating ice as blue.
Figure.add_box(box[, pen, verbose])	Plot a GMT region as a box.
Figure.add_inset([inset_pos, ...])	add an inset map showing the figure region relative to a larger region.
Figure.add_scalebar(**kwargs)	add a scalebar to a figure.
Figure.add_north_arrow(**kwargs)	add a north arrow to a figure
Figure.add_faults([faults_activity, ...])	add various types of faults from GeoMap to a map, from Cox et al.[#coxcontinentwide2023]_ and Cox et al.[#coxgeomap2023]_
Figure.add_geologic_units([legend, legend_loc])	add geologic unit shapefiles from GeoMap to a map, from Cox et al.[#coxcontinentwide2023]_ and Cox et al.[#coxgeomap2023]_
Figure.add_bed_type([legend, legend_loc, ...])	add bed type classifications from from from Aitken et al.[#aitkenantarctic2023]_ and Aitken et al.[#aitkenantarctic2023a]_.
Figure.shift_figure([origin_shift, ...])	Determine if and how much to shift origin of figure

Creating profiles

The following functions are designed to create profiles and crosssections of gridded data. Topography data are plotted as colored layers, while other data can be plotted as lines. Profiles are defined by a straight line between two points, by a shapefile, or by interactively drawing a line on a map.

plot_profile(method[, layers_dict, ...])	Show sampled layers and/or data on a cross section, with an optional location map.
plot_data(method[, data_dict, add_map, ...])	Show sampled data on a cross section, with an optional location map.
draw_lines(**kwargs)	Plot an interactive map, and use the "Draw a Polyline" button to create vertices of a line.
shapes_to_df(shapes[, hemisphere, epsg])	convert the output of ptk.draw_region and ptk.draw_lines to a dataframe of easting and northing points
make_data_dict(names, grids, colors[, axes])	Create nested dictionary of data and attributes
default_data([region, hemisphere, epsg, verbose])	Fetch default gravity and magnetic datasets.
default_layers(version[, hemisphere, epsg, ...])	Fetch default ice surface, ice base, and bed layers.

Reprojecting

These functions are designed to reproject coordinates or data between different coordinate reference systems. The functions also include some convenience functions for working with EPSG projection codes and GMT projection strings.

reproject(df, input_crs, output_crs[, ...])	Convert coordinates from input CRS to output CRS.
latlon_to_epsg3031(df[, reg, ...])	Convert coordinates from EPSG:4326 WGS84 in decimal degrees to EPSG:3031 Antarctic Polar Stereographic in meters.
latlon_to_epsg3413(df[, reg, ...])	Convert coordinates from EPSG:4326 WGS84 in decimal degrees to EPSG:3413 North Polar Stereographic in meters.
epsg3031_to_latlon(df[, reg, ...])	Convert coordinates from EPSG:3031 Antarctic Polar Stereographic in meters to EPSG:4326 WGS84 in decimal degrees.
epsg3413_to_latlon(df[, reg, ...])	Convert coordinates from EPSG:3413 North Polar Stereographic in meters to EPSG:4326 WGS84 in decimal degrees.
dd2dms(dd)	Convert decimal degrees to minutes, seconds.
default_epsg(epsg, hemisphere)	Returns the provided EPSG code through 1 of 4 methods in the following preference.
epsg_central_coordinates(epsg)	Returns the central coordinates for the EPSG code in degrees.
gmt_projection_from_epsg(epsg)	Get a GMT projection string from an EPSG code.

Spatial operations

These functions perform various spatial operations on gridded or point data, such as resampling, filtering, masking, and calculating statistics.

subset_grid(grid, region)	Return a subset of a grid based on a region
sample_grids(df, grid, sampled_name, **kwargs)	Sample data at every point along a line
resample_grid(grid[, spacing, region, ...])	Resample a grid to a new spacing, region, and/or registration.
block_reduce(df, reduction[, ...])	perform a block reduction of a dataframe.
change_registration(grid)	Use GMT grdedit to change the registration type in the metadata.
filter_grid(grid[, filter_width, ...])	Apply a spatial filter to a grid.
get_min_max(values[, shapefile, robust, ...])	Get a grids max and min values.
get_combined_min_max(values[, shapefile, ...])	Get a grids max and min values.
get_grid_info(grid[, print_info])	Returns information of the specified grid.
get_grid_region(grid)	Returns the region of the specified grid.
get_grid_registration(grid)	Returns the registration of the specified grid.
get_grid_spacing(grid)	Returns the spacing of the specified grid.
grid_blend(grid1, grid2)	Use GMT grdblend to blend 2 grids into 1.
grid_compare(da1, da2[, plot, plot_type, robust])	Find the difference between 2 grids and plot the results, if necessary resample and cut grids to match
grid_trend(da[, coords, deg, plot])	Fit an arbitrary order trend to a grid and use it to detrend.
make_grid(region, spacing, value, name)	Create a grid with 1 variable by defining a region, spacing, name and constant value
mask_from_polygon(polygon[, hemisphere, ...])	convert the output of ptk.draw_region to a mask or use it to mask a grid
mask_from_shapefile(shapefile[, hemisphere, ...])	Create a mask or a masked grid from area inside or outside of a closed shapefile.
nearest_grid_fill(grid[, method, crs])	fill missing values in a grid with the nearest value.
points_inside_region(df, region[, names, ...])	return a subset of a dataframe which is within a region
points_inside_shapefile(points, shapefile[, ...])	return a subset of a dataframe which is located inside a shapefile.
polygon_to_shapefile(polygon[, hemisphere, epsg])	Convert a polygon drawn with ptk.draw_region to a geopandas GeoDataFrame
rmse(data[, as_median])	function to give the root mean/median squared error (RMSE) of data

Plotting utilities

Here are a few utility functions which can be helpful for plotting.

square_subplots(n)	From matplotlib/grid-strategy Calculate the number of rows and columns based on the total number of items (n) to make an arrangement as close to square as looks good.
set_proj(region[, hemisphere, epsg, ...])	Gives GMT projection strings in project and geographic units, from region and figure height or width.
random_color()	generate a random color in format R/G/B
get_fig_height()	Get the height of the current PyGMT figure instance.
get_fig_width()	Get the width of the current PyGMT figure instance.
gmt_str_to_list(region)	convert a tuple of floats representing the boundaries of a region into a GMT-style region string

Interactive functions

These functions allow you to interactively plot and explore gridded or point data.

interactive_map([hemisphere, epsg, ...])	Plot an interactive map with various basemaps.
interactive_data([hemisphere, epsg, coast, ...])	plot points or grids on an interactive map using GeoViews
geoviews_points(points[, points_z, ...])	Add points to a geoviews map instance. :param points: points to plot on the map, by default None :type points: DataFrame :param points_z: column name to color the points by, by default None :type points_z: str | None :param points_color: color for the points, by default "red" :type points_color: str :param points_cmap: colormap to use to color the points based on points_z, by default "viridis" :type points_cmap: str :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 | None :param epsg: set which EPSG projection to use for plotting, can be set manually, or will read from the environment variable: "POLARTOOLKIT_EPSG", by default None :type epsg: str | None.

Region utilities

These utility functions are used for defining and transforming geographic bounding regions, which are used throughout PolarToolkit.

alter_region(starting_region[, zoom, ...])	Change a bounding region by shifting the box east/west or north/south, or zooming in or out.
combine_regions(region1, region2)	Get the bounding region of 2 regions.
regions_overlap(region1, region2)	Get the overlap of 2 regions.
draw_region(**kwargs)	Plot an interactive map, and use the "Draw a Rectangle" button to draw a rectangle and get the bounding region.
polygon_to_region(polygon[, hemisphere, epsg])	convert the output of ptk.draw_region to bounding region in the supplied projected units.
region_xy_to_ll(region[, hemisphere, epsg, ...])	Convert region in format [xmin, xmax, ymin, ymax] in projected meters to lat / lon
region_ll_to_xy(region[, hemisphere, epsg])	Convert region in format [lon_min, lon_max, lat_min, lat_max] to projected meters in the north or south polar stereographic projections.
region_to_df(region[, coord_names, reverse])	Convert region bounds in format [xmin, xmax, ymin, ymax] to pandas dataframe with coordinates of region corners, or reverse this if reverse is True.
region_to_bounding_box(region)	Convert region in format [xmin, xmax, ymin, ymax] to bounding box format used for icepyx: [ lower left longitude, lower left latitude, upper right longitude, upper right latitude ] Same format as [xmin, ymin, xmax, ymax], used for bbox parameter of geopandas.read_file
square_around_region(region[, factor])	Get a square region around a supplied region, by expanding the smaller dimension to match the larger one and optionally scaling it by a multiple of the larger dimension.

Download and fetching data

These are all the various datasets you can download and fetch with PolarToolkit.

polartoolkit.fetch.EarthDataDownloader()	Either pulls login details from pre-set environment variables, or prompts user to input username and password.
polartoolkit.fetch.mass_change([version, ...])	Ice-sheet height and thickness changes from ICESat to ICESat-2 for both Antarctica and Greenland from Smith et al.[#smithpervasive2020]_.
polartoolkit.fetch.basal_melt([version, ...])	Antarctic ice shelf basal melt rates for 1994-2018 from satellite radar altimetry.
polartoolkit.fetch.buttressing(version[, ...])	Antarctic ice shelf buttressing.
polartoolkit.fetch.ice_vel([region, ...])	MEaSUREs Phase-Based Ice Velocity Maps for Antarctica and Greenland.
polartoolkit.fetch.modis([version, ...])	Load the MODIS Mosaic of Antarctica (MoA) or Greenland (MoG) imagery.
polartoolkit.fetch.imagery()	Load the file path of Antarctic imagery geotiff from LIMA from Bindschadler et al.[#bindschadlerlandsat2008]_.
polartoolkit.fetch.antarctic_bed_type([region])	Bed classification dataset accessed from https://zenodo.org/records/7955584.
polartoolkit.fetch.geomap([version, region])	Data from GeoMAP accessed from https://doi.pangaea.de/10.1594/PANGAEA.951482?format=html#download
polartoolkit.fetch.groundingline([version])	Load the file path of two versions of groundingline shapefiles
polartoolkit.fetch.antarctic_boundaries(version)	Load various files from the MEaSUREs Antarctic Boundaries for IPY 2007-2009
polartoolkit.fetch.sediment_thickness(version)	Load 1 of 4 'versions' of sediment thickness data.
polartoolkit.fetch.ibcso_coverage([region])	Load IBCSO v2 data, from Dorschel et al.[#dorschelinternational2022]_ and Dorschel et al.[#dorschelinternational2022a]_.
polartoolkit.fetch.ibcso(layer[, reference, ...])	Load IBCSO v2 data, from Dorschel et al.[#dorschelinternational2022]_ and Dorschel et al.[#dorschelinternational2022a]_.
polartoolkit.fetch.bedmachine(layer[, ...])	Load BedMachine topography data from either Greenland (v5) or Antarctica (v3), from Morlighem[#morlighemmeasures2022]_ or IceBridge BedMachine Greenland, Version 5[#icebridge2020]_.
polartoolkit.fetch.bedmap_points(version[, ...])	Load bedmap point data, choose from Bedmap 1, 2 or 3 or all combined.
polartoolkit.fetch.bedmap3(layer[, ...])	Load Bedmap3 data as an xarray.DataArray from Pritchard et al.[#pritchardbedmap32025]_.
polartoolkit.fetch.bedmap2(layer[, ...])	Load bedmap2 data as xarray.DataArrays from Fretwell et al.[#fretwellbedmap22013]_.
polartoolkit.fetch.rema([version, region, ...])	Load the REMA surface elevation data from Howat et al.[#howatreference2019]_.
polartoolkit.fetch.deepbedmap([region, ...])	Load DeepBedMap data, from Leong and Horgan[#leongdeepbedmap2020]_ and Leong and Horgan[#leongdeepbedmap2020a]_.
polartoolkit.fetch.gravity(version[, ...])	Loads gravity anomaly data for the Arctic and Antarctic.
polartoolkit.fetch.etopo([region, spacing, ...])	Loads a grid of Antarctic topography from ETOPO1 from ETOPO1 1 Arc-Minute Global Relief Model: Procedures, Data Sources and Analysis[#etopo12009]_.
polartoolkit.fetch.geoid([region, spacing, ...])	Loads a grid of geoid heights derived from the EIGEN-6C4 from Förste et al.[#forsteeigen6c42014]_ spherical harmonic model of Earth's gravity field.
polartoolkit.fetch.magnetics(version[, ...])	Load magnetic anomaly data for the Arctic and Antarctic.
polartoolkit.fetch.ghf(version[, region, ...])	Load 1 of 8 'versions' of Antarctic geothermal heat flux data.
polartoolkit.fetch.gia(version[, region, ...])	Load 1 of 1 'versions' of Antarctic glacial isostatic adjustment grids.
polartoolkit.fetch.crustal_thickness(version)	Load various Antarctic crustal thickness data.
polartoolkit.fetch.moho(version[, region, ...])	Load various Antarctic Moho elevation data.