polartoolkit.utils
==================

.. py:module:: polartoolkit.utils


Attributes
----------

.. autoapisummary::

   polartoolkit.utils.ENGINE


Functions
---------

.. autoapisummary::

   polartoolkit.utils.default_hemisphere
   polartoolkit.utils.rmse
   polartoolkit.utils.get_grid_info
   polartoolkit.utils.dd2dms
   polartoolkit.utils.region_to_df
   polartoolkit.utils.region_xy_to_ll
   polartoolkit.utils.region_ll_to_xy
   polartoolkit.utils.region_to_bounding_box
   polartoolkit.utils.epsg3031_to_latlon
   polartoolkit.utils.epsg3413_to_latlon
   polartoolkit.utils.latlon_to_epsg3031
   polartoolkit.utils.latlon_to_epsg3413
   polartoolkit.utils.reproject
   polartoolkit.utils.points_inside_region
   polartoolkit.utils.block_reduce
   polartoolkit.utils.nearest_grid_fill
   polartoolkit.utils.filter_grid
   polartoolkit.utils.points_inside_shp
   polartoolkit.utils.mask_from_shp
   polartoolkit.utils.alter_region
   polartoolkit.utils.set_proj
   polartoolkit.utils.grd_trend
   polartoolkit.utils.get_combined_min_max
   polartoolkit.utils.grd_compare
   polartoolkit.utils.make_grid
   polartoolkit.utils.square_subplots
   polartoolkit.utils.random_color
   polartoolkit.utils.subset_grid
   polartoolkit.utils.get_min_max
   polartoolkit.utils.shapes_to_df
   polartoolkit.utils.polygon_to_region
   polartoolkit.utils.mask_from_polygon
   polartoolkit.utils.change_reg
   polartoolkit.utils.grd_blend
   polartoolkit.utils.get_fig_width
   polartoolkit.utils.get_fig_height
   polartoolkit.utils.gmt_str_to_list


Module Contents
---------------

.. py:data:: ENGINE
   :value: 'pyogrio'


.. py:function:: default_hemisphere(hemisphere)

   Returns the default hemisphere set in the users environment variables or raises a
   error.

   :param hemisphere: hemisphere to use, either "north" or "south", or None to use the default set in
                      the users environment variables.
   :type hemisphere: str | None

   :returns: hemisphere to use, either "north" or "south"
   :rtype: str


.. py:function:: rmse(data, as_median = False)

   function to give the root mean/median squared error (RMSE) of data

   :param data: input data
   :type data: numpy.ndarray[typing.Any, typing.Any]
   :param as_median: choose to give root median squared error instead, by default False
   :type as_median: bool, optional

   :returns: RMSE value
   :rtype: float


.. py:function:: get_grid_info(grid, print_info = False)

   Returns information of the specified grid.

   :param grid: Input grid to get info from. Filename string or loaded grid.
   :type grid: str or xarray.DataArray
   :param print_info: If true, prints out the grid info, by default False
   :type print_info: bool, optional

   :returns: (string of grid spacing,
             array with the region boundary,
             data min,
             data max,
             grid registration)
   :rtype: tuple


.. py:function:: dd2dms(dd)

   Convert decimal degrees to minutes, seconds. Modified from
   https://stackoverflow.com/a/10286690/18686384

   :param dd: input decimal degrees
   :type dd: float

   :returns: degrees in the format "DD:MM:SS"
   :rtype: str


.. py:function:: region_to_df(region, coord_names = ('easting', 'northing'), reverse = False)

   Convert region bounds in format [xmin, xmax, ymin, ymax] to pandas dataframe with
   coordinates of region corners, or reverse this if `reverse` is True.

   :param region: bounding region in format [xmin, xmax, ymin, ymax] or, if `reverse` is True,
                  a DataFrame with coordinate columns with names set by `cood_names`
   :type region: tuple[typing.Any, typing.Any, typing.Any, typing.Any] | pandas.DataFrame
   :param coord_names: names of input or output coordinate columns, by default ("easting", "northing")
   :type coord_names: tuple[str, str], optional
   :param reverse: If True, convert from df to region tuple, else, convert from region tuple to df,
                   by default False
   :type reverse: bool, optional

   :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
             [xmin, xmax, ymin, ymax].
   :rtype: tuple[typing.Any, typing.Any, typing.Any, typing.Any] | pandas.DataFrame


.. py:function:: region_xy_to_ll(region, hemisphere = None, dms = False)

   Convert region in format [xmin, xmax, ymin, ymax] in projected meters to lat / lon

   :param hemisphere: choose between the "north" or "south" hemispheres
   :type hemisphere: str, optional,
   :param region: region boundaries in format [xmin, xmax, ymin, ymax] in meters
   :type region: tuple[typing.Any, typing.Any, typing.Any, typing.Any]
   :param dms: if True, will return results as deg:min:sec instead of decimal degrees, by
               default False
   :type dms: bool

   :returns: region boundaries in format [lon_min, lon_max, lat_min, lat_max]
   :rtype: tuple[typing.Any, typing.Any, typing.Any, typing.Any]


.. py:function:: region_ll_to_xy(region, hemisphere = None)

   Convert region in format [lon_min, lon_max, lat_min, lat_max] to projected meters in
   the north or south polar stereographic projections.

   :param hemisphere: choose between the "north" or "south" hemispheres
   :type hemisphere: str, optional,
   :param region: region boundaries in format [xmin, xmax, ymin, ymax] in decimal degrees
   :type region: tuple[float, float, float, float]

   :returns: region boundaries in format [x_min, x_max, y_min, y_max]
   :rtype: tuple[float, float, float, float]


.. py:function:: 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

   :param region: region boundaries in format [xmin, xmax, ymin, ymax] in meters or degrees.
   :type region: tuple[typing.Any, typing.Any, typing.Any, typing.Any]

   :returns: region boundaries in bounding box format.
   :rtype: tuple[typing.Any, typing.Any, typing.Any, typing.Any]


.. py:function:: epsg3031_to_latlon(df, reg = False, input_coord_names = None, output_coord_names = ('lon', 'lat'))

   Convert coordinates from EPSG:3031 Antarctic Polar Stereographic in meters to
   EPSG:4326 WGS84 in decimal degrees.

   :param df: input dataframe with easting and northing columns, or tuple [x,y]
   :type df: pandas.DataFrame or tuple[typing.Any]
   :param reg: if true, returns a GMT formatted region string, by default False
   :type reg: bool, optional
   :param input_coord_names: set names for input coordinate columns, by default ("x", "y") or
                             ("easting", "northing")
   :type input_coord_names: tuple | None, optional
   :param output_coord_names: set names for output coordinate columns, by default ("lon", "lat")
   :type output_coord_names: tuple | None, optional

   :returns: Updated dataframe with new latitude and longitude columns, numpy.ndarray in
             format [xmin, xmax, ymin, ymax], or tuple in format [lat, lon]
   :rtype: pandas.DataFrame or tuple[typing.Any]


.. py:function:: epsg3413_to_latlon(df, reg = False, input_coord_names = None, output_coord_names = ('lon', 'lat'))

   Convert coordinates from EPSG:3413 North Polar Stereographic in meters to
   EPSG:4326 WGS84 in decimal degrees.

   :param df: input dataframe with easting and northing columns, or tuple [x,y]
   :type df: pandas.DataFrame or tuple[typing.Any]
   :param reg: if true, returns a GMT formatted region string, by default False
   :type reg: bool, optional
   :param input_coord_names: set names for input coordinate columns, by default ("x", "y") or
                             ("easting", "northing")
   :type input_coord_names: tuple | None, optional
   :param output_coord_names: set names for output coordinate columns, by default ("lon", "lat")
   :type output_coord_names: tuple | None, optional

   :returns: Updated dataframe with new latitude and longitude columns, numpy.ndarray in
             format [xmin, xmax, ymin, ymax], or tuple in format [lat, lon]
   :rtype: pandas.DataFrame or tuple[typing.Any]


.. py:function:: latlon_to_epsg3031(df, reg = False, input_coord_names = None, output_coord_names = ('easting', 'northing'))

   Convert coordinates from EPSG:4326 WGS84 in decimal degrees to EPSG:3031 Antarctic
   Polar Stereographic in meters.

   :param df: input dataframe with latitude and longitude columns
   :type df: pandas.DataFrame or numpy.ndarray[typing.Any, typing.Any]
   :param reg: if true, returns a GMT formatted region string, by default False
   :type reg: bool, optional
   :param input_coord_names: set names for input coordinate columns, by default ("lon", "lat")
   :type input_coord_names: tuple | None, optional
   :param output_coord_names: set names for output coordinate columns, by default ("easting", "northing")
   :type output_coord_names: tuple | None, optional

   :returns: Updated dataframe with new easting and northing columns or numpy.ndarray in
             format [xmin, xmax, ymin, ymax]
   :rtype: pandas.DataFrame or numpy.ndarray[typing.Any, typing.Any]


.. py:function:: latlon_to_epsg3413(df, reg = False, input_coord_names = None, output_coord_names = ('easting', 'northing'))

   Convert coordinates from EPSG:4326 WGS84 in decimal degrees to EPSG:3413 North Polar
   Stereographic in meters.

   :param df: input dataframe with latitude and longitude columns
   :type df: pandas.DataFrame or numpy.ndarray[typing.Any, typing.Any]
   :param reg: if true, returns a GMT formatted region string, by default False
   :type reg: bool, optional
   :param input_coord_names: set names for input coordinate columns, by default ("lon", "lat")
   :type input_coord_names: tuple | None, optional
   :param output_coord_names: set names for output coordinate columns, by default ("easting", "northing")
   :type output_coord_names: tuple | None, optional

   :returns: Updated dataframe with new easting and northing columns or numpy.ndarray in
             format [xmin, xmax, ymin, ymax]
   :rtype: pandas.DataFrame or numpy.ndarray[typing.Any, typing.Any]


.. py:function:: reproject(df, input_crs, output_crs, input_coord_names = None, output_coord_names = None, reg = False)

   Convert coordinates from input CRS to output CRS. Coordinates can be supplied as a
   dataframe with coordinate columns set by input_coord_names, or as a tuple of a list
   of x coordinates and a list of y coordinates.

   :param df: input dataframe with easting/longitude and northing/latitude columns, or tuple
              [x,y]
   :type df: pandas.DataFrame or tuple[typing.Any]
   :param input_crs: input CRS in EPSG format, e.g. "epsg:4326"
   :type input_crs: str
   :param output_crs: output CRS in EPSG format, e.g. "epsg:3413"
   :type output_crs: str
   :param reg: if true, returns a GMT formatted region string, by default False
   :type reg: bool, optional
   :param input_coord_names: set names for input coordinate columns, by default "x"/"y" or
                             "easting"/"northing" if input_crs is "epsg:3413" or "epsg:3031", or if input_crs
                             is "epsg_4326", "lon"/"lat"
   :type input_coord_names: tuple, optional
   :param output_coord_names: set names for output coordinate columns, by default "x"/"y" if output_crs is
                              "epsg:3413" or "epsg:3031", or if output_crs is "epsg_4326", "lon"/"lat".
   :type output_coord_names: tuple, optional

   :returns: Updated dataframe with new latitude and longitude columns, numpy.ndarray in
             format [xmin, xmax, ymin, ymax], or tuple in format [lat, lon]
   :rtype: pandas.DataFrame or tuple[typing.Any]


.. py:function:: points_inside_region(df, region, names = ('x', 'y'), reverse = False)

   return a subset of a dataframe which is within a region

   :param df: dataframe with coordinate columns to use for defining if within region
   :type df: pandas.DataFrame
   :param region: bounding region in format [xmin, xmax, ymin, ymax] for bounds of new subset
                  dataframe
   :type region: tuple[float, float, float, float]
   :param names: column names to use for x and y coordinates, by default ("x", "y") or
                 ("easting", "northing")
   :type names: tuple[str, str], optional
   :param reverse: if True, will return points outside the region, by default False
   :type reverse: bool, optional

   :returns: returns a subset dataframe
   :rtype: pandas.DataFrame


.. py:function:: block_reduce(df, reduction, input_coord_names = ('x', 'y'), input_data_names = None, **kwargs)

   perform a block reduction of a dataframe.

   :param df: data to block reduce
   :type df: pandas.DataFrame
   :param reduction: function to use in reduction, e.g. np.mean
   :type reduction: typing.Callable
   :param input_coord_names: strings of coordinate column names, by default ("x", "y") or
                             ("easting", "northing")
   :type input_coord_names: tuple[str, str], optional
   :param input_data_names: strings of data column names, by default None
   :type input_data_names: typing.Any | None, optional

   :returns: a block-reduced dataframe
   :rtype: pandas.DataFrame


.. py:function:: nearest_grid_fill(grid, method = 'verde', crs = None)

   fill missing values in a grid with the nearest value.

   :param grid: grid with missing values
   :type grid: xarray.DataArray
   :param method: choose method of filling, by default "verde"
   :type method: str, optional
   :param crs: if method is 'rioxarray', provide the crs of the grid, in format 'epsg:xxxx',
               by default None
   :type crs: str | None, optional

   :returns: filled grid
   :rtype: xarray.DataArray


.. py:function:: filter_grid(grid, filter_width = None, filt_type = 'lowpass', pad_width_factor = 3, pad_mode = 'linear_ramp', pad_constant = None, pad_end_values = None)

   Apply a spatial filter to a grid.

   :param grid: grid to filter the values of
   :type grid: xarray.DataArray
   :param filt_type: type of filter to use from 'lowpass', 'highpass' 'up_deriv', 'easting_deriv',
                     'northing_deriv', or 'total_gradient' by default "lowpass"
   :type filt_type: str, optional
   :param filt_type: type of filter to use, by default "lowpass"
   :type filt_type: str, optional
   :param pad_width_factor: factor of grid width to pad the grid by, by default 3, which equates to a pad
                            with a width of 1/3 of the grid width.
   :type pad_width_factor: int, optional
   :param pad_mode: mode of padding, can be "linear", by default "linear_ramp"
   :type pad_mode: str, optional
   :param pad_constant: constant value to use for padding, by default None
   :type pad_constant: float | None, optional
   :param pad_end_values: value to use for end of padding if pad_mode is "linear_ramp", by default None
   :type pad_end_values: float | None, optional

   :returns: a filtered grid
   :rtype: xarray.DataArray


.. py:function:: points_inside_shp(points, shapefile, crs = None, coord_names = None, hemisphere = None)

   Add a column to a dataframe indicating whether each point is inside a shapefile.

   :param points: dataframe with coordinate columns specified by coord_names to use for defining
                  if within shapefile
   :type points: pd.DataFrame | gpd.geodataframe.GeoDataFrame
   :param shapefile: shapefile to use for defining if point are within it or not
   :type shapefile: gpd.geodataframe.GeoDataFrame
   :param crs: if points is not a geodataframe, crs to use to convert into a geodataframe, by
               default None
   :type crs: str | None, optional
   :param coord_names: names of coordinate columns, by default 'x' and 'y' or 'easting' and 'northing'
   :type coord_names: tuple[str, str] | None, optional
   :param hemisphere: hemisphere to use for automatically detecting crs, by default None
   :type hemisphere: str | None, optional

   :returns: Dataframe with a new column 'inside' which is True if the point is inside the
             shapefile
   :rtype: pd.DataFrame | gpd.geodataframe.GeoDataFrame


.. py:function:: mask_from_shp(shapefile, hemisphere = None, invert = True, xr_grid = None, grid_file = None, region = None, spacing = None, masked = False, pixel_register = True, input_coord_names = ('easting', 'northign'))

   Create a mask or a masked grid from area inside or outside of a closed shapefile.

   :param shapefile: 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.
   :type shapefile: str or geopandas.GeoDataFrame
   :param hemisphere: choose "north" for EPSG:3413 or "south" for EPSG:3031
   :type hemisphere: str, optional
   :param invert: choose whether to mask data outside the shape (False) or inside the shape
                  (True), by default True (masks inside of shape)
   :type invert: bool, optional
   :param xr_grid: _xarray.DataArray; to use to define region, or to mask, by default None
   :type xr_grid: xarray.DataArray, optional
   :param grid_file: path to a .nc or .tif file to use to define region or to mask, by default None
   :type grid_file: str, optional
   :param region: bounding region in format [xmin, xmax, ymin, ymax] in meters to create a dummy
                  grid if none are supplied, by default None
   :type region: str or tuple[float, float, float, float], optional
   :param spacing: grid spacing in meters to create a dummy grid if none are supplied, by default
                   None
   :type spacing: str or int, optional
   :param masked: choose whether to return the masked grid (True) or the mask itself (False), by
                  default False
   :type masked: bool, optional
   :param pixel_register: choose whether the grid is pixel registered (True) or grid registered (False),
                          by default True
   :type pixel_register: bool, optional
   :param input_coord_names: set names for input coordinate columns, by default ("easting", "northing")
   :type input_coord_names: tuple[str, str], optional

   :returns: Returns either a masked grid, or the mask grid itself.
   :rtype: xarray.DataArray


.. py:function:: alter_region(starting_region, **kwargs)

   deprecated function, use regions.alter_region instead


.. py:function:: set_proj(region, hemisphere = None, fig_height = 15, fig_width = None)

   Gives GMT format projection string from region and figure height or width.
   Inspired from https://github.com/mrsiegfried/Venturelli2020-GRL.

   :param region: region boundaries in format [xmin, xmax, ymin, ymax] in projected meters
   :type region: tuple[float, float, float, float]
   :param hemisphere: set whether to lat lon projection is for "north" hemisphere (EPSG:3413) or
                      "south" hemisphere (EPSG:3031)
   :type hemisphere: str, optional
   :param fig_height: desired figure height in cm
   :type fig_height: float
   :param fig_width: instead of using figure height, set the projection based on figure width in cm,
                     by default is None
   :type fig_width: float

   :returns: returns a tuple of the following variables: proj, proj_latlon, fig_width,
             fig_height
   :rtype: tuple


.. py:function:: grd_trend(da, coords = ('x', 'y', 'z'), deg = 1, plot = False, **kwargs)

   Fit an arbitrary order trend to a grid and use it to detrend.

   :param da: input grid
   :type da: xarray.DataArray
   :param coords: coordinate names of the supplied grid, by default ['x', 'y', 'z']
   :type coords: tuple[str, str, str], optional
   :param deg: trend order to use, by default 1
   :type deg: int, optional
   :param plot: plot the results, by default False
   :type plot: bool, optional

   :returns: returns xarray.DataArrays of the fitted surface, and the detrended grid.
   :rtype: tuple[xarray.DataArray, xarray.DataArray]


.. py:function:: get_combined_min_max(values, shapefile = None, robust = False, region = None, hemisphere = None, absolute = False, robust_percentiles = (0.02, 0.98))

   Get a grids max and min values.

   :param values: values to get min and max for
   :type values: tuple[xarray.DataArray | pandas.Series | numpy.ndarray]
   :param shapefile: path or loaded shapefile to use for a mask, by default None
   :type shapefile: Union[str or geopandas.GeoDataFrame], optional
   :param robust: choose whether to return the 2nd and 98th percentile values, instead of the
                  min/max
   :type robust: bool, optional
   :param region: give a subset region to get min and max values from, in format
                  [xmin, xmax, ymin, ymax], by default None
   :type region: tuple[float, float, float, float], optional
   :param hemisphere: set whether to lat lon projection is for "north" hemisphere (EPSG:3413) or
                      "south" hemisphere (EPSG:3031)
   :type hemisphere: str, optional
   :param absolute: choose whether to return the absolute min and max values, by default False
   :type absolute: bool, optional
   :param robust_percentiles: percentiles to use for robust min and max values, by default (0.02, 0.98)
   :type robust_percentiles: tuple[float, float], optional

   :returns: returns the min and max values.
   :rtype: tuple[float, float]


.. py:function:: grd_compare(da1, da2, plot = True, plot_type = None, robust = False, **kwargs)

   Find the difference between 2 grids and plot the results, if necessary resample and
   cut grids to match

   :param da1: first grid, loaded grid of filename
   :type da1: xarray.DataArray or str
   :param da2: second grid, loaded grid of filename
   :type da2: xarray.DataArray or str
   :param plot: plot the results, by default True
   :type plot: bool, optional
   :param plot_type: this argument has been deprecated and will default to 'pygmt'
   :type plot_type: typing.Any or None, optional
   :param robust: use xarray robust color lims instead of min and max, by default is False.
   :type robust: bool, optional

   :keyword shp_mask: shapefile filename to use to mask the grids for setting the color range.
   :kwtype shp_mask: str
   :keyword robust: use xarray robust color lims instead of min and max, by default is False.
   :kwtype robust: bool
   :keyword region: choose a specific region to compare, in format [xmin, xmax, ymin, ymax].
   :kwtype region: tuple[float, float, float, float]
   :keyword rmse_in_title: add the RMSE to the title, by default is True.
   :kwtype rmse_in_title: bool
   :keyword cpt_lims: set the colorbar limits for the two grids.
   :kwtype cpt_lims: tuple[float, float]
   :keyword diff_lims: set the colorbar limits for the difference grid.
   :kwtype diff_lims: tuple[float, float]

   :returns: three xarray.DataArrays: (diff, resampled grid1, resampled grid2)
   :rtype: tuple[xarray.DataArray, xarray.DataArray, xarray.DataArray]


.. py:function:: make_grid(region, spacing, value, name)

   Create a grid with 1 variable by defining a region, spacing, name and constant value

   :param region: bounding region in format [xmin, xmax, ymin, ymax]
   :type region: tuple[float, float, float, float]
   :param spacing: spacing for grid
   :type spacing: float
   :param value: constant value to use for variable
   :type value: float
   :param name: name for variable
   :type name: str

   :returns: Returns a xarray.DataArray with 1 variable of constant value.
   :rtype: xarray.DataArray


.. py:function:: square_subplots(n)

   From https://github.com/matplotlib/grid-strategy/blob/master/src/grid_strategy/strategies.py
   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.

   :param n: The number of total plots in the subplot
   :type n: int

   :returns: Returns a tuple in the format (number of rows, number of columns), so for
             example a 3 x 2 grid would be represented as ``(3, 3)``, because there are 2
             rows of length 3.
   :rtype: tuple[int, int]


.. py:function:: random_color()

   generate a random color in format R/G/B

   :returns: returns a random color string, for example '95/226/100'
   :rtype: str


.. py:function:: subset_grid(grid, region)

   Return a subset of a grid based on a region

   :param grid: grid to be clipped
   :type grid: xarray.DataArray
   :param region: region to clip to, in format [xmin, xmax, ymin, ymax]
   :type region: tuple[float, float, float, float]

   :returns: clipped grid
   :rtype: xarray.DataArray


.. py:function:: get_min_max(values, shapefile = None, robust = False, region = None, hemisphere = None, absolute = False, robust_percentiles = (0.02, 0.98))

   Get a grids max and min values.

   :param values: values to find min or max for
   :type values: xarray.DataArray or pandas.Series or numpy.ndarray
   :param shapefile: path or loaded shapefile to use for a mask, by default None
   :type shapefile: Union[str or geopandas.GeoDataFrame], optional
   :param robust: choose whether to return the 2nd and 98th percentile values, instead of the
                  min/max
   :type robust: bool, optional
   :param region: give a subset region to get min and max values from, in format
                  [xmin, xmax, ymin, ymax], by default None
   :type region: tuple[float, float, float, float], optional
   :param hemisphere: set whether to lat lon projection is for "north" hemisphere (EPSG:3413) or
                      "south" hemisphere (EPSG:3031)
   :type hemisphere: str, optional
   :param absolute: return the absolute min and max values, by default False
   :type absolute: bool, optional
   :param robust_percentiles: decimal percentiles to use for robust min and max, by default (0.02, 0.98)
   :type robust_percentiles: tuple[float, float], optional

   :returns: returns the min and max values.
   :rtype: tuple[float, float]


.. py:function:: shapes_to_df(shapes, hemisphere = None)

   convert the output of `regions.draw_region` and `profiles.draw_lines` to a dataframe
   of easting and northing points

   :param hemisphere: choose between the "north" or "south" hemispheres
   :type hemisphere: str, optional
   :param shapes: list of vertices
   :type shapes: list

   :returns: Dataframe with easting, northing, and shape_num.
   :rtype: pandas.DataFrame


.. py:function:: polygon_to_region(polygon, hemisphere = None)

   convert the output of `regions.draw_region` to bounding region in EPSG:3031 for the
   south hemisphere and EPSG:3413 for the north hemisphere.

   :param polyon: list of polygon vertices
   :type polyon: list
   :param hemisphere: choose between the "north" or "south" hemispheres
   :type hemisphere: str, optional

   :returns: region in format in format [xmin, xmax, ymin, ymax]
   :rtype: tuple[float, float, float, float]


.. py:function:: mask_from_polygon(polygon, hemisphere = None, invert = False, drop_nans = False, grid = None, region = None, spacing = None, **kwargs)

   convert the output of `regions.draw_region` to a mask or use it to mask a grid

   :param polygon: list of polygon vertices
   :type polygon: list
   :param hemisphere: choose between the "north" or "south" hemispheres
   :type hemisphere: str, optional
   :param invert: reverse the sense of masking, by default False
   :type invert: bool, optional
   :param drop_nans: drop nans after masking, by default False
   :type drop_nans: bool, optional
   :param grid: grid to mask, by default None
   :type grid: Union[str, xarray.DataArray], optional
   :param region: region to create a grid if none is supplied, in format [xmin, xmax, ymin, ymax],
                  by default None
   :type region: tuple[float, float, float, float], optional
   :param spacing: spacing to create a grid if none is supplied, by default None
   :type spacing: int, optional

   :returns: masked grid or mask grid with 1's inside the mask.
   :rtype: xarray.DataArray


.. py:function:: change_reg(grid)

   Use GMT grdedit to change the registration type in the metadata.

   :param grid: input grid to change the reg for.
   :type grid: xarray.DataArray

   :returns: returns a xarray.DataArray with switched reg type.
   :rtype: xarray.DataArray


.. py:function:: grd_blend(grid1, grid2)

   Use GMT grdblend to blend 2 grids into 1.

   :param grid1: input grid to change the reg for.
   :type grid1: xarray.DataArray
   :param grid2: input grid to change the reg for.
   :type grid2: xarray.DataArray

   :returns: returns a blended grid.
   :rtype: xarray.DataArray


.. py:function:: get_fig_width()

   Get the width of the current PyGMT figure instance.

   :returns: width of the figure
   :rtype: float


.. py:function:: get_fig_height()

   Get the height of the current PyGMT figure instance.

   :returns: height of the figure
   :rtype: float


.. py:function:: gmt_str_to_list(region)

   convert a tuple of floats representing the boundaries of a region into a GMT-style
   region string

   :param region: bounding region in format [xmin, xmax, ymin, ymax]
   :type region: tuple[float, float, float, float]

   :returns: a GMT style region string
   :rtype: str