deltametrics.mask.GeometricMask

class deltametrics.mask.GeometricMask(*args, origin=None, **kwargs)

Create simple geometric masks.

A geometric mask object, allows for creation of subdomains in multiple ways. Angular boundaries can define an area of interest in the shape of an arc. Radial boundaries can define a radial region to mask. Boundaries defined in the strike direction (perpendicular to inlet channel), can be supplied to define a region of interest. Similarly, boundaries can be defined in the dip direction (parallel to inlet channel orientation).

Examples

Initialize the geometric mask using model topography as a base:

golfcube = dm.sample_data.golf()
arr = golfcube['eta'][-1, :, :]
gmsk = dm.mask.GeometricMask(arr)

# Define an angular mask to cover part of the domain from pi/4 to pi/2.
gmsk.angular(np.pi/4, np.pi/2)

# Further mask this region by defining bounds in the radial direction.
gmsk.circular(rad1=10, rad2=50)

# Visualize the mask:
fig, ax = plt.subplots(1, 2, figsize=(8, 4))
gmsk.show(ax=ax[0])
ax[1].imshow(golfcube['eta'][-1, :, :]*gmsk.mask)
ax[1].set_xticks([]); ax[1].set_yticks([])
plt.show()

(png, hires.png)

__init__(*args, origin=None, **kwargs)

Initialize the GeometricMask.

Initializing the geometric mask object requires information regarding the shape of the 2-D array of the region you wish to apply the mask to.

Important

The GeometricMask is initializes with all values set to True; this is the opposite of all other Mask types, which are set to False during initialization.

Parameters:

• *args – Various input arguments can be used to initialize the GeometricMask. Input may be a two-element tuple, specifying the array dimensions, or an ndarray, Mask, or Cube from which the shape is inferred.

• origin (tuple) – The “origin” of the domain. Usually this is the water/sediment inlet location. The origin is used as the mathematical origin point for computation setting the mask within the GeometricMask methods. If unspecified, it is inferred, based on the default configuration of a pyDeltaRCM model inlet.

• **kwargs – Keyword arguments can be specified to instantiate a GeometricMask and apply one (or more) of the geometric masking operations during instantiation. Accepted arguments are angular, circular, strike, and dip. Each argument must have a dictionary as it’s key, which contains the keyword-argument pairs to be passed to that geometric masking function (see examples).

Examples

Create an angular GeometricMask two different ways.

arr = np.random.uniform(size=(100, 200))
gmsk0 = dm.mask.GeometricMask(arr)
gmsk0.angular(np.pi/4, np.pi/2)

gmsk1 = dm.mask.GeometricMask(
    (100, 200), angular=dict(
        theta1=np.pi/4, theta2=np.pi/2)
    )

fig, ax = plt.subplots(1, 2)
gmsk0.show(ax[0])
gmsk1.show(ax[1])
plt.tight_layout()
plt.show()

(png, hires.png)

Note

See additional examples in the method docstring for each geometric masking operation: angular, circular, strike, and dip.

Methods

__init__(*args[, origin])	Initialize the GeometricMask.
angular([theta1, theta2])	Make a mask based on two angles.
circular([rad1, rad2, origin])	Make a circular mask bounded by two radii.
dip([ind1, ind2])	Make a mask parallel to the inlet.
from_array(_arr)	Create a GeometricMask from an array.
show([ax, title, ticks, colorbar])	Show the mask.
strike([ind1, ind2])	Make a mask based on two indices.
trim_mask(*args[, value, axis, length])	Replace a part of the mask with a new value.

Attributes

integer_mask	Binary mask values as integer
mask	Binary mask values.
mask_type	Type of the mask (string)
shape
variables
xc	x-coordinate of origin point.
yc	y-coordinate of origin point.

__getitem__(var)

Implement slicing.

Return values directly from the mask. Supported variables are only ‘mask’ or ‘integer’.

angular(theta1=0, theta2=3.141592653589793)

Make a mask based on two angles.

Computes a mask that is bounded by 2 angles input by the user.

Note

Requires a domain with a width greater than 2x its length right now. Function should be re-factored to be more flexible.

Note

Currently origin point is fixed, function should be extended to allow for an input origin point from which the angular bounds are determined.

Parameters:

• theta1 (float) – Radian value controlling the left bound of the mask. If unspecified, this bound is set to 0.

• theta2 (float) – Radian value controlling the right bound of the mask. If unspecified, this bound is set to pi=3.14…

Examples

Initialize an angular mask from 0 to pi/3 radians and mask topography:

golfcube = dm.sample_data.golf()
arr = golfcube['eta'][-1, :, :]
gmsk = dm.mask.GeometricMask(arr)

# Define an angular mask to cover part of the domain from 0 to pi/3
gmsk.angular(0, np.pi/3)

# Visualize the mask:
fig, ax = plt.subplots(1, 2, figsize=(8, 4))
gmsk.show(ax=ax[0], title='Binary Mask')
ax[1].imshow(golfcube['eta'][-1, :, :] * gmsk.mask)
ax[1].set_xticks([]); ax[1].set_yticks([])
ax[1].set_title('Mask * Topography')
plt.show()

(png, hires.png)

circular(rad1=0, rad2=None, origin=None)

Make a circular mask bounded by two radii.

Computes a mask that is bounded by 2 radial distances which are input by the user.

Parameters:

• rad1 (int) – Index value to set the inner radius. If unspecified, this bound is set to 0.

• rad2 (int, optional) – Index value to set the outer radius. If unspecified, this bound is set to extend as the larger dimension of the domain.

• origin (tuple, optional) – Optionally specify an origin to use for computing the circle. Will use the GeometricMask origin, if not supplied.

Examples

Initialize geometric mask which clips out a region near the inlet:

golfcube = dm.sample_data.golf()
arr = golfcube['eta'][-1, :, :]
gmsk = dm.mask.GeometricMask(arr)

# Define an circular mask to exclude region near the inlet
gmsk.circular(25)

# Visualize the mask:
fig, ax = plt.subplots(1, 2, figsize=(8, 4))
gmsk.show(ax=ax[0], title='Binary Mask')
ax[1].imshow(golfcube['eta'][-1, :, :] * gmsk.mask)
ax[1].set_xticks([]); ax[1].set_yticks([])
ax[1].set_title('Mask * Topography')
plt.show()

(png, hires.png)

dip(ind1=0, ind2=None)

Make a mask parallel to the inlet.

Makes a mask that is parallel to the direction of flow in the inlet. If only one value is supplied, then this mask is centered on the inlet and has a width of ind1. If two values are supplied then they set the bounds for the mask.

Parameters:

• ind1 (int) – Width of the mask if ind2 is not specified. Otherwise, it sets the left bound of the mask.

• ind2 (int, optional) – Right bound of the mask if specified. If not specified, then ind1 sets the width of a mask centered on the inlet.

Examples

Initialize mask with a width of 50 pixels in-line with the inlet:

golfcube = dm.sample_data.golf()
arr = golfcube['eta'][-1, :, :]
gmsk = dm.mask.GeometricMask(arr)

# Define mask with width of 50 px. inline with the inlet
gmsk.dip(50)

# Visualize the mask:
fig, ax = plt.subplots(1, 2, figsize=(8, 4))
gmsk.show(ax=ax[0], title='Binary Mask')
ax[1].imshow(golfcube['eta'][-1, :, :] * gmsk.mask)
ax[1].set_xticks([]); ax[1].set_yticks([])
ax[1].set_title('Mask * Topography')
plt.show()

(png, hires.png)

static from_array(_arr)

Create a GeometricMask from an array.

Note

Instantiation with from_array will attempt to any data type (dtype) to boolean. This may have unexpected results. Convert your array to a boolean before using from_array to ensure the mask is created correctly.

Parameters:

_arr (ndarray) – The array with values to set as the mask. Can be any dtype but will be coerced to boolean.

property integer_mask

Binary mask values as integer

Important

integer_mask is a boolean array as 0 and 1 (integers). It is not suitible for multidimensional array indexing; see also mask.

Read-only mask attribute.

Type:

ndarray

property mask

Binary mask values.

Important

mask is a boolean array (not integer). See also integer_mask.

Read-only mask attribute.

Type:

ndarray

property mask_type

Type of the mask (string)

show(ax=None, title=None, ticks=False, colorbar=False, **kwargs)

Show the mask.

The Mask is shown in a matplotlib axis with imshow. The mask values are accessed from integer_mask, so the display will show as 0 for False and 1 for True. Default colormap is black and white.

Hint

Passes **kwargs to matplotlib.imshow.

Parameters:

ax (matplotlib.pyplot.Axes) – Which axes object to plot into.

strike(ind1=0, ind2=None)

Make a mask based on two indices.

Makes a mask bounded by lines perpendicular to the direction of the flow in the inlet channel.

Parameters:

• ind1 (int) – Index value to set first boundary (closest to inlet)

• ind2 (int, optional) – Index value to set second boundary (farther from inlet). This is optional, if unspecified, this is set to the length of the domain.

Examples

Initialize a mask that isolates the region 20-50 pixels from the inlet:

golfcube = dm.sample_data.golf()
arr = golfcube['eta'][-1, :, :]
gmsk = dm.mask.GeometricMask(arr)

# Define a mask that isolates the region 20-50 pixels from the inlet
gmsk.strike(20, 50)

# Visualize the mask:
fig, ax = plt.subplots(1, 2, figsize=(8, 4))
gmsk.show(ax=ax[0], title='Binary Mask')
ax[1].imshow(golfcube['eta'][-1, :, :] * gmsk.mask)
ax[1].set_xticks([]); ax[1].set_yticks([])
ax[1].set_title('Mask * Topography')
plt.show()

(png, hires.png)

trim_mask(*args, value=False, axis=1, length=None)

Replace a part of the mask with a new value.

This is sometimes necessary before using a mask in certain computations. Most often, this method is used to manually correct domain edge effects.

Parameters:

• *args (BaseCube subclass, optional) – Optionally pass a Cube object to the mask, and the dimensions to trim/replace the mask by will be inferred from the cube. In this case, axis and length have no effect.

• value – Value to replace in the trim region with. Default is False.

• axis – Which edge to apply the trim of length to. Default is 1, the top domain edge.

• length – The length of the trim. Note that this is not the array index.

Examples

property xc

x-coordinate of origin point.

property yc

y-coordinate of origin point.