Add WatershedLungspace class

docs/api/roi/tivlungspace.md

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

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