API Reference
Contents
API Reference#
Maps#
- plot_grd(grid: str, cmap: str = 'viridis', plot_region: Optional[str] = None, coast: bool = False, origin_shift: str = 'initialize', **kwargs)[source]#
Helps easily create PyGMT maps, individually or as subplots.
- Parameters
grid (Union[str or xr.DataArray]) – grid file to plot, either loaded xr.DataArray or string of a filename
cmap (str, optional) – GMT color scale to use, by default ‘viridis’
plot_region (Union[str or np.ndarray], optional) – region to plot, by default is extent of input grid
coast (bool, optional) – choose whether to plot Antarctic coastline and grounding line, by default False
origin_shift (str, optional) – automatically will create a new figure, set to ‘xshift’ to instead add plot to right of previous plot, or ‘yshift’ to add plot above previous plot, by default ‘initialize’.
- Keyword Arguments
image (bool) – set to True if plotting imagery to correctly set colorscale.
grd2cpt (bool) – use GMT module grd2cpt to set color scale from grid values, by default is False
cmap_region (Union[str or np.ndarray]) – region to use to define color scale if grd2cpt is True, by default is plot_region
cbar_label (str) – label to add to colorbar.
points (pd.DataFrame) – points to plot on map, must contain columns ‘x’ and ‘y’.
square (np.ndarray) – GMT-format region to use to plot a square.
cpt_lims (Union[str or tuple]) – limits to use for color scale max and min, by default is max and min of data.
fig (pygmt.Figure()) – if adding subplots, set the first returned figure to a variable, and add that variable as the kwargs ‘fig’ to subsequent calls to plot_grd.
grid_lines (bool) – choose to plot lat/long grid lines, by default is False
inset (bool) – choose to plot inset map showing figure location, by default is False
inset_pos (str) – position for inset map; either ‘TL’, ‘TR’, BL’, ‘BR’, by default is ‘TL’
- 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 antarctic_plots import maps ... >>> fig = maps.plot_grd('grid1.nc') >>> fig = maps.plot_grd( ... 'grid2.nc', ... origin_shift = 'xshift', ... fig = fig, ... ) ... >>> fig.show()
Profile#
- create_profile(method: str, start: Optional[numpy.ndarray] = None, stop: Optional[numpy.ndarray] = None, num=100, shp_num_points: Optional[int] = None, shapefile: Optional[str] = None, **kwargs)[source]#
Create a pandas DataFrame of points along a line with multiple methods.
- Parameters
method (str) – Choose sampling method, either “points” or “shapefile”
start (np.ndarray, optional) – Coordinates for starting point of profile, by default None
stop (np.ndarray, optional) – Coordinates for eding point of profile, by default None
num (int, optional) – Number of points between start and stop, by default 100
shp_num_points (int, optional) – Number of points to resample shapefile to, by default None
shapefile (str, optional) – shapefile file name to create points along, by default None
- Returns
Dataframe with ‘x’, ‘y’, and ‘dist’ columns for points along line or shapefile path.
- Return type
pd.Dataframe
- default_data(region=None) dict [source]#
Fetch default gravity and magnetic datasets.
- Parameters
region (str or list[int], optional) – region of Antarctic to load, by default is entire Antarctic region.
- Returns
Nested dictionary of data and attributes
- Return type
dict[dict]
- default_layers() dict [source]#
Fetch default Bedmachine layers.
- Returns
Nested dictionary of Bedmachine layers and attributes
- Return type
dict[dict]
- fill_nans(df)[source]#
Fill NaN’s in sampled layer with values from above layer.
- Parameters
df (pd.DataFrame) – First 3 columns as they are assumed to by x, y, dist.
- Returns
Dataframe with NaN’s of lower layers filled
- Return type
pd.DataFrame
- make_data_dict(names: list, grids: list, colors: list) dict [source]#
Create nested dictionary of data and attributes
- Parameters
names (list[str]) – data names
grids (list[str or xarray.DataArray]) – files or xarray.DataArray’s
colors (list[str]) – colors to plot data
- Returns
Nested dictionaries of grids and attributes
- Return type
dict[dict]
- plot_profile(method: str, layers_dict: Optional[dict] = None, data_dict: Optional[dict] = None, add_map: bool = False, **kwargs)[source]#
Show sampled layers and/or data on a cross section, with an optional location map.
- Parameters
method (str) – Choose the sample method, either ‘points’, or ‘shapefile’.
layers_dict (dict, optional) – nested dictionary of layers to include in cross-section, construct with profile.make_data_dict, by default is Bedmap2 layers.
data_dict (dict, optional) – nested dictionary of data to include in option graph, construct with profile.make_data_dict, by default is gravity and magnetic anomalies.
add_map (bool = False) – Choose whether to add a location map, by default is False.
- Keyword Arguments
fillnans (bool) – Choose whether to fill nans in layers, defaults to True.
clip (bool) – Choose whether to clip the profile based on distance.
max_dist (int) – Clip all distances greater than.
min_dist (int) – Clip all distances less than.
map_background (str or xarray.DataArray) – Change the map background by passing a filename string or grid, by default is imagery.
map_cmap (str) – Change the map colorscale by passing a valid GMT cmap string, by default is ‘earth’.
map_buffer (float (0-1)) – Change map zoom as relative percentage of profile length, by default is 0.3.
layer_buffer (float (0-1)) – Change vertical white space within cross-section, by default is 0.1.
data_buffer (float (0-1)) – Change vertical white space within data graph, by default is 0.1.
inset (bool) – choose to plot inset map showing figure location, by default is True
inset_pos (str) – position for inset map; either ‘TL’, ‘TR’, BL’, ‘BR’, by default is ‘TL’
save (bool) – Choose to save the image, by default is False.
path (str) – Filename for saving image, by default is None.
- sample_grids(df, grid, name: Optional[str] = None)[source]#
Sample data at every point along a line
- Parameters
df (pd.DataFrame) – Dataframe containing columns ‘x’, ‘y’
grid (str or xr.DataArray) – Grid to sample, either file name or xr.DataArray
name (str, optional) – Name for sampled column, by default is str(grid)
- Returns
Dataframe with new column (name) of sample values from (grid)
- Return type
pd.DataFrame
- shorten(df, max_dist=None, min_dist=None, **kwargs)[source]#
Shorten a dataframe at either end based on distance column.
- Parameters
df (pd.DataFrame) – Dataframe to shorten and recalculate distance, must contain ‘x’, ‘y’, ‘dist’
max_dist (int, optional) – remove rows with dist>max_dist, by default None
min_dist (int, optional) – remove rows with dist<min_dist, by default None
- Returns
Shortened dataframe
- Return type
pd.DataFrame
Fetch#
- basement(plot: bool = False, info: bool = False) xarray.core.dataarray.DataArray [source]#
Load a grid of basement topography. Offshore and sub-Ross Ice Shelf basement topography. from Tankersley et al. 2022: https://onlinelibrary.wiley.com/doi/10.1029/2021GL097371 offshore data from Lindeque et al. 2016: https://doi.org/10.1002/2016GC006401
- Parameters
plot (bool, optional) – plot the fetched grid, by default False
info (bool, optional) – print info on the fetched grid, by default False
- Returns
dataarray of basement depths
- Return type
xr.DataArray
- bedmachine(layer: str, reference: str = 'geoid', plot: bool = False, info: bool = False, region=None, spacing=10000.0) xarray.core.dataarray.DataArray [source]#
Load BedMachine data, from Morlighem et al. 2020: https://doi.org/10.1038/s41561-019-0510-8
orignally from https://nsidc.org/data/nsidc-0756/versions/1. Added to Google Bucket as described in the following notebook: https://github.com/ldeo-glaciology/pangeo-bedmachine/blob/master/load_plot_bedmachine.ipynb # noqa
- Parameters
layer (str) – choose which layer to fetch: ‘surface’, ‘thickness’, ‘bed’, ‘firn’, ‘geoid’, ‘mapping’, ‘mask’, ‘errbed’, ‘source’; ‘icebase’ will give results of surface-thickness
reference (str) – choose whether heights are referenced to ‘geoid’ (EIGEN-6C4) or ‘ellipsoid’ (WGS84), by default is ‘geoid’
plot (bool, optional) – choose to plot grid, by default False
info (bool, optional) – choose to print info on grid, by default False
region (str or np.ndarray, optional) – GMT-format region to clip the loaded grid to, by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
- Returns
Returns a loaded, and optional clip/resampled grid of Bedmachine.
- Return type
xr.DataArray
- bedmap2(layer: str, reference: str = 'geoid', plot: bool = False, info: bool = False, region=None, spacing=10000.0) xarray.core.dataarray.DataArray [source]#
Load bedmap2 data. All grids are by default referenced to the g104c geoid. Use the ‘reference’ parameter to convert to the ellipsoid. Note, nan’s in surface grid are set to 0. from https://doi.org/10.5194/tc-7-375-2013.
- Parameters
layer (str) – choose which layer to fetch: ‘surface’, ‘thickness’, ‘bed’, ‘gl04c_geiod_to_WGS84’, ‘icebase’ will give results of surface-thickness
reference (str) – choose whether heights are referenced to ‘geoid’ (g104c) or ‘ellipsoid’ (WGS84), by default is ‘geoid’
plot (bool, optional) – choose to plot grid, by default False
info (bool, optional) – choose to print info on grid, by default False
region (str or np.ndarray, optional) – GMT-format region to clip the loaded grid to, by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
- Returns
Returns a loaded, and optional clip/resampled grid of Bedmap2.
- Return type
xr.DataArray
- deepbedmap(plot: bool = False, info: bool = False, region=None, spacing=10000.0) xarray.core.dataarray.DataArray [source]#
Load DeepBedMap data, from Leong and Horgan, 2020: https://doi.org/10.5194/tc-14-3687-2020 Accessed from https://zenodo.org/record/4054246#.Ysy344RByp0
- Parameters
plot (bool, optional) – choose to plot grid, by default False
info (bool, optional) – choose to print info on grid, by default False
region (str or np.ndarray, optional) – GMT-format region to clip the loaded grid to, by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
- Returns
Returns a loaded, and optional clip/resampled grid of DeepBedMap.
- Return type
xr.DataArray
- geothermal(version: str, plot: bool = False, info: bool = False, region=None, spacing: Optional[int] = None) xarray.core.dataarray.DataArray [source]#
Load 1 of 3 ‘versions’ of Antarctic geothermal heat flux grids. version=’burton-johnson-2020’ From Burton-Johnson et al. 2020: Review article: Geothermal heat flow in Antarctica: current and future directions, https://doi.org/10.5194/tc-14-3843-2020 Accessed from supplementary material version=’losing-ebbing-2021’ From Losing and Ebbing 2021: Predicting Geothermal Heat Flow in Antarctica With a Machine Learning Approach. Journal of Geophysical Research: Solid Earth, 126(6), https://doi.org/10.1029/2020JB021499 Accessed from https://doi.pangaea.de/10.1594/PANGAEA.930237 version=’aq1’ From Stal et al. 2021: Antarctic Geothermal Heat Flow Model: Aq1. DOI: https://doi.org/10.1029/2020GC009428 Accessed from https://doi.pangaea.de/10.1594/PANGAEA.924857 verion=’shen-2020’: From Shen et al. 2020; A Geothermal Heat Flux Map of Antarctica Empirically Constrained by Seismic Structure. https://doi.org/ 10.1029/2020GL086955 Accessed from https://sites.google.com/view/weisen/research-products?authuser=0
- Parameters
version (str) – Either ‘burton-johnson-2020’, ‘losing-ebbing-2021’, ‘aq1’,
plot (bool, optional) – choose to plot grid, by default False
info (bool, optional) – choose to print info on grid, by default False
region (str or np.ndarray, optional) – GMT-format region to clip the loaded grid to, by default doesn’t clip
spacing (int, optional) – grid spacing to resample the loaded grid to, by default spacing is read from downloaded files
- Returns
Returns a loaded, and optional clip/resampled grid of GHF data.
- Return type
xr.DataArray
- gravity(type: str, plot: bool = False, info: bool = False, region=None, spacing=10000.0) xarray.core.dataarray.DataArray [source]#
Loads an Antarctic gravity grid Preliminary compilation of Antarctica gravity and gravity gradient data. Updates on 2016 AntGG compilation. Accessed from https://ftp.space.dtu.dk/pub/RF/4D-ANTARCTICA/.
- Parameters
type (str) – either ‘FA’ or ‘BA’, for free-air and bouguer anomalies, respectively.
plot (bool, optional) – choose to plot grid, by default False
info (bool, optional) – choose to print info on grid, by default False
region (str or np.ndarray, optional) – GMT-format region to clip the loaded grid to, by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
- Returns
Returns a loaded, and optional clip/resampled grid of either free-air or Bouguer gravity anomalies.
- Return type
xr.DataArray
- groundingline() str [source]#
Load the file path of a groundingline shapefile Antarctic groundingline shape file, from https://doi.pangaea.de/10.1594/PANGAEA.819147 Supplement to Depoorter et al. 2013: https://doi.org/10.1038/nature12567
- Returns
file path
- Return type
str
- imagery() xarray.core.dataarray.DataArray [source]#
Load the file path of Antarctic imagery geotiff from LIMA: https://lima.usgs.gov/fullcontinent.php will replace with below once figured out login issue with pooch MODIS Mosaic of Antarctica: https://doi.org/10.5067/68TBT0CGJSOJ Assessed from https://daacdata.apps.nsidc.org/pub/DATASETS/nsidc0730_MEASURES_MOA2014_v01/geotiff/ # noqa
- Returns
file path
- Return type
str
- magnetics(version: str, plot: bool = False, info: bool = False, region=None, spacing=10000.0) xarray.core.dataarray.DataArray [source]#
Load 1 of 4 ‘versions’ of Antarctic magnetic anomaly grid. version=’admap2’ ADMAP2 magnetic anomaly compilation of Antarctica. Non-geosoft specific files provide from Sasha Golynsky. version=’admap1’ ADMAP-2001 magnetic anomaly compilation of Antarctica. https://admap.kongju.ac.kr/databases.html version=’admap2_eq_src’ ADMAP2 eqivalent sources, from https://admap.kongju.ac.kr/admapdata/ version=’admap2_gdb’ Geosoft-specific .gdb abridged files. Accessed from https://doi.pangaea.de/10.1594/PANGAEA.892722?format=html#download
- Parameters
version (str) – Either ‘admap1’, ‘admap2_eq_src’, or ‘admap2_gdb’
plot (bool, optional) – choose to plot grid, by default False
info (bool, optional) – choose to print info on grid, by default False
region (str or np.ndarray, optional) – GMT-format region to clip the loaded grid to, by default doesn’t clip
spacing (str or int, optional) – grid spacing to resample the loaded grid to, by default 10e3
- Returns
Returns a loaded, and optional clip/resampled grid of magnetic anomalies.
- Return type
xr.DataArray
Utils#
- GMT_reg_xy_to_ll(input)[source]#
Convert GMT region string [e, w, n, s] in EPSG:3031 to deg:min:sec
- Parameters
input (np.ndarray) – Array of 4 strings in GMT format; [e, w, n, s] in meters
- Returns
Array of 4 strings in GMT format; [e, w, n, s] in lat, lon
- Return type
np.ndarray
- alter_region(starting_region: numpy.ndarray, zoom: float = 0, n_shift: float = 0, w_shift: float = 0, buffer: float = 0, print_reg: bool = False)[source]#
Change a region string by shifting the box east/west or north/south, zooming in or out, or adding a seperate buffer region.
- Parameters
starting_region (np.ndarray) – Initial GMT formatted region in meters, [e,w,n,s]
zoom (float, optional) – zoom in or out, in meters, by default 0
n_shift (float, optional) – shift north, or south if negative, in meters, by default 0
w_shift (float, optional) – shift west, or eash if negative, in meters, by default 0
buffer (float, optional) – create new region which is zoomed out in all direction, in meters, by default 0
print_reg (bool, optional) – print out the dimensions of the altered region, by default False
- Returns
Returns of list of the following variables (region, buffer_region, proj)
- Return type
list
- coherency(grids: list, label: str, **kwargs)[source]#
Compute and plot the Radially Averaged Power Spectrum input data.
- Parameters
grids (list) – list of 2 grids to calculate the cohereny between. grid format can be str (filename), xr.DataArray, or pd.DataFrame.
label (str) – used to label line.
- Keyword Arguments
region (Union[str, np.ndarray]) – grid region if input is pd.DataFrame
spacing (float) – grid spacing if input is pd.DataFrame
- dd2dms(dd: float)[source]#
Convert decimal degrees to minutes, seconds. Modified from https://stackoverflow.com/a/10286690/18686384
- Parameters
dd (float) – input decimal degrees
- Returns
degrees in the format “DD:MM:SS”
- Return type
str
- epsg3031_to_latlon(df, reg: bool = False, input=['x', 'y'], output=['lon', 'lat'])[source]#
Convert coordinates from EPSG:3031 Antarctic Polar Stereographic in meters to EPSG:4326 WGS84 in decimal degrees.
- Parameters
df (pd.DataFrame) – input dataframe with easting and northing columns
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input (list, optional) – set names for input columns, by default [“x”, “y”]
output (list, optional) – set names for output columns, by default [“lon”, “lat”]
- Returns
Updated dataframe with new latitude and longitude columns or np.ndarray in format [e, w, n, s]
- Return type
pd.DataFrame or np.ndarray
- get_grid_info(grid)[source]#
Returns information of the specified grid.
- Parameters
grid (str or xarray.DataArray) – Input grid to get info from. Filename string or loaded grid.
- Returns
(string of grid spacing, array with the region boundaries, data min, data max, grid registration)
- Return type
list
- grd_compare(da1: Union[xarray.core.dataarray.DataArray, str], da2: Union[xarray.core.dataarray.DataArray, str], **kwargs)[source]#
Find the difference between 2 grids and plot the results, if necessary resample and cut grids to match
- Parameters
da1 (xr.DataArray or str) – first grid, loaded grid of filename
da2 (xr.DataArray or str) – second grid, loaded grid of filename
- Keyword Arguments
shp_mask (str) – shapefile filename to use to mask the grids for setting the color range.
robust (bool) – use xarray robust color lims instead of min and max, by default is False.
- Returns
the result of da1 - da2
- Return type
xr.DataArray
- grd_trend(da: xarray.core.dataarray.DataArray, coords: list = ['x', 'y', 'z'], deg: int = 1, plot_all: bool = False)[source]#
Fit an arbitrary order trend to a grid and use it to detrend.
- Parameters
da (xr.DataArray) – input grid
coords (list, optional) – coordinate names of grid, by default [‘x’, ‘y’, ‘z’]
deg (int, optional) – trend order to use, by default 1
plot_all (bool, optional) – plot the results, by default False
- Returns
returns xr.DataArrays of the fitted surface, and the detrended grid.
- Return type
tuple
- latlon_to_epsg3031(df, reg: bool = False, input=['lon', 'lat'], output=['x', 'y'])[source]#
Convert coordinates from EPSG:4326 WGS84 in decimal degrees to EPSG:3031 Antarctic Polar Stereographic in meters.
- Parameters
df (pd.DataFrame) – input dataframe with latitude and longitude columns
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input (list, optional) – set names for input columns, by default [“lon”, “lat”]
output (list, optional) – set names for output columns, by default [“x”, “y”]
- Returns
Updated dataframe with new easting and northing columns or np.ndarray in format [e, w, n, s]
- Return type
pd.DataFrame or np.ndarray
- make_grid(region: Union[str, numpy.ndarray], spacing: float, value: float, name: str)[source]#
Create a grid with 1 variable by defining a region, spacing, name and constant value
- Parameters
region (Union[str, np.ndarray]) – GMT format region for the inverion, by default is extent of gravity data,
spacing (float) – spacing for grid
value (float) – constant value to use for variable
name (str) – name for variable
- Returns
Returns a xr.DataArray with 1 variable of constant value.
- Return type
xr.DataArray
- mask_from_shp(shapefile: str, invert: bool = True, xr_grid=None, grid_file: Optional[str] = None, region=None, spacing=None, masked: bool = False, crs: str = 'epsg:3031')[source]#
Create a mask or a masked grid from area inside or outside of a closed shapefile.
- Parameters
shapefile (str) – path to .shp filename, must by in same directory as accompanying files : .shx, .prj, .dbf, should be a closed polygon file.
invert (bool, optional) – choose whether to mask data outside the shape (False) or inside the shape (True), by default True (masks inside of shape)
xr_grid (xarray.DataArray, optional) – _xarray.DataArray; to use to define region, or to mask, by default None
grid_file (str, optional) – path to a .nc or .tif file to use to define region or to mask, by default None
region (str or np.ndarray, optional) – GMT region string or 1x4 ndarray in meters to create a dummy grid if none are supplied, by default None
spacing (str or int, optional) – grid spacing in meters to create a dummy grid if none are supplied, by default None
masked (bool, optional) – choose whether to return the masked grid (True) or the mask itself (False), by default False
crs (str, optional) – if grid is provided, rasterio needs to assign a coordinate reference system via an epsg code, by default “epsg:3031”
- Returns
Returns either a masked grid, or the mask grid itself.
- Return type
xarray.DataArray
- raps(data: Union[pandas.core.frame.DataFrame, xarray.core.dataarray.DataArray, xarray.core.dataset.Dataset], names: numpy.ndarray, plot_type: str = 'mpl', filter: Optional[str] = None, **kwargs)[source]#
Compute and plot the Radially Averaged Power Spectrum input data.
- Parameters
data (Union[pd.DataFrame, str, list, xr.Dataset, xr.Dataarray]) – if dataframe: need with columns ‘x’, ‘y’, and other columns to calc RAPS for. if str: should be a .nc or .tif file. if list: list of grids or filenames.
names (np.ndarray) – names of pd.dataframe columns, xr.dataset variables, xr.dataarray variable, or files to calculate and plot RAPS for.
plot_type (str, optional) – choose whether to plot with PyGMT or matplotlib, by default ‘mpl’
filter (str) – GMT string to use for pre-filtering data, ex. “c100e3+h” is a 100km low-pass cosine filter, by default is None.
- Keyword Arguments
region (Union[str, np.ndarray]) – grid region if input is not a grid
spacing (float) – grid spacing if input is not a grid
- reg_str_to_df(input, names=['x', 'y'])[source]#
Convert GMT region string [e, w, n, s] to pandas dataframe with coordinates of region corners
- Parameters
input (np.ndarray) – Array of 4 strings in GMT format; [e, w, n, s]
names (list, optional) – Names of names to use for easting and northing, by default [“x”, “y”]
- Returns
Dataframe with easting and northing columns, and a row for each corner of the region.
- Return type
pd.DataFrame
- set_proj(region: str, fig_height: float = 10) str [source]#
Gives GMT format projection string from region and figure height. Inspired from https://github.com/mrsiegfried/Venturelli2020-GRL.
- Parameters
region (Union[str or np.ndarray]) – GMT-format region str or list (e, w, n, s) in meters EPSG:3031
fig_height (float) – desired figure height in cm
- Returns
returns a list of the following variables: (proj, proj_latlon, fig_width, fig_height)
- Return type
list