FlowCyPy 0.5.0__py3-none-any.whl

FlowCyPy/event_correlator.py

@@ -0,0 +1,244 @@
+from typing import Optional, Union
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import seaborn as sns
+from MPSPlots.styles import mps
+from FlowCyPy.units import second
+import warnings
+from FlowCyPy.cytometer import FlowCytometer
+from FlowCyPy.logger import EventCorrelatorLogger
+from FlowCyPy.report import Report
+
+
+class EventCorrelator:
+    """
+    A class for analyzing pulse signals generated by a flow cytometer. It processes signals
+    from multiple detectors to extract key features such as peak height, width, area,
+    and time of occurrence, while providing tools to detect coincident events between detectors.
+
+    Parameters
+    ----------
+    cytometer : FlowCytometer
+        An instance of FlowCytometer that contains detectors and their associated signals.
+
+    Methods
+    -------
+    run_analysis(compute_peak_area=False):
+        Performs peak analysis on all detectors, extracting features such as height, width,
+        and area, and stores the results in a DataFrame.
+    get_coincidence(margin):
+        Identifies and returns events where peak times from different detectors coincide
+        within a given time margin.
+    display_features():
+        Displays the extracted features from the analysis in a tabular format.
+    plot_peak(show=True, figure_size=(7, 6)):
+        Plots the signals and highlights the detected peaks and their properties (e.g., width).
+    plot(show=True, log_plot=True):
+        Generates a 2D density plot of the scattering intensities from the detectors.
+    generate_report(filename):
+        Generates a report summarizing the results of the analysis.
+    """
+
+    def __init__(self, cytometer: FlowCytometer) -> None:
+        """
+        Initializes the Analyzer class with the cytometer object.
+
+        Parameters
+        ----------
+        cytometer : FlowCytometer
+            An instance of FlowCytometer that contains detectors and their signals.
+        """
+        self.cytometer = cytometer
+        self.datasets = []
+
+    def run_analysis(self, compute_peak_area: bool = False) -> None:
+        """
+        Runs the peak detection analysis on all detectors within the flow cytometer.
+        Extracts key features such as peak height, width, area, and stores the results
+        in a pandas DataFrame for further analysis.
+
+        Parameters
+        ----------
+        compute_peak_area : bool, optional
+            Whether to compute the area under the peaks, by default False.
+
+        Returns
+        -------
+        pd.DataFrame
+            A DataFrame with the detected peak properties, organized by detector.
+        """
+        # Run peak detection on each detector
+        self.dataframe = pd.concat(
+            [d.algorithm.peak_properties for d in self.cytometer.detectors],
+            keys=[f'{d.name}' for d in self.cytometer.detectors]
+        )
+
+        self.dataframe.index.names = ['Detector', 'Event']
+
+        self._log_statistics()
+
+    def _log_statistics(self) -> EventCorrelatorLogger:
+        """
+        Logs statistical information about the detected peaks for each detector,
+        including the number of events, the first and last peak times, the average
+        time between peaks, and the minimum time between peaks.
+
+        The results are displayed in a formatted table using `tabulate` for clarity.
+        """
+        logger = EventCorrelatorLogger(self)
+
+        logger.log_statistics(table_format="fancy_grid")
+
+        return logger
+
+    def get_coincidence(self, margin: second.dimensionality) -> pd.DataFrame:
+        """
+        Identifies coincident events between two detectors within a specified time margin.
+
+        Parameters
+        ----------
+        margin : pint.Quantity
+            The time margin within which peaks are considered coincident, in compatible time units.
+        """
+        # Ensure margin has correct dimensionality (time)
+        assert margin.dimensionality == second.dimensionality, "Margin must have time dimensionality."
+
+        self.dataframe['PeakTimes'] = self.dataframe['PeakTimes'].pint.to(margin.units)
+
+        # Split the data for Detector_1 and Detector_2
+        d0 = self.dataframe.xs(self.cytometer.detectors[0].name, level='Detector')
+        d1 = self.dataframe.xs(self.cytometer.detectors[1].name, level='Detector')
+
+        # Repeat and tile PeakTimes for comparison (keeping your protocol)
+        d0_repeated = np.repeat(d0['PeakTimes'].values.numpy_data, len(d1)) * margin.units
+        d1_tiled = np.tile(d1['PeakTimes'].values.numpy_data, len(d0)) * margin.units
+
+        # Compute time differences and reshape the mask
+        time_diffs = np.abs(d0_repeated - d1_tiled)
+        mask = time_diffs <= margin
+        mask = mask.reshape(len(d0), len(d1))
+
+        # Find indices where coincidences occur
+        indices = np.where(mask)
+
+        # Count coincidences per column (for each event in Detector_1)
+        true_count_per_column = np.sum(mask.astype(int), axis=0)
+
+        # Warnings and assertions
+        if np.all(true_count_per_column == 0):
+            warnings.warn("No coincidence events found, the margin might be too low.")
+
+        assert np.all(true_count_per_column <= 1), \
+            "Coincidence events are ambiguously defined, the margin might be too high."
+
+        # Extract coincident events from both detectors
+        coincident_detector_0 = d0.iloc[indices[0]].reset_index(drop=True)
+        coincident_detector_1 = d1.iloc[indices[1]].reset_index(drop=True)
+
+        # Combine the coincident events into a single DataFrame
+        combined_coincidences = pd.concat([coincident_detector_0, coincident_detector_1], axis=1)
+
+        # Assign proper MultiIndex column names
+        combined_coincidences.columns = pd.MultiIndex.from_product([[d.name for d in self.cytometer.detectors], d0.columns])
+
+        self.coincidence = combined_coincidences
+
+        self.coincidence['Label'] = 0
+
+        return self.coincidence
+
+    def display_features(self) -> None:
+        """
+        Displays extracted peak features for all datasets in a tabular format.
+        """
+        for i, dataset in enumerate(self.datasets):
+            print(f"\nFeatures for Dataset {i + 1}:")
+            dataset.print_properties()  # Reuse the print_properties method from DataSet
+
+    def plot(self, show: bool = True, log_plot: bool = True, x_limits: tuple = None, y_limits: tuple = None, bandwidth_adjust: float = 1, color_palette: Optional[Union[str, dict]] = None) -> None:
+        """
+        Plots a 2D density plot of the scattering intensities from the two detectors,
+        along with individual peak heights.
+
+        Parameters
+        ----------
+        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.
+        bandwidth_adjust : float, optional
+            Bandwidth adjustment factor for the kernel density estimate of the marginal distributions. Default is 1.
+        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.
+        """
+        # Reset the index if necessary (to handle MultiIndex)
+        df_reset = self.coincidence.reset_index()
+
+        x_data = df_reset[(self.cytometer.detectors[0].name, 'Heights')]
+        y_data = df_reset[(self.cytometer.detectors[1].name, 'Heights')]
+
+        # Extract the units from the pint-pandas columns
+        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)
+
+        with plt.style.context(mps):
+
+            g = sns.jointplot(data=df_reset, x=x_data, y=y_data,
+                kind='kde', alpha=0.8, fill=True,
+                joint_kws={'alpha': 0.7, 'bw_adjust': bandwidth_adjust}
+            )
+            sns.scatterplot(data=df_reset, x=x_data, y=y_data,
+                hue='Label', palette=color_palette, ax=g.ax_joint, alpha=0.6, zorder=1
+            )
+
+            # Set the x and y labels with units
+            g.ax_joint.set_xlabel(f"Heights : {self.cytometer.detectors[0].name} [{x_units:P}]")
+            g.ax_joint.set_ylabel(f"Heights: {self.cytometer.detectors[1].name} [{y_units:P}]")
+
+            if log_plot:
+                g.ax_marg_x.set_xscale('log')
+                g.ax_marg_y.set_yscale('log')
+
+            if x_limits is not None:
+                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 is not None:
+                y0, y1 = y_limits
+                y0 = y0.to(y_units).magnitude
+                y1 = y1.to(y_units).magnitude
+                g.ax_joint.set_ylim(y0, y1)
+
+            plt.tight_layout()
+
+            if show:
+                plt.show()
+
+    def generate_report(self, filename: str) -> None:
+        """
+        Generates a detailed report summarizing the analysis, including peak features
+        and detected events.
+
+        Parameters
+        ----------
+        filename : str
+            The filename where the report will be saved.
+        """
+        report = Report(
+            flow_cell=self.cytometer.scatterer.flow_cell,
+            scatterer=self.cytometer.scatterer,
+            analyzer=self
+        )
+
+        report.generate_report()

FlowCyPy/flow_cell.py

@@ -0,0 +1,122 @@
+from typing import List
+from FlowCyPy.units import meter, second
+from PyMieSim.units import Quantity
+from tabulate import tabulate
+from pydantic.dataclasses import dataclass
+from pydantic import field_validator
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class FlowCell(object):
+    """
+    Models the flow parameters in a flow cytometer, including flow speed, flow area,
+    and particle interactions. This class interacts with ScattererDistribution to simulate
+    the flow of particles through the cytometer.
+
+    Parameters
+    ----------
+    flow_speed : Quantity
+        The speed of the flow in meters per second (m/s).
+    flow_area : Quantity
+        The cross-sectional area of the flow tube in square meters (m²).
+    run_time : Quantity
+        The total duration of the flow simulation in seconds.
+    """
+    flow_speed: Quantity
+    flow_area: Quantity
+    run_time: Quantity
+
+    @field_validator('flow_speed')
+    def _validate_flow_speed(cls, value):
+        """
+        Validates that the flow speed is provided in meter per second.
+
+        Parameters
+        ----------
+        value : Quantity
+            The flow speed to validate.
+
+        Returns
+        -------
+        Quantity
+            The flow speed frequency.
+
+        Raises:
+            ValueError: If the flow speed is not in meter per second.
+        """
+        if not value.check(meter / second):
+            raise ValueError(f"flow_speed must be in meter per second, but got {value.units}")
+        return value
+
+    @field_validator('flow_area')
+    def _validate_flow_area(cls, value):
+        """
+        Validates that the flow area is provided in hertz.
+
+        Parameters
+        ----------
+        value : Quantity
+            The flow area to validate.
+
+        Returns
+        -------
+        Quantity
+            The validated flow area.
+
+        Raises:
+            ValueError: If the flow area is not in hertz.
+        """
+        if not value.check(meter ** 2):
+            raise ValueError(f"flow_area must be in meter ** 2, but got {value.units}")
+        return value
+
+    @field_validator('run_time')
+    def _validate_run_time(cls, value):
+        """
+        Validates that the total time is provided in second.
+
+        Parameters
+        ----------
+        value : Quantity
+            The total time to validate.
+
+        Returns
+        -------
+        Quantity
+            The validated total time.
+
+        Raises:
+            ValueError: If the total time is not in second.
+        """
+        if not value.check(second):
+            raise ValueError(f"run_time must be in second, but got {value.units}")
+        return value
+
+    def __post_init__(self):
+        """Initialize units for flow parameters."""
+        self.flow_speed = Quantity(self.flow_speed, meter / second)
+        self.flow_area = Quantity(self.flow_area, meter ** 2)
+        self.run_time = Quantity(self.run_time, second)
+
+        self.volume = self.flow_area * self.flow_speed * self.run_time
+
+    def print_properties(self) -> None:
+        """
+        Print the core properties of the flow and particle interactions in the flow cytometer.
+        """
+        print("\nFlow Properties")
+        print(tabulate(self.get_properties(), headers=["Property", "Value"], tablefmt="grid"))
+
+    def get_properties(self) -> List[List[str]]:
+        return [
+            ['Flow Speed', f"{self.flow_speed:.2f~#P}"],
+            ['Flow Area', f"{self.flow_area:.2f~#P}"],
+            ['Total Time', f"{self.run_time:.2f~#P}"]
+        ]

FlowCyPy/helper.py

@@ -0,0 +1,85 @@
+from typing import Callable
+import matplotlib.pyplot as plt
+from MPSPlots.styles import mps
+
+
+def plot_helper(function: Callable) -> Callable:
+    """
+    A decorator that helps in plotting by wrapping a plotting function with additional functionality
+    such as handling axes creation, setting the figure style, managing legends, and saving figures.
+
+    Parameters
+    ----------
+    function : Callable
+        The plotting function that is decorated. It should accept `self`, `ax`, and `mode_of_interest`
+        as parameters.
+
+    Returns
+    -------
+    Callable
+        A wrapper function that adds the specified plotting functionalities.
+
+    Notes
+    -----
+    This decorator expects the decorated function to have the following signature:
+    `function(self, ax=None, mode_of_interest='all', **kwargs)`.
+    """
+    def wrapper(self, ax: plt.Axes = None, show: bool = True, save_filename: str = None, figure_size: tuple = None, **kwargs) -> plt.Figure:
+        """
+        A wrapped version of the plotting function that provides additional functionality for creating
+        and managing plots.
+
+        Parameters
+        ----------
+        self : object
+            The instance of the class calling this method.
+        ax : plt.Axes, optional
+            A matplotlib Axes object to draw the plot on. If None, a new figure and axes are created.
+            Default is None.
+        show : bool, optional
+            Whether to display the plot. If False, the plot will not be shown but can still be saved
+            or returned. Default is True.
+        mode_of_interest : str, optional
+            Specifies the mode of interest for the plot. If 'all', all available modes will be plotted.
+            This parameter is interpreted using the `interpret_mode_of_interest` function. Default is 'all'.
+        save_filename : str, optional
+            A file path to save the figure. If None, the figure will not be saved. Default is None.
+        **kwargs : dict
+            Additional keyword arguments passed to the decorated function.
+
+        Returns
+        -------
+        plt.Figure
+            The matplotlib Figure object created or used for the plot.
+
+        Notes
+        -----
+        - If no `ax` is provided, a new figure and axes are created using the style context `mps`.
+        - The legend is only added if there are labels to display.
+        - If `save_filename` is specified, the figure is saved to the given path.
+        - The plot is shown if `show` is set to True.
+        """
+        if ax is None:
+            with plt.style.context(mps):
+                figure, ax = plt.subplots(1, 1, figsize=figure_size)
+
+        else:
+            figure = ax.get_figure()
+
+        output = function(self, ax=ax, **kwargs)
+
+        _, labels = ax.get_legend_handles_labels()
+
+        # Only add a legend if there are labels
+        if labels:
+            ax.legend()
+
+        if save_filename:
+            figure.savefig(save_filename)
+
+        if show:
+            plt.show()
+
+        return output
+
+    return wrapper