FlowCyPy 0.5.0__py3-none-any.whl

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,114 @@
+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 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 = None
+    window_size: Quantity = Quantity(1, microsecond)
+    min_peak_distance: Quantity = None
+    rel_height: float = 0.8
+
+    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)

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

FlowCyPy/plottings.py

@@ -0,0 +1,270 @@
+from typing import Optional, Union, Tuple
+from MPSPlots.styles import mps
+import matplotlib.pyplot as plt
+import seaborn as sns
+import pandas as pd
+import numpy as np
+
+
+class MetricPlotter:
+    """
+    A class for creating 2D density and scatter plots of scattering intensities from two detectors.
+
+    Parameters
+    ----------
+    coincidence_dataframe : pd.DataFrame
+        The dataframe containing the coincidence data, including detector and feature columns.
+    detector_names : tuple of str
+        A tuple containing the names of the two detectors (detector 0 and detector 1).
+    """
+
+    def __init__(self, coincidence_dataframe: pd.DataFrame, detector_names: Tuple[str, str]):
+        self.coincidence_dataframe = coincidence_dataframe.reset_index()
+        self.detector_names = detector_names
+
+    def _extract_feature_data(self, feature: str):
+        """
+        Extracts and processes the feature data for the two detectors.
+
+        Parameters
+        ----------
+        feature : str
+            The feature to extract.
+
+        Returns
+        -------
+        Tuple[pd.Series, pd.Series, str, str]
+            Processed x_data, y_data, x_units, and y_units.
+        """
+        name_0, name_1 = self.detector_names
+        x_data = self.coincidence_dataframe[(name_0, feature)]
+        y_data = self.coincidence_dataframe[(name_1, feature)]
+
+        x_units = x_data.max().to_compact().units
+        y_units = y_data.max().to_compact().units
+
+        x_data = x_data.pint.to(x_units)
+        y_data = y_data.pint.to(y_units)
+
+        return x_data, y_data, x_units, y_units
+
+    def _create_density_plot(
+        self,
+        x_data: pd.Series,
+        y_data: pd.Series,
+        bandwidth_adjust: float,
+    ):
+        """
+        Creates a KDE density plot.
+
+        Parameters
+        ----------
+        x_data : pd.Series
+            The x-axis data.
+        y_data : pd.Series
+            The y-axis data.
+        bandwidth_adjust : float
+            Adjustment factor for the KDE bandwidth.
+
+        Returns
+        -------
+        sns.JointGrid
+            The seaborn JointGrid object.
+        """
+        return sns.jointplot(
+            data=self.coincidence_dataframe,
+            x=x_data,
+            y=y_data,
+            kind="kde",
+            alpha=0.8,
+            fill=True,
+            joint_kws={"alpha": 0.7, "bw_adjust": bandwidth_adjust},
+        )
+
+    def _add_scatterplot(
+        self,
+        g: sns.JointGrid,
+        x_data: pd.Series,
+        y_data: pd.Series,
+        color_palette: Optional[Union[str, dict]],
+    ):
+        """
+        Adds a scatterplot layer to the KDE density plot.
+
+        Parameters
+        ----------
+        g : sns.JointGrid
+            The seaborn JointGrid object to which the scatterplot is added.
+        x_data : pd.Series
+            The x-axis data.
+        y_data : pd.Series
+            The y-axis data.
+        color_palette : str or dict, optional
+            The color palette to use for the hue in the scatterplot.
+
+        Returns
+        -------
+        None
+        """
+        sns.scatterplot(
+            data=self.coincidence_dataframe,
+            x=x_data,
+            y=y_data,
+            hue="Label",
+            palette=color_palette,
+            ax=g.ax_joint,
+            alpha=0.6,
+            zorder=1,
+        )
+
+    def _apply_axis_labels(
+        self,
+        g: sns.JointGrid,
+        feature: str,
+        x_units: str,
+        y_units: str,
+    ):
+        """
+        Sets the x and y labels with units on the plot.
+
+        Parameters
+        ----------
+        g : sns.JointGrid
+            The seaborn JointGrid object.
+        feature : str
+            The feature being plotted.
+        x_units : str
+            Units of the x-axis data.
+        y_units : str
+            Units of the y-axis data.
+
+        Returns
+        -------
+        None
+        """
+        name_0, name_1 = self.detector_names
+        g.ax_joint.set_xlabel(f"{feature} : {name_0} [{x_units:P}]")
+        g.ax_joint.set_ylabel(f"{feature}: {name_1} [{y_units:P}]")
+
+    def _apply_axis_limits(
+        self,
+        g: sns.JointGrid,
+        x_limits: Optional[Tuple],
+        y_limits: Optional[Tuple],
+        x_units: str,
+        y_units: str):
+        """
+        Sets the axis limits if specified.
+
+        Parameters
+        ----------
+        g : sns.JointGrid
+            The seaborn JointGrid object.
+        x_limits : tuple, optional
+            The x-axis limits (min, max), by default None.
+        y_limits : tuple, optional
+            The y-axis limits (min, max), by default None.
+        x_units : str
+            Units of the x-axis data.
+        y_units : str
+            Units of the y-axis data.
+
+        Returns
+        -------
+        None
+        """
+        if x_limits:
+            x0, x1 = x_limits
+            x0 = x0.to(x_units).magnitude
+            x1 = x1.to(x_units).magnitude
+            g.ax_joint.set_xlim(x0, x1)
+
+        if y_limits:
+            y0, y1 = y_limits
+            y0 = y0.to(y_units).magnitude
+            y1 = y1.to(y_units).magnitude
+            g.ax_joint.set_ylim(y0, y1)
+
+    def plot(
+        self,
+        feature: str,
+        show: bool = True,
+        log_plot: bool = True,
+        x_limits: Optional[Tuple] = None,
+        y_limits: Optional[Tuple] = None,
+        equal_axes: bool = False,
+        bandwidth_adjust: float = 1.0,
+        color_palette: Optional[Union[str, dict]] = 'tab10') -> None:
+        """
+        Generates a 2D density plot of the scattering intensities, overlaid with individual peak heights.
+
+        Parameters
+        ----------
+        feature : str
+            The feature to plot (e.g., 'intensity').
+        show : bool, optional
+            Whether to display the plot immediately, by default True.
+        log_plot : bool, optional
+            Whether to use logarithmic scaling for the plot axes, by default True.
+        x_limits : tuple, optional
+            The x-axis limits (min, max), by default None.
+        y_limits : tuple, optional
+            The y-axis limits (min, max), by default None.
+        equal_axes : bool, optional
+            Whether to enforce the same range for the x and y axes, by default False.
+        bandwidth_adjust : float, optional
+            Bandwidth adjustment factor for the kernel density estimate of the marginal distributions. Default is 1.0.
+        color_palette : str or dict, optional
+            The color palette to use for the hue in the scatterplot.
+
+        Returns
+        -------
+        None
+        """
+        x_data, y_data, x_units, y_units = self._extract_feature_data(feature)
+
+        # Determine equal axis limits if required
+        if equal_axes:
+            min_x = x_limits[0].to(x_units).magnitude if x_limits else x_data.min()
+            max_x = x_limits[1].to(x_units).magnitude if x_limits else x_data.max()
+            min_y = y_limits[0].to(y_units).magnitude if y_limits else y_data.min()
+            max_y = y_limits[1].to(y_units).magnitude if y_limits else y_data.max()
+
+            # Set common limits
+            min_val = min(min_x, min_y)
+            max_val = max(max_x, max_y)
+            x_limits = (min_val, max_val)
+            y_limits = (min_val, max_val)
+
+        with plt.style.context(mps):
+            if not log_plot:
+                # KDE + Scatterplot for linear plots
+                g = self._create_density_plot(x_data, y_data, bandwidth_adjust)
+                self._add_scatterplot(g, x_data, y_data, color_palette)
+                self._apply_axis_labels(g, feature, x_units, y_units)
+                self._apply_axis_limits(g, x_limits, y_limits, x_units, y_units)
+            else:
+                # Scatterplot only for log-scaled plots
+                fig, ax = plt.subplots()
+                sns.scatterplot(
+                    x=x_data,
+                    y=y_data,
+                    hue=self.coincidence_dataframe["Label"],
+                    palette=color_palette,
+                    alpha=0.6,
+                    ax=ax,
+                )
+                ax.set_xscale("log")
+                ax.set_yscale("log")
+                ax.set_xlabel(f"{feature} : {self.detector_names[0]} [{x_units:P}]")
+                ax.set_ylabel(f"{feature} : {self.detector_names[1]} [{y_units:P}]")
+                if x_limits:
+                    ax.set_xlim([lim.to(x_units).magnitude for lim in x_limits])
+                if y_limits:
+                    ax.set_ylim([lim.to(y_units).magnitude for lim in y_limits])
+                ax.legend()
+
+            plt.tight_layout()
+            if show:
+                plt.show()
+