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. [Schirra, 2008].

Modules

polygon

Point-in-polygon algorithm.

Functions

mask_with_bz(darr, basis, *[, reciprocal, ...])

Mask an xarray.DataArray by a 2D Brillouin zone defined by lattice basis vectors.

mask_with_hex_bz(darr, a, *[, reciprocal, ...])

Mask an xarray.DataArray by a 2D hexagon.

mask_with_polygon(darr, vertices, *[, dims, ...])

Mask an xarray.DataArray by a polygon in coordinate space.

mask_with_radius(darr, radius, *[, ...])

Average data within a specified radius of a specified point.

mask_with_regular_polygon(darr, n_verts, ...)

Mask an xarray.DataArray by a regular polygon in coordinate space.
erlab.analysis.mask.mask_with_bz(darr, basis, *, reciprocal=False, rotate=0.0, offset=(0.0, 0.0), dims=None, invert=False, drop=False)[source]

Mask an xarray.DataArray by a 2D Brillouin zone defined by lattice basis vectors.

The Brillouin zone is constructed from the provided lattice basis vectors. If reciprocal=True, the basis vectors are interpreted as those of the reciprocal lattice; otherwise, they are the real space lattice basis vectors. The polygon is oriented so that a vertex is at the top (along the positive y-axis) when rotate=0.

Parameters:

  • darr (DataArray) – Input data to be masked. Must contain the coordinate variables named in dims.

  • basis (ndarray[tuple[Any, ...], dtype[floating]]) – A 2D or 3D numpy array with shape (N, N) where N = 2 or 3, containing the basis vectors of the lattice. If N is 3, only the upper left 2x2 submatrix is used.

  • reciprocal (bool) – If True, the basis vectors are interpreted as those of the reciprocal lattice. Default is False, i.e., the basis vectors are treated as real space lattice vectors.

  • rotate (float) – Rotation angle of the BZ in degrees. Default is 0.0.

  • offset (tuple of float) – Offset for the zone center in the form of a tuple. Default is (0.0, 0.0).

  • dims (tuple[Hashable, Hashable] | None, default: None) – Names of the two dimensions over which the BZ is defined. The column order of vertices must correspond to (dims[0], dims[1]). If None (default) and the dimensions ('kx', 'ky') exist in the data, those are used. Otherwise, the first two dimensions of the data are used.

  • invert (bool, default: False) – If True, invert the mask so that points inside the BZ are masked and points outside are kept.

  • drop (bool, default: False) – If True, drop coordinate labels along dims for which all values are masked. This typically reduces the extent to a bounding rectangle of the BZ; masked points inside that extent remain NaN.

Returns:

DataArray – The masked DataArray.

Return type:

DataArray

erlab.analysis.mask.mask_with_hex_bz(darr, a, *, reciprocal=False, rotate=0.0, offset=(0.0, 0.0), dims=None, invert=False, drop=False)[source]

Mask an xarray.DataArray by a 2D hexagon.

The hexagonal Brillouin zone is constructed from the lattice constant a. If reciprocal=True, a is interpreted as the periodicity of the reciprocal lattice; otherwise, it is the real space lattice constant. The hexagon is oriented so that a vertex is at the top (along the positive y-axis) when rotate=0.

Parameters:

  • darr (DataArray) – Input data to be masked. Must contain the coordinate variables named in dims.

  • a (float) – Lattice constant of the hexagonal lattice.

  • reciprocal (bool) – If True, a is interpreted as the periodicity of the reciprocal lattice. Default is False.

  • rotate (float) – Rotation angle of the hexagon in degrees. Default is 0.0.

  • offset (tuple of float) – Offset for the hexagon center in the form of a tuple. Default is (0.0, 0.0).

  • dims (tuple[Hashable, Hashable] | None, default: None) – Names of the two dimensions over which the BZ is defined. The column order of vertices must correspond to (dims[0], dims[1]). If None (default) and the dimensions ('kx', 'ky') exist in the data, those are used. Otherwise, the first two dimensions of the data are used.

  • invert (bool, default: False) – If True, invert the mask so that points inside the hexagon are masked and points outside are kept.

  • drop (bool, default: False) – If True, drop coordinate labels along dims for which all values are masked. This typically reduces the extent to a bounding rectangle of the hexagon; masked points inside that extent remain NaN.

Returns:

DataArray – The masked DataArray.

Return type:

DataArray

erlab.analysis.mask.mask_with_polygon(darr, vertices, *, dims=None, invert=False, drop=False)[source]

Mask an xarray.DataArray by a polygon in coordinate space.

Builds a boolean mask from a 2D polygon in the plane spanned by two coordinates (specified by dims) and returns a DataArray with values outside the polygon set to NaN (or dropped if drop=True). If invert=True, the selection is inverted so that values inside the polygon are masked instead.

Parameters:

  • darr (DataArray) – Input data to be masked. Must contain the coordinate variables named in dims.

  • vertices (array-like of shape (N, 2)) – Polygon vertices as [x, y] pairs in the order as dims. The polygon is treated as closed; the last vertex will be implicitly connected to the first if needed.

  • dims (tuple[Hashable, Hashable] | None, default: None) – Names of the two dimensions over which the polygon is defined. The column order of vertices must correspond to (dims[0], dims[1]). If None (default), the first two dimensions of the data are used.

  • invert (bool, default: False) – If True, invert the mask so that points inside the polygon are masked and points outside are kept.

  • drop (bool, default: False) – If True, drop coordinate labels along dims for which all values are masked. This typically reduces the extent to a bounding rectangle of the polygon; masked points inside that extent remain NaN.

Returns:

DataArray – The masked DataArray.

erlab.analysis.mask.mask_with_radius(darr, radius, *, boundary=True, invert=False, drop=False, **sel_kw)[source]

Average data within a specified radius of a specified point.

For instance, consider an ARPES map with dimensions 'kx', 'ky', and 'eV'. Providing 'kx' and 'ky' points will average the data within a cylindrical region centered at that point. The radius of the cylinder is specified by radius.

If different radii are given for kx and ky, the region will be elliptic.

Parameters:

  • radius (float | dict[Hashable, float]) – The radius of the region. If a single number, the same radius is used for all dimensions. If a dictionary, keys must be valid dimension names and the values are the radii for the corresponding dimensions.

  • boundary (bool, default: True) – Whether to consider points on the boundary to be inside the mask. Default is True.

  • invert (bool, default: False) – If True, invert the mask so that points inside are masked and points outside are kept. This is applied after the mask is created.

  • drop (bool, default: False) – If True, drop coordinate labels along dims for which all values are masked.

  • **sel_kw – The center of the spherical region. Must be a mapping of valid dimension names to coordinate values.

Returns:

DataArray – The data masked to the specified region.

Return type:

DataArray

Note

The region is defined by a spherical mask. Depending on the radius and dimensions provided, the mask will be hyperellipsoid in the dimensions specified in sel_kw.

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: 200B
array([[nan, nan,  2., nan, nan],
    [nan,  6.,  7.,  8., nan],
    [10., 11., 12., 13., 14.],
    [nan, 16., 17., 18., nan],
    [nan, nan, 22., nan, nan]])
Dimensions without coordinates: x, y
>>> spherical_mask(darr, radius=1, x=2)
<xarray.DataArray (x: 5, y: 5)> Size: 200B
array([[nan, nan, nan, nan, nan],
    [ 5.,  6.,  7.,  8.,  9.],
    [10., 11., 12., 13., 14.],
    [15., 16., 17., 18., 19.],
    [nan, nan, nan, nan, nan]])
Dimensions without coordinates: x, y
erlab.analysis.mask.mask_with_regular_polygon(darr, n_verts, radius, *, rotate=0.0, offset=(0.0, 0.0), dims=None, invert=False, drop=False)[source]

Mask an xarray.DataArray by a regular polygon in coordinate space.

Builds a boolean mask from a regular 2D polygon in the plane spanned by two coordinates (specified by dims) and returns a DataArray with values outside the polygon set to NaN (or dropped if drop=True). If invert=True, the selection is inverted so that values inside the polygon are masked instead. The polygon is oriented so that a vertex is at the top (along the positive y-axis) when rotate=0.

Parameters:

  • darr (DataArray) – Input data to be masked. Must contain the coordinate variables named in dims.

  • n_verts (int) – Number of vertices of the regular polygon.

  • radius (float) – Distance from the polygon center to each vertex.

  • rotate (float) – Rotation angle of the polygon in degrees. Default is 0.0.

  • offset (tuple of float) – Offset for the polygon center in the form of a tuple. Default is (0.0, 0.0).

  • dims (tuple[Hashable, Hashable] | None, default: None) – Names of the two dimensions over which the polygon is defined. The column order of vertices must correspond to (dims[0], dims[1]). If None (default), the first two dimensions of the data are used.

  • invert (bool, default: False) – If True, invert the mask so that points inside the polygon are masked and points outside are kept.

  • drop (bool, default: False) – If True, drop coordinate labels along dims for which all values are masked. This typically reduces the extent to a bounding rectangle of the polygon; masked points inside that extent remain NaN.

Returns:

DataArray – The masked DataArray.