Mask_maker

Docstrings for the Mask_maker class

Objects

MaskMaker()
MaskMaker.make_mask_dataset()
MaskMaker.fill_polygon_by_index()
MaskMaker.fill_polygon_by_lonlat()
MaskMaker.region_def_nws_north_sea()
MaskMaker.region_def_nws_outer_shelf()
MaskMaker.region_def_nws_norwegian_trench()
MaskMaker.region_def_nws_english_channel()
MaskMaker.region_def_south_north_sea()
MaskMaker.region_def_off_shelf()
MaskMaker.region_def_irish_sea()
MaskMaker.region_def_kattegat()
MaskMaker.make_region_from_vertices()
MaskMaker.quick_plot()

Mask maker

MaskMaker()

class MaskMaker():
MaskMasker is a class of methods to assist with making regional masks within COAsT.
Presently these masks are external to MaskMaker.
It constructs a gridded boolean numpy array for each region, which are stacked over a dim_mask dimension and
stored as an xarray object.

A typical workflow might be:

    # Define vertices
    vertices_lon = [-5, -5, 5, 5]
    vertices_lat = [40, 60, 60, 40]

    # input lat/lon as xr.DataArray or numpy arrays. Return gridded boolean mask np.array on target grid
    filled = mm.make_region_from_vertices(
        sci.dataset.longitude, sci.dataset.latitude, vertices_lon, vertices_lat)

    # make xr.Dataset of masks from gridded mask array or list of mask arrays
    gridded_mask = mm.make_mask_dataset(sci.dataset.longitude.values,
                                     sci.dataset.latitude.values,
                                     filled)
    # quick plot
    mm.quick_plot(gridded_mask)


TO DO:
* Sort out region naming to be consistently applied and associated with the masks E.g. defined regions, or user defined masks
* Create final mask as a xr.DataArray, not a xr.Dataset
MaskMaker.make_mask_dataset()
@staticmethod
def MaskMaker.make_mask_dataset(longitude, latitude, mask_list, mask_names=None):

create xr.Dataset for mask with latitude and longitude coordinates. If mask_names are given
create a dim_mask coordinate of names

MaskMaker.fill_polygon_by_index()
@staticmethod
def MaskMaker.fill_polygon_by_index(array_to_fill, vertices_r, vertices_c, fill_value=1, additive=False):

Draws and fills a polygon onto an existing numpy array based on array
indices. To create a new mask, give np.zeros(shape) as input.
Polygon vertices are drawn in the order given.

Parameters
----------
array_to_fill (2D array): Array onto which to fill polygon
vertices_r (1D array): Row indices for polygon vertices
vertices_c (1D_array): Column indices for polygon vertices
fill_value (float, bool or int): Fill value for polygon (Default: 1)
additive (bool): If true, add fill value to existing array. Otherwise
                                                                indices will be overwritten. (Default: False)

Returns
-------
Filled 2D array

MaskMaker.fill_polygon_by_lonlat()
@staticmethod
def MaskMaker.fill_polygon_by_lonlat(array_to_fill, longitude, latitude, vertices_lon, vertices_lat, fill_value=1, additive=False):

Draws and fills a polygon onto an existing numpy array based on
vertices defined by longitude and latitude locations. This does NOT
draw a polygon on a sphere, but instead based on straight lines
between points. This is OK for small regional areas, but not advisable
for large and global regions.
Polygon vertices are drawn in the order given.

Parameters
----------
array_to_fill (2D array): Array onto which to fill polygon
vertices_r (1D array): Row indices for polygon vertices
vertices_c (1D_array): Column indices for polygon vertices
fill_value (float, bool or int): Fill value for polygon (Default: 1)
additive (bool): If true, add fill value to existing array. Otherwise
                                                                indices will be overwritten. (Default: False)

Returns
-------
Filled 2D np.array

MaskMaker.region_def_nws_north_sea()
@classmethod
def MaskMaker.region_def_nws_north_sea(cls, longitude, latitude, bath):

Regional definition for the North Sea (Northwest European Shelf)
Longitude, latitude and bath should be 2D arrays corresponding to model
coordinates and bathymetry. Bath should be positive with depth.

MaskMaker.region_def_nws_outer_shelf()
@classmethod
def MaskMaker.region_def_nws_outer_shelf(cls, longitude, latitude, bath):

Regional definition for the Outer Shelf (Northwest European Shelf)
Longitude, latitude and bath should be 2D arrays corresponding to model
coordinates and bathymetry. Bath should be positive with depth.

MaskMaker.region_def_nws_norwegian_trench()
@classmethod
def MaskMaker.region_def_nws_norwegian_trench(cls, longitude, latitude, bath):

Regional definition for the Norwegian Trench (Northwest European Shelf)
Longitude, latitude and bath should be 2D arrays corresponding to model
coordinates and bathymetry. Bath should be positive with depth.

MaskMaker.region_def_nws_english_channel()
@classmethod
def MaskMaker.region_def_nws_english_channel(cls, longitude, latitude, bath):

Regional definition for the English Channel (Northwest European Shelf)
Longitude, latitude and bath should be 2D arrays corresponding to model
coordinates and bathymetry. Bath should be positive with depth.

MaskMaker.region_def_south_north_sea()
@classmethod
def MaskMaker.region_def_south_north_sea(cls, longitude, latitude, bath):

None

MaskMaker.region_def_off_shelf()
@classmethod
def MaskMaker.region_def_off_shelf(cls, longitude, latitude, bath):

None

MaskMaker.region_def_irish_sea()
@classmethod
def MaskMaker.region_def_irish_sea(cls, longitude, latitude, bath):

None

MaskMaker.region_def_kattegat()
@classmethod
def MaskMaker.region_def_kattegat(cls, longitude, latitude, bath):

None

MaskMaker.make_region_from_vertices()
@classmethod
def MaskMaker.make_region_from_vertices(cls, longitude, latitude, vertices_lon, vertices_lat):

Construct mask on supplied longitude, latitude grid with input lists of lon and lat polygon vertices
:param longitude: np.array/xr.DataArray of longitudes on target grid
:param latitude: np.array/xr.DataArray of latitudes on target grid
:param vertices_lon: list of vertices for bounding polygon
:param vertices_lat: list of vertices for bounding polygon
:return: mask: np.array(boolean) on target grid. Ones are bound by polygon vertices

MaskMaker.quick_plot()
@classmethod
def MaskMaker.quick_plot(cls, mask):

Plot a map of masks in the MaskMaker object
Add labels


Last modified November 23, 2022: Updated docstrings from coast repo. (9daee18)