FlowCyPy 0.7.0__tar.gz → 0.7.3__tar.gz

{flowcypy-0.7.0 → 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.0'
-__version_tuple__ = version_tuple = (0, 7, 0)
+__version__ = version = '0.7.3'
+__version_tuple__ = version_tuple = (0, 7, 3)

{flowcypy-0.7.0 → 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,7 +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):
@@ -93,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)
 
@@ -110,13 +113,36 @@ class Acquisition:
         )
 
     def _get_trigger_indices(
-            self,
-            threshold: units.Quantity,
-            trigger_detector_name: str = None,
-            pre_buffer: int = 64,
-            post_buffer: int = 64) -> tuple[np.ndarray, np.ndarray]:
+        self,
+        threshold: units.Quantity,
+        trigger_detector_name: str = None,
+        pre_buffer: int = 64,
+        post_buffer: int = 64
+    ) -> tuple[np.ndarray, np.ndarray]:
         """
-        Calculate start and end indices for triggered segments.
+        Calculate start and end indices for triggered segments, ensuring no retriggering
+        occurs during an active buffer period.
+
+        Parameters
+        ----------
+        threshold : units.Quantity
+            The threshold value for triggering.
+        trigger_detector_name : str, optional
+            The name of the detector to use for the triggering signal.
+        pre_buffer : int, optional
+            Number of samples to include before the trigger point.
+        post_buffer : int, optional
+            Number of samples to include after the trigger point.
+
+        Returns
+        -------
+        tuple[np.ndarray, np.ndarray]
+            The start and end indices of non-overlapping triggered segments.
+
+        Raises
+        ------
+        ValueError
+            If the specified detector is not found in the data.
         """
         if trigger_detector_name not in self.data.continuous.index.get_level_values('Detector').unique():
             raise ValueError(f"Detector '{trigger_detector_name}' not found.")
@@ -128,7 +154,18 @@ class Acquisition:
         start_indices = np.clip(crossings - pre_buffer, 0, len(trigger_signal) - 1)
         end_indices = np.clip(crossings + post_buffer, 0, len(trigger_signal) - 1)
 
-        return start_indices, end_indices
+        # Suppress retriggering within an active buffer period
+        suppressed_start_indices = []
+        suppressed_end_indices = []
+
+        last_end = -1
+        for start, end in zip(start_indices, end_indices):
+            if start > last_end:  # Ensure no overlap with the last active buffer
+                suppressed_start_indices.append(start)
+                suppressed_end_indices.append(end)
+                last_end = end  # Update the end of the current active buffer
+
+        return np.array(suppressed_start_indices), np.array(suppressed_end_indices)
 
     def run_triggering(self,
             threshold: units.Quantity,
@@ -137,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
@@ -191,6 +253,37 @@ class Acquisition:
 
         self.detect_peaks()
 
+    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
+
+        self.classifier.run(
+            dataframe=self.data.peaks,
+            features=features,
+            detectors=detectors
+        )
+
     class LoggerInterface:
         """
         A nested class for logging statistical information about the experiment.
@@ -419,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)
 
@@ -443,7 +536,8 @@ class Acquisition:
 
             ax.legend()
 
-        def coupling_distribution(self, x_detector: str, y_detector: str, log_scale: bool = False, show: bool = True, equal_limits: bool = False, save_path: str = None) -> None:
+        @helper.plot_sns
+        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.
 
@@ -466,31 +560,17 @@ class Acquisition:
             y = df[y_detector].pint.to(y_units)
 
             with plt.style.context(mps):
-                joint_plot = sns.jointplot(data=df, x=x, y=y, hue="Population", alpha=0.8)
-
-            if log_scale:
-                joint_plot.ax_joint.set_xscale("log")
-                joint_plot.ax_joint.set_yscale("log")
-
-            if equal_limits:
-                min_limit = min(x.min(), y.min())
-                max_limit = max(x.max(), y.max())
-                joint_plot.ax_joint.set_xlim(min_limit, max_limit)
-                joint_plot.ax_joint.set_ylim(min_limit, max_limit)
+                grid = sns.jointplot(data=df, x=x, y=y, hue="Population", alpha=0.8, marginal_kws=dict(bw_adjust=bandwidth_adjust))
 
-            joint_plot.ax_joint.set_xlabel(f"Signal {x_detector} [{x_units}]")
-            joint_plot.ax_joint.set_ylabel(f"Signal {y_detector} [{y_units}]")
+            grid.ax_joint.set_xlabel(f"Signal {x_detector} [{x_units}]")
+            grid.ax_joint.set_ylabel(f"Signal {y_detector} [{y_units}]")
 
-            plt.tight_layout()
+            grid.figure.suptitle("Theoretical coupling distribution")
 
-            if save_path:
-                joint_plot.figure.savefig(save_path, dpi=300, bbox_inches="tight")
-                logging.info(f"Plot saved to {save_path}")
+            return grid
 
-            if show:
-                plt.show()
-
-        def scatterer(self, show: bool = True, alpha: float = 0.8, bandwidth_adjust: float = 1, log_scale: bool = False, color_palette: Optional[Union[str, dict]] = None) -> None:
+        @helper.plot_sns
+        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.
 
@@ -504,8 +584,6 @@ class Acquisition:
                 Transparency level for the scatter plot points, ranging from 0 (fully transparent) to 1 (fully opaque). Default is 0.8.
             bandwidth_adjust : float, optional
                 Bandwidth adjustment factor for the kernel density estimate of the marginal distributions. Higher values produce smoother density estimates. Default is 1.
-            log_scale : bool, optional
-                If `True`, applies a logarithmic scale to both axes of the joint plot and their marginal distributions. Default is `False`.
             color_palette : str or dict, optional
                 The color palette to use for the hue in the scatterplot. Can be a seaborn palette name
                 (e.g., 'viridis', 'coolwarm') or a dictionary mapping hue levels to specific colors. Default is None.
@@ -540,19 +618,13 @@ class Acquisition:
                     marginal_kws=dict(bw_adjust=bandwidth_adjust)
                 )
 
-            grid.ax_joint.set_xlabel(f"Size [{x_unit}]")
-
-            if log_scale:
-                grid.ax_joint.set_xscale('log')
-                grid.ax_joint.set_yscale('log')
-                grid.ax_marg_x.set_xscale('log')
-                grid.ax_marg_y.set_yscale('log')
+            grid.figure.suptitle("Scatterer sampling distribution")
 
-            plt.tight_layout()
+            grid.ax_joint.set_xlabel(f"Size [{x_unit}]")
 
-            if show:
-                plt.show()
+            return grid
 
+        @helper.plot_sns
         def peaks(self, x_detector: str, y_detector: str, signal: str = 'Height', bandwidth_adjust: float = 0.8) -> None:
             """
             Plot the joint KDE distribution of the specified signal between two detectors using seaborn,
@@ -582,15 +654,17 @@ class Acquisition:
                     joint_kws={'bw_adjust': bandwidth_adjust, 'alpha': 0.7}
                 )
 
+            grid.figure.suptitle("Peaks properties")
             grid.ax_joint.scatter(x_data, y_data, color='C1', alpha=0.6)
 
             grid.set_axis_labels(f"{signal} ({x_detector}) [{x_units}]", f"{signal} ({y_detector}) [{y_units}]", fontsize=12)
-            plt.tight_layout()
-            plt.show()
+
+            return grid
 
         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,
@@ -603,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)
@@ -636,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')
@@ -646,6 +720,46 @@ class Acquisition:
             if show:
                 plt.show()
 
+        @helper.plot_sns
+        def classifier(self, feature: str, x_detector: str, y_detector: str) -> None:
+            """
+            Visualize the classification of peaks using a scatter plot.
+
+            Parameters
+            ----------
+            feature : str
+                The feature to classify (e.g., 'Height', 'Width', 'Area').
+            x_detector : str
+                The detector to use for the x-axis.
+            y_detector : str
+                The detector to use for the y-axis.
+
+            Raises
+            ------
+            ValueError
+                If the 'Label' column is missing in the data, suggesting that
+                the `classify_dataset` method must be called first.
+            """
+            # Check if 'Label' exists in the dataset
+            if 'Label' not in self.acquisition.data.peaks.columns:
+                raise ValueError(
+                    "The 'Label' column is missing. Ensure the dataset has been classified "
+                    "by calling the `classify_dataset` method before using `classifier`."
+                )
+
+            # Set the plotting style
+            with plt.style.context(mps):
+                grid = sns.jointplot(
+                    data=self.acquisition.data.peaks,
+                    x=(feature, x_detector),
+                    y=(feature, y_detector),
+                    hue='Label',
+                )
+
+            grid.figure.suptitle('Event classification')
+
+            return grid
+
         def get_detector(self, name: str):
             for detector in self.acquisition.cytometer.detectors:
                 if detector.name == name:

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