erlab.analysis.mask¶

Functions related to masking.

Polygon masking is adapted from the CGAL library. More information on point-in-polygon strategies can be found in Ref. [5].

Modules¶

polygon

Point-in-polygon algorithm.

Functions

`hex_bz_mask_points`(x, y[, a, rotate, ...])	Return a mask for given points.
`mask_with_hex_bz`(kxymap[, a, rotate, invert])	Mask an ARPES map with a hexagonal Brillouin zone.
`mask_with_polygon`(arr, vertices[, dims, invert])
`polygon_mask`(vertices, x, y[, invert])	Create a mask based on a polygon defined by its vertices.
`polygon_mask_points`(vertices, x, y[, invert])	Compute a mask indicating whether points are inside or outside a polygon.
`spherical_mask`(darr, radius[, boundary])	Generate a spherical boolean mask.

erlab.analysis.mask.hex_bz_mask_points(x, y, a=3.54, rotate=0, offset=(0.0, 0.0), reciprocal=False, invert=False)[source]¶

Return a mask for given points.

erlab.analysis.mask.mask_with_hex_bz(kxymap, a=3.54, rotate=0.0, invert=False)[source]¶

Mask an ARPES map with a hexagonal Brillouin zone.

Parameters:

kxymap (DataArray) – The input map to be masked.
a (float, default: 3.54) – The lattice constant of the hexagonal BZ. Default is 3.54.
rotate (float, default: 0.0) – The rotation angle of the BZ in degrees. Default is 0.0.
invert (bool, default: False) – Whether to invert the mask. Default is False.

Returns:

masked (xr.DataArray) – The masked map.

Return type:

DataArray

erlab.analysis.mask.mask_with_polygon(arr, vertices, dims=('kx', 'ky'), invert=False)[source]¶

erlab.analysis.mask.polygon_mask(vertices, x, y, invert=False)[source]¶

Create a mask based on a polygon defined by its vertices.

Parameters:

vertices (ndarray[Any, dtype[float64]]) – The vertices of the polygon. The shape should be (N, 2), where N is the number of vertices.
x (ndarray[Any, dtype[float64]]) – The x-coordinates of the grid points.
y (ndarray[Any, dtype[float64]]) – The y-coordinates of the grid points.
invert (bool, default: False) – If True, invert the mask (i.e., set True where the polygon is outside and False where it is inside). Default is False.

Returns:

mask (numpy.ndarray) – The mask array with shape (len(x), len(y)). The mask contains True where the polygon is inside and False where it is outside (or vice versa if invert is True).

Return type:

ndarray[Any, dtype[bool]]

Note

This function uses the erlab.analysis.mask.polygon.bounded_side_bool to determine whether a point is inside or outside the polygon.

Example

>>> vertices = np.array([[0.2, 0.2], [0.2, 0.8], [0.8, 0.8], [0.8, 0.2]])
>>> x = np.linspace(0, 1, 5)
>>> y = np.linspace(0, 1, 5)
>>> polygon_mask(vertices, x, y)
array([[False, False, False, False, False],
       [False,  True,  True,  True, False],
       [False,  True,  True,  True, False],
       [False,  True,  True,  True, False],
       [False, False, False, False, False]])

erlab.analysis.mask.polygon_mask_points(vertices, x, y, invert=False)[source]¶

Compute a mask indicating whether points are inside or outside a polygon.

Parameters:

vertices (ndarray[Any, dtype[float64]]) – The vertices of the polygon. The shape should be (N, 2), where N is the number of vertices.
x (ndarray[Any, dtype[float64]]) – The x-coordinates of the points.
y (ndarray[Any, dtype[float64]]) – The y-coordinates of the points.
invert (bool, default: False) – If True, invert the mask (i.e., set True where the polygon is outside and False where it is inside). Default is False.

Returns:

mask (numpy.ndarray) – A boolean array of shape (len(x),) indicating whether each point is inside or outside the polygon.

Raises:

ValueError – If the lengths of x and y are not equal.

Return type:

ndarray[Any, dtype[bool]]

Note

This function uses erlab.analysis.mask.polygon.bounded_side_bool() to determine whether a point is inside or outside the polygon.

erlab.analysis.mask.spherical_mask(darr, radius, boundary=True, **sel_kw)[source]¶

Generate a spherical boolean mask.

Depending on the radius and dimensions provided, the mask will be hyperellipsoid in the dimensions specified in sel_kw. Points at the boundary are included in the mask.

The resulting mask can be used with xarray.DataArray.where() to mask the data.

Parameters:

darr (DataArray) – The input DataArray.
radius (float | dict[Hashable, float]) – The radius of the spherical mask. If a single number, the same radius is used for all dimensions. If a dictionary, the keys should match the dimensions provided in sel_kw.
boundary (bool, default: True) – Whether to consider points on the boundary to be inside the mask. Default is True.
**sel_kw – Keyword arguments for selecting specific dimensions and values. Must be a mapping of valid dimension names to coordinate values.

Returns:

mask (xr.DataArray) – A boolean mask indicating whether each point in the data array is within the spherical mask.

Return type:

DataArray

Examples

>>> import numpy as np
>>> import xarray as xr
>>> from erlab.analysis.mask import spherical_mask
>>> darr = xr.DataArray(np.arange(25).reshape(5, 5), dims=("x", "y"))
>>> darr
<xarray.DataArray (x: 5, y: 5)> Size: 200B
array([[ 0,  1,  2,  3,  4],
    [ 5,  6,  7,  8,  9],
    [10, 11, 12, 13, 14],
    [15, 16, 17, 18, 19],
    [20, 21, 22, 23, 24]])
Dimensions without coordinates: x, y
>>> spherical_mask(darr, radius=2, x=2, y=2)
<xarray.DataArray (x: 5, y: 5)> Size: 25B
array([[False, False,  True, False, False],
    [False,  True,  True,  True, False],
    [ True,  True,  True,  True,  True],
    [False,  True,  True,  True, False],
    [False, False,  True, False, False]])
Dimensions without coordinates: x, y
>>> spherical_mask(darr, radius=1, x=2)
<xarray.DataArray (x: 5)> Size: 5B
array([False,  True,  True,  True, False])
Dimensions without coordinates: x