RegionMask

class regions.RegionMask(data, bbox)

Bases: object

Class for a region mask.

Parameters:

dataarray_like

A 2D array representing the fractional overlap of a region on the pixel grid. This should be the full-sized (i.e., not truncated) array that is the direct output of one of the low-level “geometry” functions.

bboxregions.RegionBoundingBox

The bounding box object defining the region minimal bounding box.

Examples

Usage examples are provided in the Computing Overlap Masks section of the docs.

Attributes Summary

shape

The shape of the mask data array.

Methods Summary

cutout(data[, fill_value, copy])	Create a cutout from the input data over the mask bounding box, taking any edge effects into account.
get_overlap_slices(shape)	Get slices for the overlapping part of the region mask and a 2D array.
get_values(data[, mask])	Get the mask-weighted pixel values from the data as a 1D array.
multiply(data[, fill_value])	Multiply the region mask with the input data, taking any edge effects into account.
to_image(shape[, dtype])	Return an image of the mask in a 2D array of the given shape, taking any edge effects into account.

Attributes Documentation

shape

The shape of the mask data array.

Methods Documentation

cutout(data, fill_value=0.0, copy=False)

Create a cutout from the input data over the mask bounding box, taking any edge effects into account.

Parameters:

dataarray_like

A 2D array on which to apply the region mask.

fill_valuefloat, optional

The value used to fill pixels where the region mask does not overlap with the input data. The default is 0.

copybool, optional

If True then the returned cutout array will always be hold a copy of the input data. If False and the mask is fully within the input data, then the returned cutout array will be a view into the input data. In cases where the mask partially overlaps or has no overlap with the input data, the returned cutout array will always hold a copy of the input data (i.e., this keyword has no effect).

Returns:

resultndarray or None

A 2D array cut out from the input data representing the same cutout region as the region mask. If there is a partial overlap of the region mask with the input data, pixels outside of the data will be assigned to fill_value. None is returned if there is no overlap of the region with the input data.

get_overlap_slices(shape)

Get slices for the overlapping part of the region mask and a 2D array.

Parameters:

shape2-tuple of int

The shape of the 2D array.

Returns:

slices_largetuple of slices or None

A tuple of slice objects for each axis of the large array, such that large_array[slices_large] extracts the region of the large array that overlaps with the small array. None is returned if there is no overlap of the bounding box with the given image shape.

slices_smalltuple of slices or None

A tuple of slice objects for each axis of the region mask array such that small_array[slices_small] extracts the region that is inside the large array. None is returned if there is no overlap of the bounding box with the given image shape.

get_values(data, mask=None)

Get the mask-weighted pixel values from the data as a 1D array.

If the RegionMask was created with mode='center', (where the mask weights are only 1 or 0), then the returned values will simply be pixel values extracted from the data.

Parameters:

dataarray_like or Quantity

The 2D array from which to get mask-weighted values.

maskarray_like (bool), optional

A boolean mask with the same shape as data where a True value indicates the corresponding element of data is not returned in the result.

Returns:

resultndarray

A 1D array of mask-weighted pixel values from the input data. If there is no overlap of the region with the input data, the result will be an empty array with shape (0,).

multiply(data, fill_value=0.0)

Multiply the region mask with the input data, taking any edge effects into account.

The result is a mask-weighted cutout from the data.

Parameters:

dataarray_like or Quantity

The 2D array to multiply with the region mask.

fill_valuefloat, optional

The value is used to fill pixels where the region mask does not overlap with the input data. The default is 0.

Returns:

resultndarray or None

A 2D mask-weighted cutout from the input data. If there is a partial overlap of the region mask with the input data, pixels outside of the data will be assigned to fill_value before being multiplied with the mask. None is returned if there is no overlap of the region with the input data.

to_image(shape, dtype=<class 'float'>)

Return an image of the mask in a 2D array of the given shape, taking any edge effects into account.

Parameters:

shapetuple of int

The (ny, nx) shape of the output array.

dtypedata-type, optional

The desired data type for the array. This should be a floating data type if the RegionMask was created with the “exact” or “subpixel” mode, otherwise the fractional mask weights will be altered. A integer data type may be used if the RegionMask was created with the “center” mode.

Returns:

resultndarray

A 2D array of the mask.