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:

masked (DataArray) – A new array with values outside the selected polygon replaced by missing values, or values inside it when invert is True. Dimension names, coordinates, name, and attributes are retained. If drop is True, the two mask dimensions can become shorter because coordinate labels for fully masked rows and columns are removed. Integer input is promoted to a dtype that can represent missing values. The input is not modified.

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.