PixelMap

eitprocessing.datahandling.pixelmap

Handling and visualizing pixel-based data maps in EIT analysis.

This module provides classes for working with pixel-based data representations of EIT data. The main class hierarchy consists of:

• PixelMap: Base class for representing 2D pixel data with visualization and manipulation capabilities.
• TIVMap: Specialized map for Tidal Impedance Variation (TIV) data.
• ODCLMap: Specialized map for Overdistention and Collapse (ODCL) analysis.
• DifferenceMap: Specialized map for visualizing differences between pixel maps.
• PerfusionMap: Specialized map for perfusion analysis.
• PendelluftMap: Specialized map for positive-only pendelluft values (severity, no direction).
• SignedPendelluftMap: Specialized map for signed pendelluft values (severity and direction/phase).

Plotting configurations for each map are managed via a class inheriting from PixelMapPlotConfig, which allows for flexible configuration of colormap, normalization, colorbar, and other display options. These can be customized per map type or per instance. PixelMapPlotConfig is found in eitprocessing.plotting.pixelmap.

All classes are immutable to ensure data integrity during analysis pipelines.

PixelMap provides a replace method, which allows you to create a copy of the object with one or more attributes replaced, similar to dataclasses.replace() (or `copy.replace() in Python ≥3.13). This is useful for updating data or configuration in an immutable and chainable way, and supports partial updates of nested configuration (e.g., updating only a single plotting configuration).

Mathematical Operations

PixelMap instances support basic mathematical operations (+, -, *, /) with other PixelMap instances, arrays, or scalar values. The operations are applied element-wise to the underlying values.

• Addition (+): Returns a PixelMap with values added element-wise.

• Subtraction (-): Returns a DifferenceMap with values subtracted element-wise.

• Multiplication (*): Returns a PixelMap with values multiplied element-wise.

• Division (/): Returns a PixelMap with values divided element-wise. Division by zero results in NaN values with a warning.

When operating with another PixelMap of any type, operations typically return the base PixelMap type, except for subtraction which returns a DifferenceMap. When operating with scalars or arrays, operations return the same type as the original PixelMap.

Note: Some PixelMap subclasses (like TIVMap and PerfusionMap) do not allow negative values. Operations that might produce negative values with these maps will display appropriate warnings.

PixelMap dataclass

PixelMap(
    values: ArrayLike,
    *,
    label: str | None = None,
    suppress_negative_warning: bool = False,
    suppress_all_nan_warning: bool = False,
    plot_config: PixelMapPlotConfig | dict | None = None
)

Map representing a single value for each pixel.

At initialization, values are conveted to a 2D numpy array of floats. The values are immutable after initialization, meaning that the values attribute cannot be changed directly. Instead, use the replace(...) method to create a copy with new values or label.

For many common cases, specific classes with default plot configurations are available.

PARAMETER	DESCRIPTION
values	2D array of pixel values. TYPE: ndarray
label	Label for the pixel map. TYPE: str | None DEFAULT: None
plot_config	Plotting configuration controlling colormap, normalization, colorbar, and other display options. Accepts both a PixelMapPlotConfig instance or a dict, which is converted to PixelMapPlotConfig during initialization. Subclasses provide their own defaults. TYPE: dict | PixelMapPlotConfig | None DEFAULT: None

ATTRIBUTE	DESCRIPTION
allow_negative_values	Whether negative values are allowed in the pixel map. TYPE: bool

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(
    *,
    mode: Literal[
        "zero-based", "symmetric", "maximum", "reference"
    ] = "zero-based",
    reference: float | None = None,
    **kwargs
) -> Self

Normalize the pixel map values.

Creates a copy of the pixel map with normalized values. Four normalization modes are available.

• "zero-based" (default): normalizes the values to the range [0, 1] by subtracting the minimum value and dividing by the new maximum value. This ensures the lowest resulting value is 0 and the highest resulting value is 1.
• "symmetric": divides the values by the maximum absolute value, resulting in a range of [-1, 1].
• "maximum": divides the values by the maximum value. If all values are positive, this normalizes them to the range [0, 1] without shifting the minimum value to zero. The sign of values does not change. If negative values are present, the result may extend below -1.
• "reference": is similar to "maximum", except it divides by a user-defined reference value. A reference value must be provided. Resulting values can fall outside the range [-1, 1].

NaN values are ignored when normalizing. All-NaN pixel maps results in a ValueError.

Examples:

>>> PixelMap([[1, 3, 5]]).normalize()  # Default is zero-based normalization
PixelMap(values=array([[0. , 0.5, 1. ]]), ...)

>>> PixelMap([[1, 3, 5]]).normalize(mode="maximum")
PixelMap(values=array([[0.2, 0.6, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize()
PixelMap(values=array([[0. , 0.7, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="symmetric")
PixelMap(values=array([[-1.   , -0.125,  0.25 ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="reference", reference=4)
PixelMap(values=array([[-2.  , -0.25,  0.5 ]]), ...)

PARAMETER	DESCRIPTION
mode	The normalization mode to use. Defaults to "zero-based". TYPE: Literal['zero-based', 'symmetric', 'maximum', 'reference'] DEFAULT: 'zero-based'
reference	The reference value to use for normalization in "reference" mode. TYPE: float | None DEFAULT: None
kwargs	Additional keyword arguments to pass to the new PixelMap instance. TYPE: dict DEFAULT: {}

RAISES	DESCRIPTION
ValueError	If an invalid normalization mode is specified.
ValueError	If no reference value is provided in "reference" mode.
ValueError	If a reference value is provided with a mode other than "reference".
TypeError	If the reference value is not a number.
ZeroDivisionError	If normalization by zero is attempted (either reference=0, or the maximum (absolute) value in the values is 0).
ValueError	If normalization by NaN is attempted (either reference=np.nan, or all values are NaN).

WARNS	DESCRIPTION
UserWarning	If normalization by a negative number is attempted (either reference is negative, or all values are negative). This results in inverting the sign of the values.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.

DifferenceMap dataclass

DifferenceMap(
    values: ndarray,
    *,
    label: str | None = None,
    plot_config: InitVar[PixelMapPlotConfig]
)

Pixel map representing the difference between two pixel maps.

Values are centered around zero, with positive values indicating an increase and negative values indicating a decrease in the pixel values compared to a reference map. If the values are all expected to be positive, consider converting to a normal PixelMap or other subclass instead.

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(
    *,
    mode: Literal[
        "zero-based", "symmetric", "maximum", "reference"
    ] = "zero-based",
    reference: float | None = None,
    **kwargs
) -> Self

Normalize the pixel map values.

Creates a copy of the pixel map with normalized values. Four normalization modes are available.

• "zero-based" (default): normalizes the values to the range [0, 1] by subtracting the minimum value and dividing by the new maximum value. This ensures the lowest resulting value is 0 and the highest resulting value is 1.
• "symmetric": divides the values by the maximum absolute value, resulting in a range of [-1, 1].
• "maximum": divides the values by the maximum value. If all values are positive, this normalizes them to the range [0, 1] without shifting the minimum value to zero. The sign of values does not change. If negative values are present, the result may extend below -1.
• "reference": is similar to "maximum", except it divides by a user-defined reference value. A reference value must be provided. Resulting values can fall outside the range [-1, 1].

NaN values are ignored when normalizing. All-NaN pixel maps results in a ValueError.

Examples:

>>> PixelMap([[1, 3, 5]]).normalize()  # Default is zero-based normalization
PixelMap(values=array([[0. , 0.5, 1. ]]), ...)

>>> PixelMap([[1, 3, 5]]).normalize(mode="maximum")
PixelMap(values=array([[0.2, 0.6, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize()
PixelMap(values=array([[0. , 0.7, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="symmetric")
PixelMap(values=array([[-1.   , -0.125,  0.25 ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="reference", reference=4)
PixelMap(values=array([[-2.  , -0.25,  0.5 ]]), ...)

PARAMETER	DESCRIPTION
mode	The normalization mode to use. Defaults to "zero-based". TYPE: Literal['zero-based', 'symmetric', 'maximum', 'reference'] DEFAULT: 'zero-based'
reference	The reference value to use for normalization in "reference" mode. TYPE: float | None DEFAULT: None
kwargs	Additional keyword arguments to pass to the new PixelMap instance. TYPE: dict DEFAULT: {}

RAISES	DESCRIPTION
ValueError	If an invalid normalization mode is specified.
ValueError	If no reference value is provided in "reference" mode.
ValueError	If a reference value is provided with a mode other than "reference".
TypeError	If the reference value is not a number.
ZeroDivisionError	If normalization by zero is attempted (either reference=0, or the maximum (absolute) value in the values is 0).
ValueError	If normalization by NaN is attempted (either reference=np.nan, or all values are NaN).

WARNS	DESCRIPTION
UserWarning	If normalization by a negative number is attempted (either reference is negative, or all values are negative). This results in inverting the sign of the values.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.

TIVMap dataclass

TIVMap(
    values: ndarray,
    *,
    label: str | None = None,
    plot_config: InitVar[PixelMapPlotConfig]
)

Pixel map representing the tidal impedance variation.

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(
    *,
    mode: Literal[
        "zero-based", "symmetric", "maximum", "reference"
    ] = "zero-based",
    reference: float | None = None,
    **kwargs
) -> Self

Normalize the pixel map values.

Creates a copy of the pixel map with normalized values. Four normalization modes are available.

• "zero-based" (default): normalizes the values to the range [0, 1] by subtracting the minimum value and dividing by the new maximum value. This ensures the lowest resulting value is 0 and the highest resulting value is 1.
• "symmetric": divides the values by the maximum absolute value, resulting in a range of [-1, 1].
• "maximum": divides the values by the maximum value. If all values are positive, this normalizes them to the range [0, 1] without shifting the minimum value to zero. The sign of values does not change. If negative values are present, the result may extend below -1.
• "reference": is similar to "maximum", except it divides by a user-defined reference value. A reference value must be provided. Resulting values can fall outside the range [-1, 1].

NaN values are ignored when normalizing. All-NaN pixel maps results in a ValueError.

Examples:

>>> PixelMap([[1, 3, 5]]).normalize()  # Default is zero-based normalization
PixelMap(values=array([[0. , 0.5, 1. ]]), ...)

>>> PixelMap([[1, 3, 5]]).normalize(mode="maximum")
PixelMap(values=array([[0.2, 0.6, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize()
PixelMap(values=array([[0. , 0.7, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="symmetric")
PixelMap(values=array([[-1.   , -0.125,  0.25 ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="reference", reference=4)
PixelMap(values=array([[-2.  , -0.25,  0.5 ]]), ...)

PARAMETER	DESCRIPTION
mode	The normalization mode to use. Defaults to "zero-based". TYPE: Literal['zero-based', 'symmetric', 'maximum', 'reference'] DEFAULT: 'zero-based'
reference	The reference value to use for normalization in "reference" mode. TYPE: float | None DEFAULT: None
kwargs	Additional keyword arguments to pass to the new PixelMap instance. TYPE: dict DEFAULT: {}

RAISES	DESCRIPTION
ValueError	If an invalid normalization mode is specified.
ValueError	If no reference value is provided in "reference" mode.
ValueError	If a reference value is provided with a mode other than "reference".
TypeError	If the reference value is not a number.
ZeroDivisionError	If normalization by zero is attempted (either reference=0, or the maximum (absolute) value in the values is 0).
ValueError	If normalization by NaN is attempted (either reference=np.nan, or all values are NaN).

WARNS	DESCRIPTION
UserWarning	If normalization by a negative number is attempted (either reference is negative, or all values are negative). This results in inverting the sign of the values.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.

AmplitudeMap dataclass

AmplitudeMap(
    values: ndarray,
    *,
    label: str | None = None,
    plot_config: InitVar[PixelMapPlotConfig]
)

Pixel map representing the amplitude.

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(
    *,
    mode: Literal[
        "zero-based", "symmetric", "maximum", "reference"
    ] = "zero-based",
    reference: float | None = None,
    **kwargs
) -> Self

Normalize the pixel map values.

Creates a copy of the pixel map with normalized values. Four normalization modes are available.

• "zero-based" (default): normalizes the values to the range [0, 1] by subtracting the minimum value and dividing by the new maximum value. This ensures the lowest resulting value is 0 and the highest resulting value is 1.
• "symmetric": divides the values by the maximum absolute value, resulting in a range of [-1, 1].
• "maximum": divides the values by the maximum value. If all values are positive, this normalizes them to the range [0, 1] without shifting the minimum value to zero. The sign of values does not change. If negative values are present, the result may extend below -1.
• "reference": is similar to "maximum", except it divides by a user-defined reference value. A reference value must be provided. Resulting values can fall outside the range [-1, 1].

NaN values are ignored when normalizing. All-NaN pixel maps results in a ValueError.

Examples:

>>> PixelMap([[1, 3, 5]]).normalize()  # Default is zero-based normalization
PixelMap(values=array([[0. , 0.5, 1. ]]), ...)

>>> PixelMap([[1, 3, 5]]).normalize(mode="maximum")
PixelMap(values=array([[0.2, 0.6, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize()
PixelMap(values=array([[0. , 0.7, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="symmetric")
PixelMap(values=array([[-1.   , -0.125,  0.25 ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="reference", reference=4)
PixelMap(values=array([[-2.  , -0.25,  0.5 ]]), ...)

PARAMETER	DESCRIPTION
mode	The normalization mode to use. Defaults to "zero-based". TYPE: Literal['zero-based', 'symmetric', 'maximum', 'reference'] DEFAULT: 'zero-based'
reference	The reference value to use for normalization in "reference" mode. TYPE: float | None DEFAULT: None
kwargs	Additional keyword arguments to pass to the new PixelMap instance. TYPE: dict DEFAULT: {}

RAISES	DESCRIPTION
ValueError	If an invalid normalization mode is specified.
ValueError	If no reference value is provided in "reference" mode.
ValueError	If a reference value is provided with a mode other than "reference".
TypeError	If the reference value is not a number.
ZeroDivisionError	If normalization by zero is attempted (either reference=0, or the maximum (absolute) value in the values is 0).
ValueError	If normalization by NaN is attempted (either reference=np.nan, or all values are NaN).

WARNS	DESCRIPTION
UserWarning	If normalization by a negative number is attempted (either reference is negative, or all values are negative). This results in inverting the sign of the values.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.

ODCLMap dataclass

ODCLMap(
    values: ndarray,
    *,
    label: str | None = None,
    plot_config: InitVar[PixelMapPlotConfig]
)

Pixel map representing normalized overdistention and collapse.

Values between -1 and 0 (-100% to 0%) represent compliance change due to collapse , while values between 0 and 1 (0% to 100%) represent compliance change due to overdistention.

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(
    *,
    mode: Literal[
        "zero-based", "symmetric", "maximum", "reference"
    ] = "zero-based",
    reference: float | None = None,
    **kwargs
) -> Self

Normalize the pixel map values.

Creates a copy of the pixel map with normalized values. Four normalization modes are available.

• "zero-based" (default): normalizes the values to the range [0, 1] by subtracting the minimum value and dividing by the new maximum value. This ensures the lowest resulting value is 0 and the highest resulting value is 1.
• "symmetric": divides the values by the maximum absolute value, resulting in a range of [-1, 1].
• "maximum": divides the values by the maximum value. If all values are positive, this normalizes them to the range [0, 1] without shifting the minimum value to zero. The sign of values does not change. If negative values are present, the result may extend below -1.
• "reference": is similar to "maximum", except it divides by a user-defined reference value. A reference value must be provided. Resulting values can fall outside the range [-1, 1].

NaN values are ignored when normalizing. All-NaN pixel maps results in a ValueError.

Examples:

>>> PixelMap([[1, 3, 5]]).normalize()  # Default is zero-based normalization
PixelMap(values=array([[0. , 0.5, 1. ]]), ...)

>>> PixelMap([[1, 3, 5]]).normalize(mode="maximum")
PixelMap(values=array([[0.2, 0.6, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize()
PixelMap(values=array([[0. , 0.7, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="symmetric")
PixelMap(values=array([[-1.   , -0.125,  0.25 ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="reference", reference=4)
PixelMap(values=array([[-2.  , -0.25,  0.5 ]]), ...)

PARAMETER	DESCRIPTION
mode	The normalization mode to use. Defaults to "zero-based". TYPE: Literal['zero-based', 'symmetric', 'maximum', 'reference'] DEFAULT: 'zero-based'
reference	The reference value to use for normalization in "reference" mode. TYPE: float | None DEFAULT: None
kwargs	Additional keyword arguments to pass to the new PixelMap instance. TYPE: dict DEFAULT: {}

RAISES	DESCRIPTION
ValueError	If an invalid normalization mode is specified.
ValueError	If no reference value is provided in "reference" mode.
ValueError	If a reference value is provided with a mode other than "reference".
TypeError	If the reference value is not a number.
ZeroDivisionError	If normalization by zero is attempted (either reference=0, or the maximum (absolute) value in the values is 0).
ValueError	If normalization by NaN is attempted (either reference=np.nan, or all values are NaN).

WARNS	DESCRIPTION
UserWarning	If normalization by a negative number is attempted (either reference is negative, or all values are negative). This results in inverting the sign of the values.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.

PerfusionMap dataclass

PerfusionMap(
    values: ndarray,
    *,
    label: str | None = None,
    plot_config: InitVar[PixelMapPlotConfig]
)

Pixel map representing perfusion values.

Values represent perfusion, where higher values indicate more perfusion. The values are expected to be non-negative, with 0 representing no perfusion.

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(
    *,
    mode: Literal[
        "zero-based", "symmetric", "maximum", "reference"
    ] = "zero-based",
    reference: float | None = None,
    **kwargs
) -> Self

Normalize the pixel map values.

Creates a copy of the pixel map with normalized values. Four normalization modes are available.

• "zero-based" (default): normalizes the values to the range [0, 1] by subtracting the minimum value and dividing by the new maximum value. This ensures the lowest resulting value is 0 and the highest resulting value is 1.
• "symmetric": divides the values by the maximum absolute value, resulting in a range of [-1, 1].
• "maximum": divides the values by the maximum value. If all values are positive, this normalizes them to the range [0, 1] without shifting the minimum value to zero. The sign of values does not change. If negative values are present, the result may extend below -1.
• "reference": is similar to "maximum", except it divides by a user-defined reference value. A reference value must be provided. Resulting values can fall outside the range [-1, 1].

NaN values are ignored when normalizing. All-NaN pixel maps results in a ValueError.

Examples:

>>> PixelMap([[1, 3, 5]]).normalize()  # Default is zero-based normalization
PixelMap(values=array([[0. , 0.5, 1. ]]), ...)

>>> PixelMap([[1, 3, 5]]).normalize(mode="maximum")
PixelMap(values=array([[0.2, 0.6, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize()
PixelMap(values=array([[0. , 0.7, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="symmetric")
PixelMap(values=array([[-1.   , -0.125,  0.25 ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="reference", reference=4)
PixelMap(values=array([[-2.  , -0.25,  0.5 ]]), ...)

PARAMETER	DESCRIPTION
mode	The normalization mode to use. Defaults to "zero-based". TYPE: Literal['zero-based', 'symmetric', 'maximum', 'reference'] DEFAULT: 'zero-based'
reference	The reference value to use for normalization in "reference" mode. TYPE: float | None DEFAULT: None
kwargs	Additional keyword arguments to pass to the new PixelMap instance. TYPE: dict DEFAULT: {}

RAISES	DESCRIPTION
ValueError	If an invalid normalization mode is specified.
ValueError	If no reference value is provided in "reference" mode.
ValueError	If a reference value is provided with a mode other than "reference".
TypeError	If the reference value is not a number.
ZeroDivisionError	If normalization by zero is attempted (either reference=0, or the maximum (absolute) value in the values is 0).
ValueError	If normalization by NaN is attempted (either reference=np.nan, or all values are NaN).

WARNS	DESCRIPTION
UserWarning	If normalization by a negative number is attempted (either reference is negative, or all values are negative). This results in inverting the sign of the values.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.

PendelluftMap dataclass

PendelluftMap(
    values: ndarray,
    *,
    label: str | None = None,
    plot_config: InitVar[PixelMapPlotConfig]
)

Pixel map representing positive-only pendelluft values.

Values represent pendelluft severity as positive values. There is no distinction between pixels with early inflation and pixels with late inflation. Alternatively, you can use a SignedPendelluftMap for signed data.

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(
    *,
    mode: Literal[
        "zero-based", "symmetric", "maximum", "reference"
    ] = "zero-based",
    reference: float | None = None,
    **kwargs
) -> Self

Normalize the pixel map values.

Creates a copy of the pixel map with normalized values. Four normalization modes are available.

• "zero-based" (default): normalizes the values to the range [0, 1] by subtracting the minimum value and dividing by the new maximum value. This ensures the lowest resulting value is 0 and the highest resulting value is 1.
• "symmetric": divides the values by the maximum absolute value, resulting in a range of [-1, 1].
• "maximum": divides the values by the maximum value. If all values are positive, this normalizes them to the range [0, 1] without shifting the minimum value to zero. The sign of values does not change. If negative values are present, the result may extend below -1.
• "reference": is similar to "maximum", except it divides by a user-defined reference value. A reference value must be provided. Resulting values can fall outside the range [-1, 1].

NaN values are ignored when normalizing. All-NaN pixel maps results in a ValueError.

Examples:

>>> PixelMap([[1, 3, 5]]).normalize()  # Default is zero-based normalization
PixelMap(values=array([[0. , 0.5, 1. ]]), ...)

>>> PixelMap([[1, 3, 5]]).normalize(mode="maximum")
PixelMap(values=array([[0.2, 0.6, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize()
PixelMap(values=array([[0. , 0.7, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="symmetric")
PixelMap(values=array([[-1.   , -0.125,  0.25 ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="reference", reference=4)
PixelMap(values=array([[-2.  , -0.25,  0.5 ]]), ...)

PARAMETER	DESCRIPTION
mode	The normalization mode to use. Defaults to "zero-based". TYPE: Literal['zero-based', 'symmetric', 'maximum', 'reference'] DEFAULT: 'zero-based'
reference	The reference value to use for normalization in "reference" mode. TYPE: float | None DEFAULT: None
kwargs	Additional keyword arguments to pass to the new PixelMap instance. TYPE: dict DEFAULT: {}

RAISES	DESCRIPTION
ValueError	If an invalid normalization mode is specified.
ValueError	If no reference value is provided in "reference" mode.
ValueError	If a reference value is provided with a mode other than "reference".
TypeError	If the reference value is not a number.
ZeroDivisionError	If normalization by zero is attempted (either reference=0, or the maximum (absolute) value in the values is 0).
ValueError	If normalization by NaN is attempted (either reference=np.nan, or all values are NaN).

WARNS	DESCRIPTION
UserWarning	If normalization by a negative number is attempted (either reference is negative, or all values are negative). This results in inverting the sign of the values.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.

SignedPendelluftMap dataclass

SignedPendelluftMap(
    values: ndarray,
    *,
    label: str | None = None,
    plot_config: InitVar[PixelMapPlotConfig]
)

Pixel map representing pendelluft values as signed values.

Values represent pendelluft severity. Negative values indicate pixels that have early inflation (before the global inflation starts), while negative values indicate pixels that have late inflation (after the global inflation starts).

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(
    *,
    mode: Literal[
        "zero-based", "symmetric", "maximum", "reference"
    ] = "zero-based",
    reference: float | None = None,
    **kwargs
) -> Self

Normalize the pixel map values.

Creates a copy of the pixel map with normalized values. Four normalization modes are available.

• "zero-based" (default): normalizes the values to the range [0, 1] by subtracting the minimum value and dividing by the new maximum value. This ensures the lowest resulting value is 0 and the highest resulting value is 1.
• "symmetric": divides the values by the maximum absolute value, resulting in a range of [-1, 1].
• "maximum": divides the values by the maximum value. If all values are positive, this normalizes them to the range [0, 1] without shifting the minimum value to zero. The sign of values does not change. If negative values are present, the result may extend below -1.
• "reference": is similar to "maximum", except it divides by a user-defined reference value. A reference value must be provided. Resulting values can fall outside the range [-1, 1].

NaN values are ignored when normalizing. All-NaN pixel maps results in a ValueError.

Examples:

>>> PixelMap([[1, 3, 5]]).normalize()  # Default is zero-based normalization
PixelMap(values=array([[0. , 0.5, 1. ]]), ...)

>>> PixelMap([[1, 3, 5]]).normalize(mode="maximum")
PixelMap(values=array([[0.2, 0.6, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize()
PixelMap(values=array([[0. , 0.7, 1. ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="symmetric")
PixelMap(values=array([[-1.   , -0.125,  0.25 ]]), ...)

>>> PixelMap([[-8, -1, 2]]).normalize(mode="reference", reference=4)
PixelMap(values=array([[-2.  , -0.25,  0.5 ]]), ...)

PARAMETER	DESCRIPTION
mode	The normalization mode to use. Defaults to "zero-based". TYPE: Literal['zero-based', 'symmetric', 'maximum', 'reference'] DEFAULT: 'zero-based'
reference	The reference value to use for normalization in "reference" mode. TYPE: float | None DEFAULT: None
kwargs	Additional keyword arguments to pass to the new PixelMap instance. TYPE: dict DEFAULT: {}

RAISES	DESCRIPTION
ValueError	If an invalid normalization mode is specified.
ValueError	If no reference value is provided in "reference" mode.
ValueError	If a reference value is provided with a mode other than "reference".
TypeError	If the reference value is not a number.
ZeroDivisionError	If normalization by zero is attempted (either reference=0, or the maximum (absolute) value in the values is 0).
ValueError	If normalization by NaN is attempted (either reference=np.nan, or all values are NaN).

WARNS	DESCRIPTION
UserWarning	If normalization by a negative number is attempted (either reference is negative, or all values are negative). This results in inverting the sign of the values.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.

IntegerMap dataclass

IntegerMap(
    values: ndarray,
    *,
    label: str | None = None,
    plot_config: InitVar[PixelMapPlotConfig]
)

Pixel map with integer values.

This class is a wrapper around PixelMap that ensures the values are integers. It is useful for pixel maps that represent labels or discrete values.

shape property

shape: tuple[int, int]

Get the shape of the pixel map values.

plotting property

plotting: PixelMapPlotting

A utility class for plotting the pixel map with the specified configuration.

normalize

normalize(*args, **kwargs) -> NoReturn

Normalization is not supported for IntegerMap.

create_mask_from_threshold

create_mask_from_threshold(
    threshold: float,
    *,
    comparator: Callable = greater_equal,
    use_magnitude: bool = False,
    fraction_of_max: bool = False,
    captures: dict | None = None
) -> PixelMask

Create a pixel mask from the pixel map based on threshold values.

The values of the pixel map are compared to the threshold values. By default, the comparator is >= (np.greater_equal), such that the resulting mask is 1.0 where the map values are at least the threshold values, and NaN elsewhere. The comparator can be set to any comparison function, e.g.np.less, a function from the operator module or custom function which takes pixel map values array and threshold as arguments, and returns a boolean array with the same shape as the array.

If use_magnitude is True, absolute values are compared to the threshold.

If fraction_of_max is True, the threshold is interpreted as a fraction of the maximum value in the map. For example, a threshold of 0.2 with fraction_of_max=True will create a mask where values are at least 20% of the maximum value.

The shape of the pixel mask is the same as the shape of the pixel map.

PARAMETER	DESCRIPTION
threshold	The threshold value or fraction, depending on fraction_of_max argument. TYPE: float
comparator	A function that compares pixel values against the threshold. TYPE: Callable DEFAULT: greater_equal
use_magnitude	If True, apply the threshold to the absolute values of the pixel map. TYPE: bool DEFAULT: False
fraction_of_max	If True, interpret threshold as a fraction of the maximum value. TYPE: bool DEFAULT: False
captures	An optional dictionary to capture intermediate results. If None, no captures are made. TYPE: dict | None DEFAULT: None

RETURNS	DESCRIPTION
PixelMask	A PixelMask instance with values 1.0 where comparison is true, and NaN elsewhere. TYPE: PixelMask

RAISES	DESCRIPTION
TypeError	If threshold is not a float or comparator is not callable.

Examples:

pm = PixelMap([[0.1, 0.5, 0.9]]) mask = pm.create_mask_from_threshold(0.5) # Absolute threshold of 0.5 PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, fraction_of_max=True) # 50% of max value (=0.45) PixelMask(mask=array([[nan, 1., 1.]]))

mask = pm.create_mask_from_threshold(0.5, comparator=np.less) PixelMask(mask=array([[ 1., nan, nan]]))

convert_to

convert_to(
    target_type: type[PixelMapT], *, keep_attrs: bool = False, **kwargs: dict
) -> PixelMapT

Convert the pixel map to (a different subclass of) PixelMap.

This method allows for converting the pixel map to a PixelMap or different subclass of PixelMap. The label attribute is copied by default, but a new label can be provided. Other attributes are not copied by default, but can be retained by setting keep_attrs to True. Additional keyword arguments can be passed to the new instance.

PARAMETER	DESCRIPTION
target_type	The target subclass to convert to. TYPE: type[T]
keep_attrs	If True, retains the attributes of the original pixel map in the new instance. TYPE: bool DEFAULT: False
**kwargs	Additional keyword arguments to pass to the new instance. TYPE: dict DEFAULT: {}

RETURNS	DESCRIPTION
T	A new instance of the target type with the same values and attributes. TYPE: PixelMapT

from_aggregate classmethod

from_aggregate(
    maps: Sequence[ArrayLike | PixelMap],
    aggregator: Callable[..., ndarray],
    **return_attrs
) -> Self

Get a pixel map by aggregating several pixel maps with a specified function.

The maps can be 2D numpy arrays, sequences that can be converted to 2D numpy arrays (e.g., nested lists), or PixelMap objects. The aggregation is performed using the provided function along the first axis of the stacked maps. NaN values are typically ignored by using numpy's nan-aware functions (np.nanmean, np.nanmedian, etc.).

Returns the same class as this function was called from. Keyword arguments are passed to the initializer of that object.

PARAMETER	DESCRIPTION
maps	list/tuple of maps to be aggregated TYPE: Sequence[ArrayLike | PixelMap]
aggregator	Function to aggregate the maps along the first axis. Should accept an array and axis parameter. TYPE: Callable[..., ndarray]
**return_attrs	Keyword arguments to be passed to the initializer of the return object DEFAULT: {}

RETURNS	DESCRIPTION
Self	A new instance with the aggregated values of the pixel maps. TYPE: Self

Examples:

>>> maps = [PixelMap([[1, 2]]), PixelMap([[3, 4]]), PixelMap([[5, 6]])]
>>> TIVMap.from_aggregate(maps, np.nanmean)  # Mean: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmedian)  # Median: [[3, 4]]
>>> TIVMap.from_aggregate(maps, np.nanmax)  # Maximum: [[5, 6]]
>>> TIVMap.from_aggregate(maps, np.nanmin)  # Minimum: [[1, 2]]
>>> TIVMap.from_aggregate(maps, lambda x, axis: np.nanpercentile(x, 75, axis=axis))  # 75th percentile

to_boolean_array

to_boolean_array(*, zero: bool = False) -> ndarray

Convert the pixel map values to a boolean array.

NaN values are replaced with False, and the resulting array is cast to boolean. 0-values are converted to False by default. Provided zero=True in case you want to treat 0-values as True.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.

to_integer_array

to_integer_array() -> ndarray

Convert the pixel map values to an integer array.

NaN values are replaced with 0, and the resulting array is cast to integers.

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.

to_non_nan_array

to_non_nan_array(*, nan: float = 0.0, dtype: type | dtype = float) -> ndarray

Convert the pixel map values to a numpy array, replacing NaN with a fill value.

PARAMETER	DESCRIPTION
nan	The value to replace NaN values with. Defaults to 0.0. TYPE: float DEFAULT: 0.0
dtype	The data type of the resulting array. Defaults to float. TYPE: type | dtype DEFAULT: float

RETURNS	DESCRIPTION
ndarray	np.ndarray: A 2D numpy array with NaN values replaced by nan and cast to the specified dtype.