PixelMaskCollection

eitprocessing.roi.pixelmaskcollection ¶

PixelMaskCollection `dataclass` ¶

PixelMaskCollection(
    masks: (
        dict[Hashable, PixelMask]
        | frozendict[Hashable, PixelMask]
        | list[PixelMask]
        | None
    ) = None,
    *,
    label: str | None = None
)

A collection of pixel masks, each representing a specific region of interest (ROI) in the EIT data.

This class allows for the application of multiple masks to numpy arrays, EIT data or pixel maps, enabling the extraction of specific regions based on the defined masks.

PixelMasks can be labelled with strings, or anonymous (label=None). Either all or none of the masks should have a label; it is not possible to mix labelled and unlabelled masks.

At initialization, masks can be provided as a list or a dictionary. If provided as a list, the masks are converted to a dictionary with either their labels as keys (if all masks have labels) or their indices as keys (if none have labels). If provided as a dictionary, the keys must match the labels of the masks.

When the apply method is called, it applies each mask to the provided data and returns a dictionary mapping each mask's key (label or index) to the resulting masked data.

Example:

>>> mask_collection = PixelMaskCollection(
        [
            PixelMask(right_lung_data, label="right lung"),
            PixelMask(left_lung_data, label="left lung"),
        ],
        label="lung masks",
    )

PARAMETER	DESCRIPTION
`masks`	A dictionary mapping mask names to their corresponding pixel masks or a list of masks. TYPE: `dict \| list` DEFAULT: `None`
`label`	An optional label for the collection of masks. TYPE: `str \| None` DEFAULT: `None`

ATTRIBUTE	DESCRIPTION
`is_anonymous`	A boolean indicating whether all masks in the collection are anonymous (i.e., have no label). TYPE: `bool`

is_anonymous `property` ¶

is_anonymous: bool

Check if all masks in the collection are anonymous (i.e., have no label).

add ¶

add(*mask: PixelMask, overwrite: bool = False, **kwargs) -> Self

Return a new collection with one or more masks added.

Masks can be added as positional arguments or keyword arguments (non-anonymous masks only).

Example:

>>> left_lung_mask = PixelMask(data, label="left_lung")
>>> mask_collection.add(left_lung_mask)  # equals mask_collection.add(left_lung=left_lung_mask)

PARAMETER	DESCRIPTION
`*mask`	One or more `PixelMask` instances to add to the collection. TYPE: `PixelMask` DEFAULT: `()`
`overwrite`	If True, allows overwriting existing masks with the same label or index. TYPE: `bool` DEFAULT: `False`
`**kwargs`	Keyword arguments where the key is the label of the mask and the value is the mask itself. TYPE: `PixelMask` DEFAULT: `{}`

RETURNS	DESCRIPTION
`Self`	A new `PixelMaskCollection` instance with the added masks.

RAISES	DESCRIPTION
`ValueError`	If no masks are provided, if trying to mix labelled and unlabelled masks, or if provided keys don't match the masks label.
`KeyError`	If trying to overwrite an existing mask without setting `overwrite`.

combine ¶

combine(
    method: Literal["sum", "product"] = "sum", label: str | None = None
) -> PixelMask

Combine all masks in the collection into a single mask using the specified method.

The method can be either "sum" or "product". If "sum" is used, the masks are summed, generally resulting in the union of the represented ROIs. If "product" is used, the masks are multiplied, generally resulting in the intersection of the ROIs.

Example:

>>> pm1 = PixelMask([[True, False], [False, True]])
>>> pm2 = PixelMask([[True, True], [False, False]])
>>> collection = PixelMaskCollection([pm1, pm2])
>>> summed_mask = collection.combine(method="sum")
PixelMask(mask=array([[ 1.,  1.], [nan,  1.]]))

PARAMETER	DESCRIPTION
`method`	The method to combine the masks. Defaults to "sum". TYPE: `Literal['sum', 'product']` DEFAULT: `'sum'`
`label`	The label for the combined mask. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`PixelMask`	A new `PixelMask` instance representing the combined mask. TYPE: `PixelMask`

RAISES	DESCRIPTION
`ValueError`	If the PixelMaskCollection is empty.
`ValueError`	If an unsupported method is provided.

apply ¶

apply(data: ndarray) -> dict[Hashable, ndarray]

apply(
    data: EITData, *, label_format: str | None = None, **kwargs
) -> dict[Hashable, EITData]

apply(
    data: PixelMap, *, label_format: str | None = None, **kwargs
) -> dict[Hashable, PixelMap]

apply(data, *, label_format: str | None = None, **kwargs)

Apply the masks to the provided data.

The input data can be a numpy array, EITData, or PixelMap. The method applies each mask in the collection to the data and returns a dictionary mapping each mask's key (label or index) to the resulting masked data.

If label_format is provided, it should be a format string that includes {mask_label}. This label will be passed to the resulting objects, with the appropriate mask label applied. If label_format is not provided, no label will be provided.

Additional keyword arguments are passed to the update of the EITData or PixelMap, if applicable. If the input data is a numpy array, label_format and additional keyword arguments are not applicable and will raise a ValueError.

Example:

>>> mask_collection = PixelMaskCollection([
        PixelMask(data, label="right lung"),
        PixelMask(data, label="left lung")
    ])
>>> mask_collection.apply(eit_data, label_format="masked {mask_label}")
{"right lung": EITData(label="masked right lung"), "left lung": EITData(label="masked left lung")}

PARAMETER	DESCRIPTION
`data`	The data to which the masks will be applied. TYPE: `ndarray \| EITData \| PixelMap`
`label_format`	A format string to create the label of the returned EITData or PixelMap objects. TYPE: `str \| None` DEFAULT: `None`
`**kwargs`	Additional keyword arguments to pass to the `update` method of the returned EITData or PixelMap objects. DEFAULT: `{}`

RETURNS	DESCRIPTION
	A dictionary mapping each mask's key (label or index) to the resulting masked data.

RAISES	DESCRIPTION
`ValueError`	If the PixelMaskCollection is empty.
`ValueError`	If a label is passed as a keyword argument.
`ValueError`	If label_format or additional keyword arguments are provided when the input data is a numpy array.
`ValueError`	If provided label format does not contain '{mask_label}'.
`TypeError`	If provided data is not an array, EITData, or PixelMap.

PixelMaskCollection

eitprocessing.roi.pixelmaskcollection ¶