Add WatershedLungspace class

docs/api/roi/watershed.md

@@ -0,0 +1 @@
+::: eitprocessing.roi.watershed.WatershedLungspace

eitprocessing/datahandling/continuousdata.py

@@ -58,7 +58,7 @@ def __post_init__(self) -> None:
                 "`sample_frequency` is set to `None`. This will not be supported in future versions. "
                 "Provide a sample frequency when creating a ContinuousData object."
             )
-            warnings.warn(msg, DeprecationWarning)
+            warnings.warn(msg, DeprecationWarning, stacklevel=2)
 
         if (lv := len(self.values)) != (lt := len(self.time)):
             msg = f"The number of time points ({lt}) does not match the number of values ({lv})."

eitprocessing/datahandling/eitdata.py

@@ -1,15 +1,16 @@
 from __future__ import annotations
 
 import warnings
-from dataclasses import dataclass, field
+from dataclasses import InitVar, dataclass, field
 from enum import auto
 from pathlib import Path
-from typing import TYPE_CHECKING, TypeVar
+from typing import TYPE_CHECKING, Any, TypeVar
 
 import numpy as np
-from strenum import LowercaseStrEnum
+from strenum import LowercaseStrEnum  # TODO: EOL 3.10: replace with native StrEnum
 
 from eitprocessing.datahandling import DataContainer
+from eitprocessing.datahandling.continuousdata import ContinuousData
 from eitprocessing.datahandling.mixins.slicing import SelectByTime
 
 if TYPE_CHECKING:
@@ -49,8 +50,9 @@ class is meant to hold data from (part of) a singular continuous measurement.
     description: str = field(default="", compare=False, repr=False)
     name: str | None = field(default=None, compare=False, repr=False)
     pixel_impedance: np.ndarray = field(repr=False, kw_only=True)
+    suppress_simulated_warning: InitVar[bool] = False
 
-    def __post_init__(self):
+    def __post_init__(self, suppress_simulated_warning: bool) -> None:
         if not self.label:
             self.label = f"{self.__class__.__name__}_{id(self)}"
 
@@ -64,12 +66,21 @@ def __post_init__(self):
             msg = f"The number of time points ({lt}) does not match the number of pixel impedance values ({lv})."
             raise ValueError(msg)
 
+        if not suppress_simulated_warning and self.vendor == Vendor.SIMULATED:
+            warnings.warn(
+                "The simulated vendor is used for testing purposes. "
+                "It is not a real vendor and should not be used in production code.",
+                UserWarning,
+                stacklevel=2,
+            )
+
     @property
     def framerate(self) -> float:
         """Deprecated alias to `sample_frequency`."""
         warnings.warn(
             "The `framerate` attribute has been deprecated. Use `sample_frequency` instead.",
             DeprecationWarning,
+            stacklevel=2,
         )
         return self.sample_frequency
 
@@ -135,6 +146,28 @@ def _sliced_copy(
     def __len__(self):
         return self.pixel_impedance.shape[0]
 
+    def get_summed_impedance(self, *, return_label: str | None = None, **return_kwargs) -> ContinuousData:
+        """Return a ContinuousData-object with the same time axis and summed pixel values over time.
+
+        Args:
+            return_label: The label of the returned object; defaults to 'summed <label>' where '<label>' is the label of
+            the current object.
+            **return_kwargs: Keyword arguments for the creation of the returned object.
+        """
+        summed_impedance = np.nansum(self.pixel_impedance, axis=(1, 2))
+
+        if return_label is None:
+            return_label = f"summed {self.label}"
+
+        return_kwargs_: dict[str, Any] = {
+            "name": return_label,
+            "unit": "AU",
+            "category": "impedance",
+            "sample_frequency": self.sample_frequency,
+        } | return_kwargs
+
+        return ContinuousData(label=return_label, time=np.copy(self.time), values=summed_impedance, **return_kwargs_)
+
     def calculate_global_impedance(self) -> np.ndarray:
         """Return the global impedance, i.e. the sum of all included pixels at each frame."""
         return np.nansum(self.pixel_impedance, axis=(1, 2))
@@ -148,3 +181,4 @@ class Vendor(LowercaseStrEnum):
     SENTEC = auto()
     DRAGER = DRAEGER
     DRÄGER = DRAEGER  # noqa: PLC2401
+    SIMULATED = auto()

eitprocessing/datahandling/loading/draeger.py

@@ -68,7 +68,7 @@ def load_from_single_path(
             f"the first frame selected ({first_frame}, total frames: "
             f"{total_frames}).\n {n_frames} frames will be loaded."
         )
-        warnings.warn(msg)
+        warnings.warn(msg, RuntimeWarning, stacklevel=2)
 
     # We need to load 1 frame before first actual frame to check if there is an event marker. Data for the pre-first
     # (dummy) frame will be removed from self at the end of this function.
@@ -194,7 +194,7 @@ def _estimate_sample_frequency(time: np.ndarray, sample_frequency: float | None)
             f"Provided sample frequency ({sample_frequency}) does not match "
             f"the estimated sample frequency ({estimated_sample_frequency})."
         )
-        warnings.warn(msg, RuntimeWarning)
+        warnings.warn(msg, RuntimeWarning, stacklevel=2)
 
     return sample_frequency
 
@@ -274,7 +274,7 @@ def _read_frame(
     if ((previous_marker is not None) and (event_marker > previous_marker)) or (index == 0 and event_text):
         events.append((frame_time, Event(event_marker, event_text)))
     if timing_error:
-        warnings.warn("A timing error was encountered during loading.")
+        warnings.warn("A timing error was encountered during loading.", RuntimeWarning, stacklevel=2)
         # TODO: expand on what timing errors are in some documentation.
     if min_max_flag in (1, -1):
         phases.append((frame_time, min_max_flag))

eitprocessing/datahandling/loading/sentec.py

@@ -90,7 +90,7 @@ def load_from_single_path(  # noqa: C901, PLR0912
                         "Sample frequency value found in file. "
                         f"The sample frequency value will be set to {sample_frequency:.2f}"
                     )
-                    warnings.warn(msg)
+                    warnings.warn(msg, RuntimeWarning, stacklevel=2)
 
                 else:
                     fh.seek(payload_size, os.SEEK_CUR)
@@ -108,7 +108,7 @@ def load_from_single_path(  # noqa: C901, PLR0912
             f"the first frame selected ({first_frame}, total frames: "
             f"{index}).\n {n_frames} frames will be loaded."
         )
-        warnings.warn(msg)
+        warnings.warn(msg, RuntimeWarning, stacklevel=2)
 
     if not sample_frequency:
         sample_frequency = SENTEC_SAMPLE_FREQUENCY

eitprocessing/datahandling/loading/timpel.py

@@ -74,6 +74,8 @@ def load_from_single_path(
                 f"than the available number ({data.shape[0]}) of frames after "
                 f"the first frame selected ({first_frame}).\n"
                 f"{data.shape[0]} frames have been loaded.",
+                RuntimeWarning,
+                stacklevel=2,
             )
         nframes = data.shape[0]
 

eitprocessing/datahandling/mixins/slicing.py

@@ -52,7 +52,7 @@ def select_by_index(
         object is attached.
         """
         if start is None and end is None:
-            warnings.warn("No starting or end timepoint was selected.")
+            warnings.warn("No starting or end timepoint was selected.", UserWarning, stacklevel=2)
             return self
 
         start = start if start is not None else 0
@@ -144,7 +144,7 @@ def select_by_time(  # noqa: D417
             return copy.deepcopy(self)
 
         if start_time is None and end_time is None:
-            warnings.warn("No starting or end timepoint was selected.")
+            warnings.warn("No starting or end timepoint was selected.", UserWarning, stacklevel=2)
             return self
 
         if not np.all(np.sort(self.time) == self.time):

eitprocessing/datahandling/pixelmap.py

@@ -48,12 +48,14 @@
 import sys
 import warnings
 from dataclasses import KW_ONLY, InitVar, asdict, dataclass, field, replace
-from typing import TYPE_CHECKING, ClassVar, Literal, TypeVar, cast
+from typing import TYPE_CHECKING, ClassVar, Literal, NoReturn, TypeVar, cast
 
 import numpy as np
 from numpy import typing as npt
 from typing_extensions import Self
 
+from eitprocessing.utils import make_capture
+
 if TYPE_CHECKING:
     from collections.abc import Callable, Sequence
 
@@ -64,7 +66,7 @@
 PixelMapT = TypeVar("PixelMapT", bound="PixelMap")
 
 
-@dataclass(frozen=True, init=False)
+@dataclass(frozen=True)
 class PixelMap:
     """Map representing a single value for each pixel.
 
@@ -112,13 +114,15 @@ def __init__(
                 f"{self.__class__.__name__} initialized with all NaN values. "
                 "This may lead to unexpected behavior in plotting or analysis.",
                 UserWarning,
+                stacklevel=2,
             )
 
         if not self.allow_negative_values and not suppress_negative_warning and np.any(values < 0):
             warnings.warn(
                 f"{self.__class__.__name__} initialized with negative values, but `allow_negative_values` is False. "
                 "This may lead to unexpected behavior in plotting or analysis.",
                 UserWarning,
+                stacklevel=2,
             )
 
         values.flags.writeable = False  # Make the values array immutable
@@ -263,14 +267,18 @@ def _check_normalization_reference(reference_: float) -> None:
                 )
             raise exc
         if reference_ < 0:
-            warnings.warn("Normalization by a negative number may lead to unexpected results.", UserWarning)
+            warnings.warn(
+                "Normalization by a negative number may lead to unexpected results.", UserWarning, stacklevel=2
+            )
 
     def create_mask_from_threshold(
         self,
         threshold: float,
         *,
         comparator: Callable = np.greater_equal,
-        absolute: bool = False,
+        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.
 
@@ -280,14 +288,21 @@ def create_mask_from_threshold(
         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 `absolute` is True, absolute values are compared to the threshold.
+        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.
 
         Args:
-            threshold (float): The threshold value.
+            threshold (float): The threshold value or fraction, depending on `fraction_of_max` argument.
             comparator (Callable): A function that compares pixel values against the threshold.
-            absolute (bool): If True, apply the threshold to the absolute values of the pixel map.
+            use_magnitude (bool): If True, apply the threshold to the absolute values of the pixel map.
+            fraction_of_max (bool): If True, interpret threshold as a fraction of the maximum value.
+            captures (dict | None):
+                An optional dictionary to capture intermediate results. If None, no captures are made.
 
         Returns:
             PixelMask:
@@ -298,14 +313,17 @@ def create_mask_from_threshold(
 
         Examples:
         >>> pm = PixelMap([[0.1, 0.5, 0.9]])
-        >>> mask = pm.create_mask_from_threshold(0.5)
+        >>> 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.apply(pm)
-        PixelMap(values=array([[nan, 0.5, 0.9]]), ...)
 
         >>> mask = pm.create_mask_from_threshold(0.5, comparator=np.less)
         PixelMask(mask=array([[ 1., nan, nan]]))
         """
+        capture = make_capture(captures)
+
         if not isinstance(threshold, (float, np.floating, int, np.integer)):
             msg = "`threshold` must be a number."
             raise TypeError(msg)
@@ -316,8 +334,22 @@ def create_mask_from_threshold(
 
         from eitprocessing.roi import PixelMask
 
-        compare_values = np.abs(self.values) if absolute else self.values
-        mask_values = comparator(compare_values, threshold)
+        compare_values = np.abs(self.values) if use_magnitude else self.values
+
+        if fraction_of_max:
+            # Convert the threshold to an absolute value
+            max_val = np.nanmax(compare_values)
+
+            if np.isnan(max_val):
+                msg = ("All values in the pixel map are NaN. Cannot compute fraction of maximum value.",)
+                raise ValueError(msg)
+
+            actual_threshold = threshold * max_val
+        else:
+            actual_threshold = threshold
+        capture("actual threshold", actual_threshold)
+
+        mask_values = comparator(compare_values, actual_threshold)
         return PixelMask(mask_values)
 
     @property
@@ -419,7 +451,7 @@ def __mul__(self, other: npt.ArrayLike | float | PixelMap) -> PixelMap:
     def __truediv__(self, other: npt.ArrayLike | float | PixelMap) -> PixelMap:
         other_values = self._validate_other(other)
         if isinstance(other_values, np.ndarray) and 0 in other_values:
-            warnings.warn("Dividing by 0 will result in `np.nan` value.", UserWarning)
+            warnings.warn("Dividing by 0 will result in `np.nan` value.", UserWarning, stacklevel=2)
 
         invalid = np.isnan(self.values) | np.isnan(other_values) | (other_values == 0)
         new_values = np.divide(self.values, other_values, where=~invalid)
@@ -431,7 +463,7 @@ def __truediv__(self, other: npt.ArrayLike | float | PixelMap) -> PixelMap:
     def __rtruediv__(self, other: npt.ArrayLike | float | PixelMap) -> PixelMap:
         other_values = self._validate_other(other)
         if 0 in self.values:
-            warnings.warn("Dividing by 0 will result in `np.nan` value.", UserWarning)
+            warnings.warn("Dividing by 0 will result in `np.nan` value.", UserWarning, stacklevel=2)
         invalid = np.isnan(self.values) | np.isnan(other_values) | (self.values == 0)
         new_values = np.divide(other_values, self.values, where=~invalid)
         new_values[invalid] = np.nan
@@ -490,6 +522,38 @@ def _get_values(map_: npt.ArrayLike | PixelMap) -> np.ndarray:
         aggregated_values = aggregator(stacked, axis=0)
         return cls(values=aggregated_values, **return_attrs)
 
+    def to_boolean_array(self) -> np.ndarray:
+        """Convert the pixel map values to a boolean array.
+
+        NaN values are replaced with False, and the resulting array is cast to boolean.
+
+        Returns:
+            np.ndarray: A 2D numpy array of booleans, where NaN values are replaced with False.
+        """
+        return self.to_nan_nan_array(0, bool)
+
+    def to_integer_array(self) -> np.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:
+            np.ndarray: A 2D numpy array of integers, where NaN values are replaced with 0.
+        """
+        return self.to_non_nan_array(0, int)
+
+    def to_non_nan_array(self, fill_value: float = 0.0, dtype: type | np.dtype = float) -> np.ndarray:
+        """Convert the pixel map values to a numpy array, replacing NaN with a fill value.
+
+        Args:
+            fill_value (float): The value to replace NaN values with. Defaults to 0.0.
+            dtype (type | np.dtype): The data type of the resulting array. Defaults to float.
+
+        Returns:
+            np.ndarray: A 2D numpy array with NaN values replaced by `fill_value` and cast to the specified `dtype`.
+        """
+        return np.nan_to_num(self.values, nan=fill_value).astype(dtype)
+
 
 @dataclass(frozen=True, init=False)
 class TIVMap(PixelMap):
@@ -547,3 +611,24 @@ class SignedPendelluftMap(PixelMap):
     inflation starts), while negative values indicate pixels that have late inflation (after the global inflation
     starts).
     """
+
+
+@dataclass(frozen=True, init=False)
+class IntegerMap(PixelMap):
+    """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.
+    """
+
+    def __init__(self, values: npt.ArrayLike, **kwargs):
+        values_ = np.asarray(values, dtype=int)
+        super().__init__(values=values_, **kwargs)
+        values_ = values_.astype(int)
+        values_.flags.writeable = False  # Make the values array immutable
+        object.__setattr__(self, "values", values_)
+
+    def normalize(self, *args, **kwargs) -> NoReturn:
+        """Normalization is not supported for IntegerPixelMap."""
+        msg = "Normalization is not supported for IntegerPixelMap."
+        raise NotImplementedError(msg)