Merge pull request #418 from EIT-ALIVE/feature/389-watershed

Adds a WatershedLungspace class, as well as a lot of general improvements to make this possible.

## PixelMap
An AmplitudeMap and IntegerMap (subclasses of PixelMap) have been added, including plotting configurations. 

For IntegerMaps to be possible, the data type of PixelMap values has been made variable (set per class), and casting to that type has been made safe (i.e., a change in actual value when converting from e.g. float to int will throw an error). 

Creating a mask from a PixelMap has been improved.

PixelMap now has three methods to get the values array as boolean, integer or non-nan-float array.

PixelMap plotting now has contour and surface methods.

## PixelMask

PixelMasks can now be plotted using the same imshow method as PixelMap. 

PixelMasks gains a subtraction method. 

The standard masks are now generated using get_geomtric_mask, which allows for different shapes.

## TIV and AmplitudeLungspace
TIVLungspace and AmplitudeLungspace provide easy determination of functional lung space.

## Warnings
The stack level of warnings has been set to 2 everywhere. Also, warnings in tests have been explicitly silenced.

Author: psomhorst

docs/api/datacontainers/pixelmap.md

@@ -4,8 +4,10 @@
         - PixelMap
         - DifferenceMap
         - TIVMap
+        - AmplitudeMap
         - ODCLMap
         - PerfusionMap
         - PendelluftMap
         - SignedPendelluftMap
+        - IntegerMap
         - PlotParameters

docs/api/roi/tivlungspace.md

@@ -0,0 +1,3 @@
+::: eitprocessing.roi.tiv.TIVLungspace
+
+::: eitprocessing.roi.amplitude.AmplitudeLungspace

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):