FlowCyPy 0.7.0__py3-none-any.whl

FlowCyPy/peak_locator/base_class.py

@@ -0,0 +1,163 @@
+import numpy as np
+import pandas as pd
+from scipy.integrate import cumulative_trapezoid
+import matplotlib.pyplot as plt
+import pint_pandas
+from abc import ABC, abstractmethod
+from FlowCyPy.units import Quantity
+from scipy.signal import peak_widths
+
+
+class BasePeakLocator(ABC):
+    """
+    A base class to handle common functionality for peak detection,
+    including area calculation under peaks.
+    """
+
+    peak_properties: pd.DataFrame = None
+
+    def init_data(self, dataframe: pd.DataFrame) -> None:
+        """
+        Initialize signal and time data for peak detection.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            A DataFrame containing the signal data with columns 'Signal' and 'Time'.
+
+        Raises
+        ------
+        ValueError
+            If the DataFrame is missing required columns or is empty.
+        """
+        if not {'Signal', 'Time'}.issubset(dataframe.columns):
+            raise ValueError("The DataFrame must contain 'Signal' and 'Time' columns.")
+
+        if dataframe.empty:
+            raise ValueError("The DataFrame is empty. Please provide valid signal data.")
+
+        self.data = pd.DataFrame(index=np.arange(len(dataframe)))
+        self.data['Signal'] = dataframe['Signal']
+        self.data['Time'] = dataframe['Time']
+
+        self.dt = self.data.Time[1] - self.data.Time[0]
+
+    @abstractmethod
+    def _compute_algorithm_specific_features(self) -> None:
+        """
+        Abstract method for computing features specific to the detection algorithm.
+        This must be implemented by subclasses.
+        """
+        pass
+
+    def detect_peaks(self, compute_area: bool = True) -> pd.DataFrame:
+        """
+        Detect peaks and compute peak properties.
+
+        Parameters
+        ----------
+        compute_area : bool, optional
+            If True, computes the area under each peak (default is True).
+
+        Returns
+        -------
+        pd.DataFrame
+            A DataFrame containing peak properties (times, heights, widths, etc.).
+        """
+        peak_indices, widths_samples, width_heights, left_ips, right_ips = self._compute_algorithm_specific_features()
+
+        peak_times = self.data['Time'].values[peak_indices]
+        heights = self.data['Signal'].values[peak_indices]
+        widths = widths_samples * self.dt
+
+        # Store results in `peak_properties`
+        self.peak_properties = pd.DataFrame({
+            'PeakTimes': peak_times,
+            'Heights': heights,
+            'Widths': pint_pandas.PintArray(widths, dtype=widths.units),
+            'WidthHeights': pint_pandas.PintArray(width_heights, dtype=heights.units),
+            'LeftIPs': pint_pandas.PintArray(left_ips * self.dt, dtype=self.dt.units),
+            'RightIPs': pint_pandas.PintArray(right_ips * self.dt, dtype=self.dt.units),
+        })
+
+        # Compute areas if needed
+        if compute_area:
+            self._compute_peak_areas()
+
+        return self.peak_properties
+
+    def _compute_peak_areas(self) -> None:
+        """
+        Computes the areas under the detected peaks using cumulative integration.
+
+        The cumulative integral of the signal is interpolated at the left and right
+        interpolated positions of each peak to compute the enclosed area.
+
+        Adds an 'Areas' column to `self.peak_properties`.
+
+        Raises
+        ------
+        RuntimeError
+            If `peak_properties` or `data` has not been initialized.
+        """
+        if not hasattr(self, 'peak_properties') or self.peak_properties.empty:
+            raise RuntimeError("No peaks detected. Run `detect_peaks()` first.")
+
+        if not hasattr(self, 'data') or self.data.empty:
+            raise RuntimeError("Signal data is not initialized. Call `init_data()` first.")
+
+        # Compute cumulative integral of the signal
+        cumulative = cumulative_trapezoid(
+            self.data.Signal.values.quantity.magnitude,
+            x=self.data.Time.values.quantity.magnitude,
+            initial=0  # Include 0 at the start
+        )
+
+        # Interpolate cumulative integral at left and right interpolated positions
+        left_cum_integral = np.interp(
+            x=self.peak_properties.LeftIPs,
+            xp=self.data.index,
+            fp=cumulative
+        )
+        right_cum_integral = np.interp(
+            x=self.peak_properties.RightIPs,
+            xp=self.data.index,
+            fp=cumulative
+        )
+
+        # Compute areas under peaks
+        areas = right_cum_integral - left_cum_integral
+
+        # Add areas with units to peak properties
+        self.peak_properties['Areas'] = pint_pandas.PintArray(
+            areas, dtype=self.data.Signal.pint.units * self.data.Time.pint.units
+        )
+
+    def _add_to_ax(self, time_unit: str | Quantity, signal_unit: str | Quantity, ax: plt.Axes = None) -> None:
+        """
+        Plots the signal with detected peaks and FWHM lines.
+
+        Parameters
+        ----------
+        time_unit : str or Quantity
+            Unit for the time axis (e.g., 'microsecond').
+        signal_unit : str or Quantity
+            Unit for the signal axis (e.g., 'volt').
+        ax : plt.Axes
+            The matplotlib Axes to plot on. Creates a new figure if not provided.
+        """
+        # Plot vertical lines at peak times
+        for _, row in self.peak_properties.iterrows():
+            ax.axvline(row['PeakTimes'].to(time_unit), color='black', linestyle='-', lw=0.8)
+
+        self._add_custom_to_ax(ax=ax, time_unit=time_unit, signal_unit=signal_unit)
+
+    def _compute_peak_widths(self, peak_indices: list[int], values: np.ndarray) -> None:
+        # Compute peak properties
+        widths_samples, width_heights, left_ips, right_ips = peak_widths(
+            x=values,
+            peaks=peak_indices,
+            rel_height=self.rel_height
+        )
+
+        return widths_samples, width_heights, left_ips, right_ips

FlowCyPy/peak_locator/basic.py

@@ -0,0 +1,108 @@
+from dataclasses import dataclass
+import matplotlib.pyplot as plt
+import pandas as pd
+import numpy as np
+from scipy.signal import find_peaks
+from FlowCyPy.peak_locator.base_class import BasePeakLocator
+from FlowCyPy.units import Quantity, volt
+
+
+@dataclass
+class BasicPeakLocator(BasePeakLocator):
+    """
+    A basic peak detector class that identifies peaks in a signal using a threshold-based method.
+
+    Parameters
+    ----------
+    threshold : Quantity, optional
+        The minimum height required for a peak to be considered significant. Default is `Quantity(0.1, volt)`.
+    min_peak_distance : Quantity, optional
+        The minimum distance between detected peaks. Default is `Quantity(0.1)`.
+    rel_height : float, optional
+        The relative height at which the peak width is measured. Default is `0.5`.
+
+    """
+
+    threshold: Quantity = Quantity(0.0, volt)
+    rel_height: float = 0.5
+    min_peak_distance: Quantity = None
+
+    def init_data(self, dataframe: pd.DataFrame) -> None:
+        """
+        Initialize the data for peak detection.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            A DataFrame containing the signal data with columns 'Signal' and 'Time'.
+
+        Raises
+        ------
+        ValueError
+            If the DataFrame is missing required columns or is empty.
+        """
+        super().init_data(dataframe)
+
+        if self.threshold is not None:
+            self.threshold = self.threshold.to(self.data['Signal'].values.units)
+
+        if self.min_peak_distance is not None:
+            self.min_peak_distance = self.min_peak_distance.to(self.data['Time'].values.units)
+
+    def _compute_algorithm_specific_features(self) -> None:
+        """
+        Compute peaks based on the moving average algorithm.
+        """
+        peak_indices = self._compute_peak_positions()
+
+        widths_samples, width_heights, left_ips, right_ips = self._compute_peak_widths(
+            peak_indices,
+            self.data['Signal'].values
+        )
+
+        return peak_indices, widths_samples, width_heights, left_ips, right_ips
+
+    def _compute_peak_positions(self) -> pd.DataFrame:
+        """
+        Detects peaks in the signal and calculates their properties such as heights, widths, and areas.
+
+        Parameters
+        ----------
+        detector : pd.DataFrame
+            DataFrame with the signal data to detect peaks in.
+
+        Returns
+        -------
+        peak_times : Quantity
+            The times at which peaks occur.
+        heights : Quantity
+            The heights of the detected peaks.
+        widths : Quantity
+            The widths of the detected peaks.
+        areas : Quantity or None
+            The areas under each peak, if `compute_area` is True.
+        """
+        # Find peaks in the difference signal
+        peak_indices, _ = find_peaks(
+            self.data['Signal'].values,
+            height=None if self.threshold is None else self.threshold.magnitude,
+            distance=None if self.min_peak_distance is None else int(np.ceil(self.min_peak_distance / self.dt))
+        )
+
+        return peak_indices
+
+    def _add_custom_to_ax(self, time_unit: str | Quantity, signal_unit: str | Quantity, ax: plt.Axes = None) -> None:
+        """
+        Add algorithm-specific elements to the plot.
+
+        Parameters
+        ----------
+        time_unit : str or Quantity
+            The unit for the time axis (e.g., 'microsecond').
+        signal_unit : str or Quantity
+            The unit for the signal axis (e.g., 'volt').
+        ax : matplotlib.axes.Axes
+            The Axes object to add elements to.
+        """
+        # Plot the signal threshold line
+        ax.axhline(y=self.threshold.to(signal_unit).magnitude, color='black', linestyle='--', label='Threshold', lw=1)

FlowCyPy/peak_locator/derivative.py

@@ -0,0 +1,143 @@
+from dataclasses import dataclass
+import numpy as np
+import matplotlib.pyplot as plt
+from scipy.signal import find_peaks
+from FlowCyPy.peak_locator.base_class import BasePeakLocator
+import pandas as pd
+import pint_pandas
+from FlowCyPy.units import Quantity, microsecond
+
+
+@dataclass
+class DerivativePeakLocator(BasePeakLocator):
+    """
+    Detects peaks in a signal using a derivative-based algorithm.
+    A peak is identified when the derivative exceeds a defined threshold.
+
+    Parameters
+    ----------
+    derivative_threshold : Quantity, optional
+        The minimum derivative value required to detect a peak.
+        Default is `Quantity(0.1)`.
+    min_peak_distance : Quantity, optional
+        The minimum distance between detected peaks.
+        Default is `Quantity(0.1)`.
+    rel_height : float, optional
+        The relative height at which the peak width is measured. Default is `0.5` (half-height).
+
+    """
+
+    derivative_threshold: Quantity = Quantity(0.1, 'volt/microsecond')
+    min_peak_distance: Quantity = Quantity(0.1, microsecond)
+    rel_height: float = 0.5
+
+    def init_data(self, dataframe: pd.DataFrame) -> None:
+        """
+        Initialize the data for peak detection.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            A DataFrame containing the signal data with columns 'Signal' and 'Time'.
+
+        Raises
+        ------
+        ValueError
+            If the DataFrame is missing required columns or is empty.
+        """
+        super().init_data(dataframe)
+
+        if self.derivative_threshold is not None:
+            self.derivative_threshold = self.derivative_threshold.to(
+                self.data['Signal'].values.units / self.data['Time'].values.units
+            )
+
+        if self.min_peak_distance is not None:
+            self.min_peak_distance = self.min_peak_distance.to(self.data['Time'].values.units)
+
+    def _compute_algorithm_specific_features(self) -> None:
+        """
+        Compute peaks based on the moving average algorithm.
+        """
+        peak_indices = self._compute_peak_positions()
+
+        widths_samples, width_heights, left_ips, right_ips = self._compute_peak_widths(
+            peak_indices,
+            self.data['Signal'].values
+        )
+
+        return peak_indices, widths_samples, width_heights, left_ips, right_ips
+
+    def _compute_peak_positions(self) -> None:
+        """
+        Compute peaks based on the derivative of the signal and refine their positions
+        to align with the actual maxima in the original signal.
+        """
+        # Compute the derivative of the signal
+        derivative = np.gradient(
+            self.data['Signal'].values.quantity.magnitude,
+            self.data['Time'].values.quantity.magnitude
+        )
+        derivative = pint_pandas.PintArray(
+            derivative, dtype=self.data['Signal'].values.units / self.data['Time'].values.units
+        )
+
+        # Add the derivative to the DataFrame
+        self.data['Derivative'] = derivative
+
+        # Detect peaks in the derivative signal
+        derivative_peak_indices, _ = find_peaks(
+            self.data['Derivative'].values.quantity.magnitude,
+            height=self.derivative_threshold.magnitude,
+            prominence=0.1,  # Adjust this if needed
+            plateau_size=True,
+            distance=None if self.min_peak_distance is None else int(np.ceil(self.min_peak_distance / self.dt))
+        )
+
+        # Refine detected peaks to align with maxima in the original signal
+        refined_peak_indices = []
+        refinement_window = 5  # Number of samples around each derivative peak to search for the max
+
+        for idx in derivative_peak_indices:
+            # Define search window boundaries
+            window_start = max(0, idx - refinement_window)
+            window_end = min(len(self.data) - 1, idx + refinement_window)
+
+            # Find the maximum in the original signal within the window
+            true_max_idx = window_start + np.argmax(self.data['Signal'].iloc[window_start:window_end])
+            refined_peak_indices.append(true_max_idx)
+
+        refined_peak_indices = np.unique(refined_peak_indices)  # Remove duplicates
+
+        return refined_peak_indices
+
+    def _add_custom_to_ax(self, time_unit: str | Quantity, signal_unit: str | Quantity, ax: plt.Axes) -> None:
+        """
+        Add algorithm-specific elements to the plot.
+
+        Parameters
+        ----------
+        time_unit : str or Quantity
+            The unit for the time axis (e.g., 'microsecond').
+        signal_unit : str or Quantity
+            The unit for the signal axis (e.g., 'volt').
+        ax : matplotlib.axes.Axes
+            The Axes object to add elements to.
+        """
+        # Plot the derivative
+        ax.plot(
+            self.data.Time,
+            self.data.Derivative,
+            linestyle='--',
+            color='C2',
+            label='Derivative'
+        )
+
+        # Plot the derivative threshold line
+        ax.axhline(
+            y=self.derivative_threshold.to(self.data['Derivative'].values.units).magnitude,
+            color='black',
+            linestyle='--',
+            label='Derivative Threshold',
+            lw=1
+        )

FlowCyPy/peak_locator/moving_average.py

@@ -0,0 +1,166 @@
+from dataclasses import dataclass
+import numpy as np
+import matplotlib.pyplot as plt
+from scipy.signal import find_peaks
+from FlowCyPy.peak_locator.base_class import BasePeakLocator
+import pandas as pd
+import pint_pandas
+from FlowCyPy.units import Quantity
+from pint_pandas import PintArray
+from typing import Tuple, Callable
+
+
+@dataclass
+class MovingAverage(BasePeakLocator):
+    """
+    Detects peaks in a signal using a moving average algorithm.
+    A peak is identified when the signal exceeds the moving average by a defined threshold.
+
+    Parameters
+    ----------
+    threshold : Quantity, optional
+        The minimum difference between the signal and its moving average required to detect a peak. Default is `Quantity(0.2)`.
+    window_size : Quantity, optional
+        The window size for calculating the moving average. Default is `Quantity(500)`.
+    min_peak_distance : Quantity, optional
+        The minimum distance between detected peaks. Default is `Quantity(0.1)`.
+    rel_height : float, optional
+        The relative height at which the peak width is measured. Default is `0.5` (half-height).
+
+    """
+
+    threshold: Quantity
+    window_size: Quantity
+    min_peak_distance: Quantity = None
+    rel_height: float = 0.1
+
+    def init_data(self, dataframe: pd.DataFrame) -> None:
+        """
+        Initialize the data for peak detection.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            A DataFrame containing the signal data with columns 'Signal' and 'Time'.
+
+        Raises
+        ------
+        ValueError
+            If the DataFrame is missing required columns or is empty.
+        """
+        super().init_data(dataframe)
+
+        if self.threshold is not None:
+            self.threshold = self.threshold.to(self.data['Signal'].values.units)
+
+        self.window_size = self.window_size.to(self.data['Time'].values.units)
+
+        if self.min_peak_distance is not None:
+            self.min_peak_distance = self.min_peak_distance.to(self.data['Time'].values.units)
+
+    def _compute_algorithm_specific_features(self) -> None:
+        """
+        Compute peaks based on the moving average algorithm.
+        """
+        peak_indices = self._compute_peak_positions()
+
+        widths_samples, width_heights, left_ips, right_ips = self._compute_peak_widths(peak_indices, self.data['Difference'].values)
+
+        return peak_indices, widths_samples, width_heights, left_ips, right_ips
+
+    def _compute_peak_positions(self) -> None:
+        # Calculate moving average
+        window_size_samples = int(np.ceil(self.window_size / self.dt))
+        moving_avg = self.data['Signal'].rolling(window=window_size_samples, center=True, min_periods=1).mean()
+
+        # Reattach Pint units to the moving average
+        moving_avg = pint_pandas.PintArray(moving_avg, dtype=self.data['Signal'].values.units)
+
+        # Add the moving average to the DataFrame
+        self.data['MovingAverage'] = moving_avg
+
+        # Compute the difference signal
+        self.data['Difference'] = self.data['Signal'] - self.data['MovingAverage']
+
+        # Detect peaks
+        peak_indices, _ = find_peaks(
+            self.data['Difference'].values.quantity.magnitude,
+            height=None if self.threshold is None else self.threshold.magnitude,
+            distance=None if self.min_peak_distance is None else int(np.ceil(self.min_peak_distance / self.dt))
+        )
+
+        return peak_indices
+
+    def _add_custom_to_ax(self, time_unit: str | Quantity, signal_unit: str | Quantity, ax: plt.Axes) -> None:
+        """
+        Add algorithm-specific elements to the plot.
+
+        Parameters
+        ----------
+        time_unit : str or Quantity
+            The unit for the time axis (e.g., 'microsecond').
+        signal_unit : str or Quantity
+            The unit for the signal axis (e.g., 'volt').
+        ax : matplotlib.axes.Axes
+            The Axes object to add elements to.
+        """
+        ax.plot(
+            self.data.Time,
+            self.data.Difference,
+            linestyle='--',
+            color='C1',
+            label='MA-difference'
+        )
+
+        # Plot the signal threshold line
+        ax.axhline(y=self.threshold.to(signal_unit).magnitude, color='black', linestyle='--', label='Threshold', lw=1)
+
+
+    def format_input(function: Callable) -> Callable:
+        def wrapper(self, dataframe: pd.DataFrame, y: str, x: str = None):
+            x = dataframe[x] if x is not None else dataframe.index
+
+            new_dataframe = pd.DataFrame(
+                data=dict(
+                    x=x, y=dataframe[y]
+                )
+            )
+
+            return function(self=self, dataframe=new_dataframe)
+
+        return wrapper
+
+
+    @format_input
+    def process_data(self, dataframe: pd.DataFrame) -> Tuple[pd.DataFrame, pd.DataFrame]:
+        dt = dataframe.x[1] - dataframe.x[0]
+
+        window_size_samples = int(np.ceil(self.window_size / dt))
+
+
+        y_units = dataframe['y'].pint.units
+        x_units = dataframe['x'].pint.units
+
+        moving_avg = dataframe['y'].rolling(window=window_size_samples, center=True, min_periods=1).mean()
+
+        dataframe['MovingAverage'] = PintArray(moving_avg, y_units)
+
+        dataframe['Difference'] = dataframe['y'] - dataframe['MovingAverage']
+
+        peak_indices, meta = find_peaks(
+            x=dataframe['Difference'],
+            height=self.threshold.to(dataframe['Difference'].pint.units).magnitude,
+            distance=window_size_samples,
+            rel_height=0.1,
+            width=1
+        )
+
+        peak_dataframe = pd.DataFrame(
+            dict(
+                PeakPosition=dataframe['x'][peak_indices],
+                PeakHeight=PintArray(meta['peak_heights'], y_units),
+                PeakWidth=PintArray(meta['widths'], x_units),
+            )
+        )
+
+        return dataframe, peak_dataframe

FlowCyPy/physical_constant.py

@@ -0,0 +1,19 @@
+from FlowCyPy.units import meter, joule, second, farad, kelvin, coulomb
+import numpy as np
+
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+class PhysicalConstant:
+    h = 6.62607015e-34 * joule * second  # Planck constant
+    c = 3e8 * meter / second  # Speed of light
+    epsilon_0 = 8.8541878128e-12 * farad / meter  # Permtivitty of vacuum
+    pi = np.pi  # Pi, what else?
+    kb = 1.380649e-23 * joule / kelvin  # Botlzmann constant
+    e = 1.602176634e-19 * coulomb  # Electron charge