FlowCyPy 0.7.1__tar.gz → 0.7.3__tar.gz

{flowcypy-0.7.1 → flowcypy-0.7.3}/FlowCyPy/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.7.1'
-__version_tuple__ = version_tuple = (0, 7, 1)
+__version__ = version = '0.7.3'
+__version_tuple__ = version_tuple = (0, 7, 3)

{flowcypy-0.7.1 → flowcypy-0.7.3}/FlowCyPy/acquisition.py

@@ -1,4 +1,5 @@
 import logging
+import warnings
 from typing import Optional, Union, List
 from MPSPlots.styles import mps
 import pandas as pd
@@ -9,8 +10,9 @@ from scipy.signal import find_peaks
 import matplotlib.pyplot as plt
 import seaborn as sns
 from tabulate import tabulate
-import warnings
+
 from FlowCyPy import helper
+from FlowCyPy.classifier import BaseClassifier
 
 class DataAccessor:
     def __init__(self, outer):
@@ -94,13 +96,13 @@ class Acquisition:
         results = results.reset_index(drop=True)
 
         # Check for multiple peaks and issue a warning
-        peak_counts = results.groupby(['Detector', 'SegmentID']).size()
-        multiple_peak_segments = peak_counts[peak_counts > 1]
-        if not multiple_peak_segments.empty:
-            warnings.warn(
-                f"Multiple peaks detected in the following segments: {multiple_peak_segments.index.tolist()}",
-                UserWarning
-            )
+        # peak_counts = results.groupby(['Detector', 'SegmentID']).size()
+        # multiple_peak_segments = peak_counts[peak_counts > 1]
+        # if not multiple_peak_segments.empty:
+        #     warnings.warn(
+        #         f"Multiple peaks detected in the following segments: {multiple_peak_segments.index.tolist()}",
+        #         UserWarning
+        #     )
 
         _temp = results.reset_index()[['Detector', 'SegmentID', 'Height']].pint.dequantify().droplevel('unit', axis=1)
 
@@ -172,22 +174,47 @@ class Acquisition:
             post_buffer: int = 64,
             max_triggers: int = None) -> None:
         """
-        Executes the triggered acquisition analysis.
+        Execute triggered acquisition analysis for signal data.
+
+        This method identifies segments of signal data based on a triggering threshold
+        and specified detector. It extracts segments of interest from the signal,
+        including a pre-trigger buffer and post-trigger buffer, and stores the results
+        in `self.data.triggered`.
 
         Parameters
         ----------
         threshold : units.Quantity
-            Trigger threshold value.
-        trigger_detector_name : str, optional
-            Detector used for triggering, by default None.
-        custom_trigger : np.ndarray, optional
-            Custom trigger array, by default None.
+            The threshold value for triggering. Only signal values exceeding this threshold
+            will be considered as trigger events.
+        trigger_detector_name : str
+            The name of the detector used for triggering. This determines which detector's
+            signal is analyzed for trigger events.
         pre_buffer : int, optional
-            Points before trigger, by default 64.
+            The number of points to include before the trigger point in each segment.
+            Default is 64.
         post_buffer : int, optional
-            Points after trigger, by default 64.
+            The number of points to include after the trigger point in each segment.
+            Default is 64.
         max_triggers : int, optional
-            Maximum number of triggers to process, by default None.
+            The maximum number of triggers to process. If None, all triggers will be processed.
+            Default is None.
+
+        Raises
+        ------
+        ValueError
+            If the specified `trigger_detector_name` is not found in the dataset.
+
+        Warnings
+        --------
+        UserWarning
+            If no triggers are detected for the specified threshold, the method raises a warning
+            indicating that no signals met the criteria.
+
+        Notes
+        -----
+        - Triggered segments are stored in `self.data.triggered` as a pandas DataFrame with a hierarchical index on `['Detector', 'SegmentID']`.
+        - This method modifies `self.data.triggered` in place.
+        - The peak detection function `self.detect_peaks` is automatically called at the end of this method to analyze triggered segments.
         """
         self.threshold = threshold
         self.trigger_detector_name = trigger_detector_name
@@ -226,7 +253,28 @@ class Acquisition:
 
         self.detect_peaks()
 
-    def classify_dataset(self, classifier: object, features: List[str], detectors: list[str]) -> None:
+    def classify_dataset(self, classifier: BaseClassifier, features: List[str], detectors: list[str]) -> None:
+        """
+        Classify the dataset using the specified classifier and features.
+
+        This method applies a classification algorithm to the dataset by first unstacking
+        the "Detector" level of the DataFrame's index. It then uses the provided classifier
+        object to classify the dataset based on the specified features and detectors.
+
+        Parameters
+        ----------
+        classifier : BaseClassifier
+            An object implementing a `run` method for classification.
+        features : List[str]
+            A list of column names corresponding to the features to be used for classification (e.g., 'Height', 'Width', 'Area').
+        detectors : list[str]
+            A list of detector names to filter the data before classification. Only data from these detectors will be included in the classification process.
+
+        Returns
+        -------
+        None
+            This method updates the `self.data.peaks` attribute in place with the classified data.
+        """
         self.data.peaks = self.data.peaks.unstack('Detector')
         self.classifier = classifier
 
@@ -464,7 +512,7 @@ class Acquisition:
                     zorder=0,
                 )
 
-                ax2.set_ylim(detector._saturation_levels)
+                ax2.set_ylim(detector._saturation_levels if detector._saturation_levels[0] != detector._saturation_levels[1] else None)
 
             self._add_event_to_ax(ax=axes[-1], time_units=time_units)
 
@@ -489,7 +537,7 @@ class Acquisition:
             ax.legend()
 
         @helper.plot_sns
-        def coupling_distribution(self, x_detector: str, y_detector: str, equal_limits: bool = False) -> None:
+        def coupling_distribution(self, x_detector: str, y_detector: str, bandwidth_adjust: float = 1) -> None:
             """
             Plots the density distribution of optical coupling between two detector channels.
 
@@ -512,7 +560,7 @@ class Acquisition:
             y = df[y_detector].pint.to(y_units)
 
             with plt.style.context(mps):
-                grid = sns.jointplot(data=df, x=x, y=y, hue="Population", alpha=0.8)
+                grid = sns.jointplot(data=df, x=x, y=y, hue="Population", alpha=0.8, marginal_kws=dict(bw_adjust=bandwidth_adjust))
 
             grid.ax_joint.set_xlabel(f"Signal {x_detector} [{x_units}]")
             grid.ax_joint.set_ylabel(f"Signal {y_detector} [{y_units}]")
@@ -522,7 +570,7 @@ class Acquisition:
             return grid
 
         @helper.plot_sns
-        def scatterer(self, alpha: float = 0.8, bandwidth_adjust: float = 1, log_scale: bool = False, color_palette: Optional[Union[str, dict]] = None) -> None:
+        def scatterer(self, alpha: float = 0.8, bandwidth_adjust: float = 1, color_palette: Optional[Union[str, dict]] = None) -> None:
             """
             Visualizes the joint distribution of scatterer sizes and refractive indices using a Seaborn jointplot.
 
@@ -616,6 +664,7 @@ class Acquisition:
         def trigger(self, show: bool = True) -> None:
             """Plot detected peaks on signal segments."""
             n_plots = self.acquisition.n_detectors + 1
+
             with plt.style.context(mps):
                 _, axes = plt.subplots(
                     nrows=n_plots,
@@ -628,12 +677,12 @@ class Acquisition:
 
             time_units = self.acquisition.data.triggered['Time'].max().to_compact().units
 
-            for ax, (detector_name, group) in zip(axes, self.acquisition.data.triggered.groupby(level=['Detector'])):
+            for ax, (detector_name, group) in zip(axes, self.acquisition.data.triggered.groupby(level='Detector')):
                 detector = self.get_detector(detector_name)
 
                 ax.set_ylabel(detector_name)
 
-                for _, sub_group in group.groupby(level=['SegmentID']):
+                for _, sub_group in group.groupby(level='SegmentID'):
                     x = sub_group['Time'].pint.to(time_units)
                     digitized = sub_group['DigitizedSignal']
                     ax.step(x, digitized, where='mid', linewidth=2)
@@ -661,7 +710,7 @@ class Acquisition:
                 ax2.legend()
 
 
-            for ax, (detector_name, group) in zip(axes, self.acquisition.data.peaks.groupby(level=['Detector'], axis=0)):
+            for ax, (detector_name, group) in zip(axes, self.acquisition.data.peaks.groupby(level='Detector')):
                 x = group['Time'].pint.to(time_units)
                 y = group['Height']
                 ax.scatter(x, y, color='C1')
@@ -700,7 +749,6 @@ class Acquisition:
 
             # Set the plotting style
             with plt.style.context(mps):
-                # Generate a scatter plot using seaborn's jointplot
                 grid = sns.jointplot(
                     data=self.acquisition.data.peaks,
                     x=(feature, x_detector),

flowcypy-0.7.3/FlowCyPy/classifier.py

@@ -0,0 +1,182 @@
+from sklearn.cluster import KMeans
+from sklearn.cluster import DBSCAN
+from sklearn.mixture import GaussianMixture
+import pandas as pd
+from typing import Dict, Tuple
+
+
+class BaseClassifier:
+    def filter_dataframe(self, dataframe: pd.DataFrame, features: list, detectors: list = None) -> object:
+        """
+        Filter the DataFrame based on the selected features and detectors.
+
+        Parameters
+        ----------
+        features : list
+            List of features to use for filtering. Options include 'Heights', 'Widths', 'Areas'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+
+        Returns
+        -------
+        DataFrame
+            A filtered DataFrame containing only the selected detectors and features.
+
+        Raises
+        ------
+        ValueError
+            If no matching features are found for the given detectors and features.
+        """
+        # Determine detectors to use
+
+        if detectors is None:
+            detectors = dataframe.columns.get_level_values(1).unique().tolist()
+
+        return dataframe.loc[:, (features, detectors)]
+
+
+class KmeansClassifier(BaseClassifier):
+    def __init__(self, number_of_cluster: int) -> None:
+        """
+        Initialize the Classifier.
+
+        Parameters
+        ----------
+        dataframe : DataFrame
+            The input dataframe with multi-index columns.
+        """
+        self.number_of_cluster = number_of_cluster
+
+    def run(self, dataframe: pd.DataFrame, features: list = ['Height'], detectors: list = None, random_state: int = 42) -> pd.DataFrame:
+        """
+        Run KMeans clustering on the selected features and detectors.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            The input DataFrame with multi-index (e.g., by 'Detector').
+        features : list
+            List of features to use for clustering. Options include 'Height', 'Width', 'Area'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+        random_state : int, optional
+            Random state for KMeans, by default 42.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with clustering labels added.
+        """
+        # Filter the DataFrame
+        sub_dataframe = self.filter_dataframe(dataframe=dataframe, features=features, detectors=detectors)
+
+        # Ensure data is dequantified if it uses Pint quantities
+        if hasattr(sub_dataframe, 'pint'):
+            sub_dataframe = sub_dataframe.pint.dequantify().droplevel('unit', axis=1)
+
+        # Run KMeans
+        kmeans = KMeans(n_clusters=self.number_of_cluster, random_state=random_state)
+        labels = kmeans.fit_predict(sub_dataframe)
+
+        dataframe['Label'] = labels
+
+        return labels
+
+class GaussianMixtureClassifier(BaseClassifier):
+    def __init__(self, number_of_components: int) -> None:
+        """
+        Initialize the Gaussian Mixture Classifier.
+
+        Parameters
+        ----------
+        number_of_components : int
+            Number of Gaussian components (clusters) to use for the model.
+        """
+        self.number_of_components = number_of_components
+
+    def run(self, dataframe: pd.DataFrame, features: list = ['Height'], detectors: list = None, random_state: int = 42) -> pd.DataFrame:
+        """
+        Run Gaussian Mixture Model (GMM) clustering on the selected features and detectors.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            The input DataFrame with multi-index (e.g., by 'Detector').
+        features : list
+            List of features to use for clustering. Options include 'Height', 'Width', 'Area'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+        random_state : int, optional
+            Random state for reproducibility, by default 42.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with clustering labels added.
+        """
+        # Filter the DataFrame
+        sub_dataframe = self.filter_dataframe(dataframe=dataframe, features=features, detectors=detectors)
+
+        # Ensure data is dequantified if it uses Pint quantities
+        if hasattr(sub_dataframe, 'pint'):
+            sub_dataframe = sub_dataframe.pint.dequantify().droplevel('unit', axis=1)
+
+        # Run Gaussian Mixture Model
+        gmm = GaussianMixture(n_components=self.number_of_components, random_state=random_state)
+        labels = gmm.fit_predict(sub_dataframe)
+
+        # Add labels to the original DataFrame
+        dataframe['Label'] = labels
+
+        return labels
+
+class DBSCANClassifier(BaseClassifier):
+    def __init__(self, epsilon: float = 0.5, min_samples: int = 5) -> None:
+        """
+        Initialize the DBSCAN Classifier.
+
+        Parameters
+        ----------
+        epsilon : float, optional
+            The maximum distance between two samples for them to be considered as neighbors.
+            Default is 0.5.
+        min_samples : int, optional
+            The number of samples in a neighborhood for a point to be considered a core point.
+            Default is 5.
+        """
+        self.epsilon = epsilon
+        self.min_samples = min_samples
+
+    def run(self, dataframe: pd.DataFrame, features: list = ['Height'], detectors: list = None) -> pd.DataFrame:
+        """
+        Run DBSCAN clustering on the selected features and detectors.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            The input DataFrame with multi-index (e.g., by 'Detector').
+        features : list
+            List of features to use for clustering. Options include 'Height', 'Width', 'Area'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with clustering labels added. Noise points are labeled as -1.
+        """
+        # Filter the DataFrame
+        sub_dataframe = self.filter_dataframe(dataframe=dataframe, features=features, detectors=detectors)
+
+        # Ensure data is dequantified if it uses Pint quantities
+        if hasattr(sub_dataframe, 'pint'):
+            sub_dataframe = sub_dataframe.pint.dequantify().droplevel('unit', axis=1)
+
+        # Run DBSCAN
+        dbscan = DBSCAN(eps=self.epsilon, min_samples=self.min_samples)
+        labels = dbscan.fit_predict(sub_dataframe)
+
+        # Add labels to the original DataFrame
+        dataframe['Label'] = labels
+
+        return labels

{flowcypy-0.7.1 → flowcypy-0.7.3}/FlowCyPy/cytometer.py

@@ -4,14 +4,13 @@
 import logging
 import numpy as np
 from typing import List, Callable, Optional
-from MPSPlots.styles import mps
-from FlowCyPy.flow_cell import FlowCell
-from FlowCyPy.detector import Detector
 import pandas as pd
-import pint_pandas
+from pint_pandas import PintArray
+
 from FlowCyPy import units
 from FlowCyPy.units import Quantity, milliwatt
-from pint_pandas import PintArray
+from FlowCyPy.flow_cell import FlowCell
+from FlowCyPy.detector import Detector
 from FlowCyPy.acquisition import Acquisition
 from FlowCyPy.signal_digitizer import SignalDigitizer
 
@@ -117,33 +116,73 @@ class FlowCytometer:
                 medium_refractive_index=self.scatterer_collection.medium_refractive_index
             )
 
-            scatterer_dataframe[detector.name] = pint_pandas.PintArray(self.coupling_power, dtype=self.coupling_power.units)
+            scatterer_dataframe[detector.name] = PintArray(self.coupling_power, dtype=self.coupling_power.units)
 
     def _generate_pulse_parameters(self, scatterer_dataframe: pd.DataFrame) -> None:
-        """
+        r"""
         Generates and assigns random Gaussian pulse parameters for each particle event.
 
-        The generated parameters include:
-        - Centers: The time at which each pulse occurs.
-        - Widths: The standard deviation (spread) of each pulse in seconds.
+        The pulse shape follows the Gaussian beam’s spatial intensity profile:
 
-        Effects
-        -------
-        scatterer_collection.dataframe : pandas.DataFrame
-            Adds a 'Widths' column with computed pulse widths for each particle.
-            Uses the flow speed and beam waist to calculate pulse widths.
-        """
-        columns = pd.MultiIndex.from_product(
-            [[p.name for p in self.detectors], ['Centers', 'Heights']]
-        )
+        .. math::
+
+            I(r) = I_0 \exp\left(-\frac{2r^2}{w_0^2}\right),
+
+        where :math:`w_0` is the beam waist (the :math:`1/e^2` radius of the intensity distribution).
+        This profile can be rewritten in standard Gaussian form:
+
+        .. math::
+
+            I(r) = I_0 \exp\left(-\frac{r^2}{2\sigma_x^2}\right),
 
-        self.pulse_dataframe = pd.DataFrame(columns=columns)
+        which implies the spatial standard deviation:
 
-        self.pulse_dataframe['Centers'] = scatterer_dataframe['Time']
+        .. math::
 
-        widths = self.source.waist / self.flow_cell.flow_speed * np.ones(len(scatterer_dataframe))
+            \sigma_x = \frac{w_0}{2}.
 
-        scatterer_dataframe['Widths'] = pint_pandas.PintArray(widths, dtype=widths.units)
+        When a particle moves at a constant flow speed :math:`v`, the spatial coordinate :math:`r`
+        is related to time :math:`t` via :math:`r = v t`. Substituting this into the intensity profile
+        gives a temporal Gaussian:
+
+        .. math::
+
+            I(t) = I_0 \exp\left(-\frac{2 (v t)^2}{w_0^2}\right).
+
+        This is equivalent to a Gaussian in time:
+
+        .. math::
+
+            I(t) = I_0 \exp\left(-\frac{t^2}{2\sigma_t^2}\right),
+
+        so that the temporal standard deviation is:
+
+        .. math::
+
+            \sigma_t = \frac{\sigma_x}{v} = \frac{w_0}{2v}.
+
+        The full width at half maximum (FWHM) in time is then:
+
+        .. math::
+
+            \text{FWHM} = 2\sqrt{2 \ln2} \, \sigma_t = \frac{w_0}{v} \sqrt{2 \ln2}.
+
+        **Generated Parameters:**
+        - **Centers:** The time at which each pulse occurs (randomly determined).
+        - **Widths:** The pulse width (:math:`\sigma_t`) in seconds, computed as :math:`w_0 / (2 v)`.
+
+        **Effects**
+        -----------
+        Modifies `scatterer_dataframe` in place by adding:
+        - A `'Centers'` column with the pulse center times.
+        - A `'Widths'` column with the computed pulse widths.
+        """
+        # Calculate the pulse width (standard deviation in time, σₜ) based on the beam waist and flow speed.
+        pulse_width = self.source.waist / (2 * self.flow_cell.flow_speed)
+
+        widths = pulse_width * np.ones(len(scatterer_dataframe))
+
+        scatterer_dataframe['Widths'] = PintArray(widths, dtype=widths.units)
 
     def initialize_signal(self, run_time: Quantity) -> None:
         """
@@ -221,11 +260,11 @@ class FlowCytometer:
             time = self.dataframe.xs(detector.name)['Time'].pint.magnitude
 
             time_grid = np.expand_dims(time, axis=0) * units.second
-
             centers = np.expand_dims(_centers, axis=1) * units.second
             widths = np.expand_dims(_widths, axis=1) * units.second
 
             # Compute the Gaussian for each height, center, and width using broadcasting
+            # To be noted that widths is defined as: waist / (2 * flow_speed)
             power_gaussians = _coupling_power[:, np.newaxis] * np.exp(- (time_grid - centers) ** 2 / (2 * widths ** 2))
 
             total_power = np.sum(power_gaussians, axis=0) + self.background_power

{flowcypy-0.7.1 → flowcypy-0.7.3}/FlowCyPy/detector.py

@@ -1,21 +1,20 @@
+import logging
+from copy import copy
 import numpy as np
 import pandas as pd
 from typing import Optional, Union
 import matplotlib.pyplot as plt
-from FlowCyPy import units
-from FlowCyPy.units import AU, volt, watt, degree, ampere, coulomb, particle, meter
-from FlowCyPy.utils import PropertiesReport
 from pydantic.dataclasses import dataclass
 from pydantic import field_validator
 import pint_pandas
-from FlowCyPy.physical_constant import PhysicalConstant
+
 from PyMieSim.units import Quantity
+from FlowCyPy import units
+from FlowCyPy.units import AU, volt, watt, degree, ampere, coulomb
 from FlowCyPy.noises import NoiseSetting
-from FlowCyPy.helper import plot_helper
 from FlowCyPy.peak_locator import BasePeakLocator
-import logging
-from copy import copy
 from FlowCyPy.signal_digitizer import SignalDigitizer
+from FlowCyPy.physical_constant import PhysicalConstant
 
 config_dict = dict(
     arbitrary_types_allowed=True,
@@ -26,7 +25,7 @@ config_dict = dict(
 
 
 @dataclass(config=config_dict, unsafe_hash=True)
-class Detector(PropertiesReport):
+class Detector():
     """
     A class representing a signal detector used in flow cytometry.
 
@@ -337,62 +336,6 @@ class Detector(PropertiesReport):
 
         return digitized_signal
 
-    @plot_helper
-    def plot_raw(
-        self,
-        ax: Optional[plt.Axes] = None,
-        time_unit: Optional[Union[str, Quantity]] = None,
-        signal_unit: Optional[Union[str, Quantity]] = None,
-        add_peak_locator: bool = False
-    ) -> None:
-        """
-        Visualizes the signal and optional components (peaks, raw signal) over time.
-
-        This method generates a customizable plot of the processed signal as a function of time.
-        Additional components like raw signals and detected peaks can also be overlaid.
-
-        Parameters
-        ----------
-        ax : matplotlib.axes.Axes, optional
-            An existing Matplotlib Axes object to plot on. If None, a new Axes will be created.
-        time_unit : str or Quantity, optional
-            Desired unit for the time axis. If None, defaults to the most compact unit of the `Time` column.
-        signal_unit : str or Quantity, optional
-            Desired unit for the signal axis. If None, defaults to the most compact unit of the `Signal` column.
-        add_peak_locator : bool, optional
-            If True, adds the detected peaks (if available) to the plot. Default is False.
-
-        Returns
-        -------
-        tuple[Quantity, Quantity]
-            A tuple containing the units used for the time and signal axes, respectively.
-
-        Notes
-        -----
-        - The `Time` and `Signal` data are automatically converted to the specified units for consistency.
-        - If no `ax` is provided, a new figure and axis will be generated.
-        - Warnings are logged if peak locator data is unavailable when `add_peak_locator` is True.
-        """
-        # Set default units if not provided
-        signal_unit = signal_unit or self.dataframe['Signal'].max().to_compact().units
-        time_unit = time_unit or self.dataframe['Time'].max().to_compact().units
-
-        x = self.dataframe['Time'].pint.to(time_unit)
-
-        ax.plot(x, self.dataframe['Signal'].pint.to(signal_unit), color='C1', linestyle='--', label=f'{self.name}: Raw', linewidth=1)
-        ax.legend(loc='upper right')
-
-        # Overlay peak locator positions, if requested
-        if add_peak_locator:
-            if not hasattr(self, 'algorithm'):
-                logging.warning("The detector does not have a peak locator algorithm. Peaks cannot be plotted.")
-
-            self.algorithm._add_to_ax(ax=ax, signal_unit=signal_unit, time_unit=time_unit)
-
-        # Customize labels
-        ax.set_xlabel(f"Time [{time_unit:P}]")
-        ax.set_ylabel(f"{self.name} [{signal_unit:P}]")
-
     def set_peak_locator(self, algorithm: BasePeakLocator, compute_peak_area: bool = True) -> None:
         """
         Assigns a peak detection algorithm to the detector, analyzes the signal,