polartoolkit.utils#
- alter_region(starting_region, zoom=0, n_shift=0, w_shift=0, buffer=0, print_reg=False)[source]#
Change a bounding region by shifting the box east/west or north/south, zooming in or out, or adding a separate buffer region.
- Parameters:
starting_region (tuple[float, float, float, float]) – 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 east 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 two tuples: region, buffer_region
- Return type:
tuple[tuple[float, float, float, float], tuple[float, float, float, float]]
- block_reduce(df, reduction, input_coord_names=('x', 'y'), input_data_names=None, **kwargs)[source]#
perform a block reduction of a dataframe.
- Parameters:
df (pd.DataFrame) – data to block reduce
reduction (Callable) – function to use in reduction, e.g. np.mean
input_coord_names (tuple[str, str], optional) – strings of coordinate column names, by default (“x”, “y”)
input_data_names (Any | None, optional) – strings of data column names, by default None
kwargs (
Any)
- Returns:
a block-reduced dataframe
- Return type:
pd.DataFrame
- change_reg(grid)[source]#
Use GMT grdedit to change the registration type in the metadata.
- Parameters:
grid (xr.DataArray) – input grid to change the reg for.
- Returns:
returns a xr.DataArray with switch reg type.
- Return type:
xr.DataArray
- coherency(grids, label, **kwargs)[source]#
Compute and plot the Radially Averaged Power Spectrum input data.
- Parameters:
- Keyword Arguments:
- Return type:
- dd2dms(dd)[source]#
Convert decimal degrees to minutes, seconds. Modified from https://stackoverflow.com/a/10286690/18686384
- epsg3031_to_latlon(df, reg=False, input_coord_names=('x', 'y'), output_coord_names=('lon', 'lat'))[source]#
Convert coordinates from EPSG:3031 Antarctic Polar Stereographic in meters to EPSG:4326 WGS84 in decimal degrees.
- Parameters:
df (pd.DataFrame or list[Any]) – input dataframe with easting and northing columns, or list [x,y]
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input_coord_names (list, optional) – set names for input coordinate columns, by default [“x”, “y”]
output_coord_names (list, optional) – set names for output coordinate columns, by default [“lon”, “lat”]
- Returns:
Updated dataframe with new latitude and longitude columns, NDArray in format [e, w, n, s], or list in format [lat, lon]
- Return type:
- get_fig_height()[source]#
Get the height of the current PyGMT figure instance.
- Returns:
height of the figure
- Return type:
- get_fig_width()[source]#
Get the width of the current PyGMT figure instance.
- Returns:
width of the figure
- Return type:
- get_grid_info(grid, print_info=False)[source]#
Returns information of the specified grid.
- Parameters:
grid (str or xarray.DataArray) – Input grid to get info from. Filename string or loaded grid.
print_info (bool, optional) – If true, prints out the grid info, by default False
- Returns:
(string of grid spacing, array with the region boundaries, data min, data max, grid registration)
- Return type:
- get_min_max(grid, shapefile=None, robust=False)[source]#
Get a grids max and min values.
- Parameters:
- Returns:
returns the min and max values.
- Return type:
- gmt_str_to_list(region)[source]#
convert a tuple of floats representing the boundaries of a region into a GMT-style region string
- grd_blend(grid1, grid2)[source]#
Use GMT grdblend to blend 2 grids into 1.
- Parameters:
grid1 (xr.DataArray) – input grid to change the reg for.
grid2 (xr.DataArray) – input grid to change the reg for.
- Returns:
returns a blended grid.
- Return type:
xr.DataArray
- grd_compare(da1, da2, plot=False, plot_type='pygmt', robust=False, **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
plot (bool, optional) – plot the results, by default False
plot_type (str, optional) – choose the style of plot, by default is pygmt, can choose xarray for faster, simpler plots.
robust (bool, optional) – use xarray robust color lims instead of min and max, by default is False.
kwargs (
Any)
- 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.
region (tuple[float, float, float, float]) – choose a specific region to compare.
rmse_in_title (bool) – add the RMSE to the title, by default is True.
- Returns:
three xr.DataArrays: (diff, resampled grid1, resampled grid2)
- Return type:
tuple[xr.DataArray, xr.DataArray, xr.DataArray]
- grd_mask(df, spacing, region, clobber='o', values='0/0/1', radius='0c')[source]#
Wrapper for GMT grdmask function
- Parameters:
- Returns:
_description_
- Return type:
xr.DataArray
- grd_trend(da, coords=('x', 'y', 'z'), deg=1, plot=False, plot_type='pygmt', **kwargs)[source]#
Fit an arbitrary order trend to a grid and use it to detrend.
- Parameters:
da (xr.DataArray) – input grid
coords (tuple[str, str, str], optional) – coordinate names of the supplied grid, by default [‘x’, ‘y’, ‘z’]
deg (int, optional) – trend order to use, by default 1
plot (bool, optional) – plot the results, by default False
plot_type (str, by default "pygmt") – choose to plot results with pygmt or xarray
kwargs (
Any)
- Returns:
returns xr.DataArrays of the fitted surface, and the detrended grid.
- Return type:
tuple[xr.DataArray, xr.DataArray]
- latlon_to_epsg3031(df, reg=False, input_coord_names=('lon', 'lat'), output_coord_names=('x', 'y'))[source]#
Convert coordinates from EPSG:4326 WGS84 in decimal degrees to EPSG:3031 Antarctic Polar Stereographic in meters.
- Parameters:
df (pd.DataFrame or NDArray[Any, Any]) – input dataframe with latitude and longitude columns
reg (bool, optional) – if true, returns a GMT formatted region string, by default False
input_coord_names (list, optional) – set names for input coordinate columns, by default [“lon”, “lat”]
output_coord_names (list, optional) – set names for output coordinate columns, by default [“x”, “y”]
- Returns:
Updated dataframe with new easting and northing columns or NDArray in format [e, w, n, s]
- Return type:
- make_grid(region, spacing, value, name)[source]#
Create a grid with 1 variable by defining a region, spacing, name and constant value
- mask_from_polygon(polygon, invert=False, drop_nans=False, grid=None, region=None, spacing=None, **kwargs)[source]#
convert the output of regions.draw_region to a mask or use it to mask a grid
- Parameters:
polygon (list) – list of polygon vertices
invert (bool, optional) – reverse the sense of masking, by default False
drop_nans (bool, optional) – drop nans after masking, by default False
grid (Union[str, xr.DataArray], optional) – grid to mask, by default None
region (tuple[float, float, float, float], optional) – region to create a grid if none is supplied, by default None
spacing (int, optional) – spacing to create a grid if none is supplied, by default None
kwargs (
Any)
- Returns:
masked grid or mask grid with 1’s inside the mask.
- Return type:
xr.DataArray
- mask_from_shp(shapefile, invert=True, xr_grid=None, grid_file=None, region=None, spacing=None, masked=False, crs='epsg:3031', pixel_register=True, input_coord_names=('x', 'y'))[source]#
Create a mask or a masked grid from area inside or outside of a closed shapefile.
- Parameters:
shapefile (str or gpd.geodataframe.GeoDataFrame]) – either path to .shp filename, must by in same directory as accompanying files : .shx, .prj, .dbf, should be a closed polygon file, or shapefile which as already been loaded into a geodataframe.
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 (xr.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 tuple[float, float, float, float], optional) – bounding region in GMT format 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”
pixel_register (
bool)
- Returns:
Returns either a masked grid, or the mask grid itself.
- Return type:
- points_inside_region(df, region, names=('x', 'y'), reverse=False)[source]#
return a subset of a dataframe which is within a region
- Parameters:
df (pd.DataFrame) – dataframe with columns ‘x’,’y’ to use for defining if within region
region (tuple[float, float, float, float]) – bounding region in GMT format for bounds of new subset dataframe
names (tuple[str, str], optional) – column names to use for x and y coordinates, by default (“x”, “y”)
reverse (bool, optional) – if True, will return points outside the region, by default False
- Returns:
returns a subset dataframe
- Return type:
pd.DataFrame
- polygon_to_region(polygon)[source]#
convert the output of regions.draw_region to bounding region in EPSG:3031
- random_color()[source]#
generate a random color in format R/G/B
- Returns:
returns a random color string
- Return type:
- raps(data, names, plot_type='mpl', filter_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 (NDArray[Any, Any]) – 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 (str) – GMT string to use for pre-filtering data, ex. “c100e3+h” is a 100km low-pass cosine filter, by default is None.
kwargs (
Any)
- Keyword Arguments:
- Return type:
- region_to_bounding_box(region)[source]#
Convert GMT region in format [e, w, n, s] 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
- region_to_df(region, coord_names=('x', 'y'), reverse=False)[source]#
Convert region bounds in GMT format [e, w, n, s] to pandas dataframe with coordinates of region corners, or reverse this if reverse is True.
- Parameters:
region (tuple[Any, Any, Any, Any] | pd.DataFrame) – Tuple of bounding region in GMT format; [e, w, n, s], or, if reverse is True, a DataFrame with coordinate columns with names set by cood_names
coord_names (tuple[str, str], optional) – names of input or output coordinate columns, by default (“x”, “y”)
reverse (bool, optional) – If True, convert from df to region tuple, else, convert from region tuple to df, by default False
- Returns:
Dataframe with easting and northing columns, and a row for each corner of the region, or, if reverse is True, an array in the format [e,w,n,s].
- Return type:
- region_xy_to_ll(region, dms=False)[source]#
Convert GMT region in format [e, w, n, s] in EPSG:3031 to lat / lon
- Parameters:
- Returns:
region boundaries in GMT format; [e, w, n, s] in lat, lon
- Return type:
- rmse(data, as_median=False)[source]#
function to give the root mean/median squared error (RMSE) of data
- set_proj(region, fig_height=15, fig_width=None)[source]#
Gives GMT format projection string from region and figure height or width. Inspired from mrsiegfried/Venturelli2020-GRL.
- Parameters:
- Returns:
returns a tuple of the following variables: proj, proj_latlon, fig_width, fig_height
- Return type:
- shapes_to_df(shapes)[source]#
convert the output of regions.draw_region and profile.draw_lines to a dataframe of x and y points
- Parameters:
shapes (list) – list of vertices
- Returns:
Dataframe with x, y, and shape_num.
- Return type:
pd.DataFrame
- square_subplots(n)[source]#
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.