FlowCyPy 0.7.1__tar.gz → 0.7.4__tar.gz

{flowcypy-0.7.1 → flowcypy-0.7.4}/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.4'
+__version_tuple__ = version_tuple = (0, 7, 4)

{flowcypy-0.7.1 → flowcypy-0.7.4}/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
 
@@ -417,21 +465,32 @@ class Acquisition:
         def __init__(self, acquisition: object):
             self.acquisition = acquisition
 
-        def signals(self, figure_size: tuple = (10, 6), show: bool = True) -> None:
+        def signals(
+            self,
+            figure_size: tuple = (10, 6),
+            show: bool = True,
+            show_populations: str | List[str] = None,
+            save_filename: str = None
+        ) -> None:
             """
             Visualizes raw signals for all detector channels and the scatterer distribution.
 
             Parameters
             ----------
             figure_size : tuple, optional
-                Size of the plot (default: (10, 6)).
-            add_peak_locator : bool, optional
-                Adds peak location markers to the signals if True (default: False).
+                Size of the plot in inches (default: (10, 6)).
             show : bool, optional
-                Displays the plot immediately if True (default: True).
+                If True, displays the plot immediately (default: True).
+            show_populations : str or list of str, optional
+                List of population names to highlight in the event plot. If None, shows all populations.
+            save_filename : str, optional
+                If provided, saves the figure to the specified file.
             """
-            n_plots = self.acquisition.n_detectors + 1
+            # Handle `show_populations` default case
+            if show_populations is None:
+                show_populations = self.acquisition.data.scatterer.index.get_level_values('Population').unique()
 
+            n_plots = self.acquisition.n_detectors + 1  # One extra plot for events
             time_units = self.acquisition.data.continuous.Time.max().to_compact().units
 
             with plt.style.context(mps):
@@ -440,56 +499,103 @@ class Acquisition:
                     nrows=n_plots,
                     figsize=figure_size,
                     sharex=True,
-                    height_ratios=[1] * (n_plots - 1) + [0.5],
+                    height_ratios=[1] * (n_plots - 1) + [0.5]
                 )
 
+            # Plot digitized and continuous signals for each detector
             for ax, (detector_name, group) in zip(axes[:-1], self.acquisition.data.continuous.groupby("Detector")):
                 detector = self.get_detector(detector_name)
 
-                ax.step(group["Time"].pint.to(time_units), group["DigitizedSignal"], label="Digitized Signal", where='mid')
+                # Convert time and signal data to the appropriate units
+                time_data = group["Time"].pint.to(time_units)
+                digitized_signal = group["DigitizedSignal"]
+
+                # Plot digitized signal
+                ax.step(time_data, digitized_signal, label="Digitized Signal", where='mid')
                 ax.set_ylabel(detector_name)
                 ax.set_ylim([0, self.acquisition.cytometer.signal_digitizer._bit_depth])
 
+                # Twin axis for continuous signal
                 ax2 = ax.twinx()
-                ax2_x = self.acquisition.data.continuous.loc[detector_name, 'Time']
-                ax2_y = self.acquisition.data.continuous.loc[detector_name, 'Signal']
-                ax2_y_units = ax2_y.max().to_compact().units
-                ax2.plot(
-                    ax2_x.pint.to(time_units),
-                    ax2_y.pint.to(ax2_y_units),
-                    color='black',
-                    linewidth=1,
-                    linestyle='-',
-                    label='Continuous signal',
-                    zorder=0,
-                )
+                cont_time, cont_signal, cont_signal_units = self._get_continuous_signal(detector_name, time_units)
+                ax2.plot(cont_time, cont_signal, color='black', linewidth=1, linestyle='-', label='Continuous Signal', zorder=0)
 
-                ax2.set_ylim(detector._saturation_levels)
-
-            self._add_event_to_ax(ax=axes[-1], time_units=time_units)
+                # Set y-limits for the continuous signal
+                if detector._saturation_levels[0] != detector._saturation_levels[1]:
+                    ax2.set_ylim(detector._saturation_levels)
 
+            # Add event markers to the last subplot
+            self._add_event_to_ax(ax=axes[-1], time_units=time_units, show_populations=show_populations)
             axes[-1].set_xlabel(f"Time [{time_units}]")
+
+            # Save or show the figure
+            if save_filename:
+                fig.savefig(fname=save_filename)
             if show:
                 plt.show()
 
-        def _add_event_to_ax(self, ax: plt.Axes, time_units: units.Quantity, palette: str = 'tab10') -> None:
+
+        def _get_continuous_signal(self, detector_name: str, time_units: units.Quantity):
+            """
+            Retrieves and converts the continuous signal data for a given detector.
+
+            Parameters
+            ----------
+            detector_name : str
+                Name of the detector.
+            time_units : units.Quantity
+                Desired time units.
+
+            Returns
+            -------
+            tuple
+                (time array, signal array, signal units)
+            """
+            data = self.acquisition.data.continuous.loc[detector_name]
+            cont_time = data['Time'].pint.to(time_units)
+            cont_signal = data['Signal']
+            cont_signal_units = cont_signal.max().to_compact().units
+            return cont_time, cont_signal.pint.to(cont_signal_units), cont_signal_units
+
+        def _add_event_to_ax(
+            self,
+            ax: plt.Axes,
+            time_units: units.Quantity,
+            palette: str = 'tab10',
+            show_populations: str | List[str] = None
+        ) -> None:
+            """
+            Adds vertical markers for event occurrences in the scatterer data.
+
+            Parameters
+            ----------
+            ax : plt.Axes
+                The matplotlib axis to modify.
+            time_units : units.Quantity
+                Time units to use for plotting.
+            palette : str, optional
+                Color palette for different populations (default: 'tab10').
+            show_populations : str or list of str, optional
+                Populations to display. If None, all populations are shown.
+            """
+            # Get unique population names
             unique_populations = self.acquisition.data.scatterer.index.get_level_values('Population').unique()
             color_mapping = dict(zip(unique_populations, sns.color_palette(palette, len(unique_populations))))
 
             for population_name, group in self.acquisition.data.scatterer.groupby('Population'):
+                if show_populations is not None and population_name not in show_populations:
+                    continue
                 x = group.Time.pint.to(time_units)
                 color = color_mapping[population_name]
                 ax.vlines(x, ymin=0, ymax=1, transform=ax.get_xaxis_transform(), label=population_name, color=color)
 
             ax.tick_params(axis='y', left=False, labelleft=False)
-
             ax.get_yaxis().set_visible(False)
             ax.set_xlabel(f"Time [{time_units}]")
-
             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 +618,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 +628,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 +722,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 +735,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 +768,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 +807,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.4/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