FlowCyPy 0.7.0__py3-none-any.whl

FlowCyPy/flow_cell.py

@@ -0,0 +1,198 @@
+from typing import List
+from FlowCyPy.units import meter, second, particle
+
+from PyMieSim.units import Quantity
+import pandas as pd
+from tabulate import tabulate
+from pydantic.dataclasses import dataclass
+from pydantic import field_validator
+from pint_pandas import PintType, PintArray
+from FlowCyPy.source import BaseBeam
+from FlowCyPy.population import Population
+from FlowCyPy.scatterer_collection import ScattererCollection
+import pandas
+import numpy
+import warnings
+
+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²).
+    """
+    flow_speed: Quantity
+    flow_area: Quantity
+    scheme: str = 'poisson'
+
+    source: BaseBeam = None
+
+    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)
+
+    def get_volume(self, run_time: Quantity) -> Quantity:
+        return self.flow_area * self.flow_speed * run_time
+
+    @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
+
+    def get_population_sampling(self, run_time: Quantity, scatterer_collection: ScattererCollection) -> list[Quantity]:
+        population_sampling = [
+            p.particle_count.calculate_number_of_events(
+                flow_area=self.flow_area,
+                flow_speed=self.flow_speed,
+                run_time=run_time
+            ) for p in scatterer_collection.populations
+        ]
+
+        return population_sampling
+
+    def generate_event_dataframe(self, populations: List[Population], run_time: Quantity) -> pd.DataFrame:
+        """
+        Generates a DataFrame of event times for each population based on the specified scheme.
+
+        Parameters
+        ----------
+        populations : List[Population]
+            A list of populations for which to generate event times.
+        run_time : Quantity
+            The total duration of the experiment.
+
+        Returns
+        -------
+        pd.DataFrame
+            A MultiIndex DataFrame with event times for each population.
+        """
+        # Generate individual DataFrames for each population
+        population_event_frames = [
+            self._generate_poisson_events(population=population, run_time=run_time)
+            for population in populations
+        ]
+
+        # Combine the DataFrames with population names as keys
+        event_dataframe = pd.concat(population_event_frames, keys=[pop.name for pop in populations])
+        event_dataframe.index.names = ["Population", "Index"]
+
+        # Handle the scheme for event timing
+        if self.scheme.lower() in ['uniform-random', 'uniform-sequential']:
+            total_events = len(event_dataframe)
+            start_time = 0 * run_time.units
+            end_time = run_time
+            time_interval = (end_time - start_time) / total_events
+            evenly_spaced_times = numpy.arange(0, total_events) * time_interval
+
+            if self.scheme.lower() == 'uniform-random':
+                numpy.random.shuffle(evenly_spaced_times.magnitude)  # Shuffle times for random spacing
+
+            # Assign the computed times to the DataFrame
+            event_dataframe['Time'] = PintArray(evenly_spaced_times.to('second'))
+
+        return event_dataframe
+
+    def _generate_poisson_events(self, run_time: Quantity, population: Population) -> pd.DataFrame:
+        r"""
+        Generate particle arrival times over the entire experiment duration based on a Poisson process.
+
+        In flow cytometry, the particle arrival times can be modeled as a Poisson process, where the time
+        intervals between successive particle arrivals follow an exponential distribution. The average rate
+        of particle arrivals (the particle flux) is given by:
+
+        .. math::
+            \text{Particle Flux} = \rho \cdot v \cdot A
+
+        where:
+        - :math:`\rho` is the scatterer density (particles per cubic meter),
+        - :math:`v` is the flow speed (meters per second),
+        - :math:`A` is the cross-sectional area of the flow tube (square meters).
+
+        The number of particles arriving in a given time interval follows a Poisson distribution, and the
+        time between successive arrivals follows an exponential distribution. The mean inter-arrival time
+        is the inverse of the particle flux:
+
+        .. math::
+            \Delta t \sim \text{Exponential}(1/\lambda)
+
+        where:
+            - :math:`\Delta t` is the time between successive particle arrivals,
+            - :math:`\lambda` is the particle flux (particles per second).
+
+        Steps:
+            1. Compute the particle flux, which is the average number of particles passing through the detection
+            region per second.
+            2. Calculate the expected number of particles over the entire experiment duration.
+            3. Generate random inter-arrival times using the exponential distribution.
+            4. Compute the cumulative arrival times by summing the inter-arrival times.
+            5. Ensure that all arrival times fall within the total experiment duration.
+
+        Returns
+        -------
+        np.ndarray
+            An array of particle arrival times (in seconds) for the entire experiment duration, based on the Poisson process.
+        """
+        # Step 1: Compute the average particle flux (particles per second)
+        particle_flux = population.particle_count.compute_particle_flux(
+            flow_speed=self.flow_speed,
+            flow_area=self.flow_area,
+            run_time=run_time
+        )
+
+        # Step 2: Calculate the expected number of particles over the entire experiment
+        expected_particles = particle_flux * run_time
+        # expected_particles = population.n_events
+
+        # Step 3: Generate inter-arrival times (exponentially distributed)
+        inter_arrival_times = numpy.random.exponential(
+            scale=1 / particle_flux.magnitude,
+            size=int(expected_particles.magnitude)
+        ) / (particle_flux.units / particle)
+
+        # Step 4: Compute cumulative arrival times
+        arrival_times = numpy.cumsum(inter_arrival_times)
+
+        # Step 5: Limit the arrival times to the total experiment duration
+        arrival_times = arrival_times[arrival_times <= run_time]
+
+        dataframe = pd.DataFrame()
+
+        dataframe['Time'] = PintArray(arrival_times, dtype=arrival_times.units)
+
+        if len(dataframe) == 0:
+            warnings.warn("Population has been initialized with 0 events.")
+
+        return dataframe

FlowCyPy/helper.py

@@ -0,0 +1,81 @@
+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()
+
+        if save_filename:
+            figure.savefig(save_filename)
+
+        if show:
+            plt.show()
+
+        return output
+
+    return wrapper

FlowCyPy/logger.py

@@ -0,0 +1,136 @@
+import logging
+from tabulate import tabulate
+import pandas as pd
+from typing import List, Union, Optional
+from FlowCyPy import units
+
+
+class EventCorrelatorLogger:
+    """
+    Logs key statistics and properties for the EventCorrelator class, including peak detection statistics
+    for each detector and coincident event information.
+
+    Parameters
+    ----------
+    correlator : EventCorrelator
+        An instance of the EventCorrelator class to log statistics for.
+    """
+
+    def __init__(self, correlator: object):
+        """
+        Initializes the EventCorrelatorLogger with the correlator instance.
+
+        Parameters
+        ----------
+        correlator : EventCorrelator
+            An instance of EventCorrelator to log properties and statistics for.
+        """
+        # self.run_time = run_time
+        self.correlator = correlator
+        self.detectors = correlator.cytometer.detectors
+        self.coincidence = getattr(correlator, "coincidence", None)
+
+    def log_statistics(self, table_format: str = "grid") -> None:
+        """
+        Logs statistics for each detector, including number of peaks, time between peaks, and peak times.
+
+        Parameters
+        ----------
+        table_format : str, optional
+            The format for the table display (default is 'grid').
+        """
+        logging.info("\n=== Detector Statistics ===")
+
+        table_data = [self._get_detector_stats(detector) for detector in self.detectors]
+        headers = [
+            "Detector",
+            "Number of Peaks",
+            "First Peak Time",
+            "Last Peak Time",
+            "Avg Time Between Peaks",
+            "Min Time Between Peaks",
+            'Measured Concentration'
+        ]
+
+        formatted_table = tabulate(table_data, headers=headers, tablefmt=table_format, floatfmt=".4f")
+        logging.info("\n" + formatted_table)
+
+    def _get_detector_stats(self, detector) -> List[Union[str, int, str]]:
+        """
+        Computes statistics for a single detector.
+
+        Parameters
+        ----------
+        detector : object
+            A detector object with peak detection data.
+
+        Returns
+        -------
+        list
+            List of statistics: [detector name, number of peaks, first peak time, last peak time,
+            average time between peaks, minimum time between peaks].
+        """
+        group = self.correlator.dataframe.xs(detector.name, level="Detector")
+        num_events = len(group)
+
+        if num_events > 1:
+            times = group['PeakTimes'].sort_values()
+            time_diffs = times.diff().dropna()
+            avg_time_between_peaks = f"{time_diffs.mean().to_compact():.4~P}"
+            min_time_between_peaks = f"{time_diffs.min().to_compact():.4~P}"
+            # volume = self.correlator.cytometer.flow_cell.get_volume(self.run_time)
+            # measured_concentration = num_events * units.particle / volume.to(units.milliliter)
+        else:
+            avg_time_between_peaks = "N/A"
+            min_time_between_peaks = "N/A"
+            measured_concentration = "N/A"
+
+        first_peak_time = f"{group['PeakTimes'].min().to_compact():.4~P}" if num_events > 0 else "N/A"
+        last_peak_time = f"{group['PeakTimes'].max().to_compact():.4~P}" if num_events > 0 else "N/A"
+
+        return [detector.name, num_events, first_peak_time, last_peak_time, avg_time_between_peaks, min_time_between_peaks]  #, measured_concentration]
+
+    def log_coincidence_statistics(self, table_format: str = "grid") -> None:
+        """
+        Logs statistics about coincident events detected between detectors.
+
+        Parameters
+        ----------
+        table_format : str, optional
+            The format for the table display (default is 'grid').
+        """
+        if self.coincidence is None or self.coincidence.empty:
+            logging.warning("No coincidence events to log.")
+            return
+
+        logging.info("\n=== Coincidence Event Statistics ===")
+
+        table_data = self._get_coincidence_stats()
+        headers = ["Detector 1 Event", "Detector 2 Event", "Time Difference"]
+
+        formatted_table = tabulate(table_data, headers=headers, tablefmt=table_format, floatfmt=".4f")
+        logging.info("\n" + formatted_table)
+
+    def _get_coincidence_stats(self) -> List[List[Union[str, float]]]:
+        """
+        Extracts statistics about coincident events.
+
+        Returns
+        -------
+        list
+            List of coincident event statistics: [detector 1 event, detector 2 event, time difference].
+        """
+        coinc_df = self.coincidence.reset_index()
+        time_diffs = (
+            coinc_df[self.detectors[0].name, 'PeakTimes'] -
+            coinc_df[self.detectors[1].name, 'PeakTimes']
+        ).abs()
+
+        return [
+            [
+                row[self.detectors[0].name, 'PeakTimes'],
+                row[self.detectors[1].name, 'PeakTimes'],
+                time_diff.to_compact()
+            ]
+            for row, time_diff in zip(coinc_df.itertuples(), time_diffs)
+        ]

FlowCyPy/noises.py

@@ -0,0 +1,34 @@
+class RestrictiveMeta(type):
+    def __setattr__(cls, name, value):
+        if not hasattr(cls, name):
+            raise AttributeError(f"Cannot set unknown class-level attribute '{name}' in {cls.__name__}.")
+        super().__setattr__(name, value)
+
+
+class NoiseSetting(metaclass=RestrictiveMeta):
+    _instance = None
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    _include_noises = True
+    include_shot_noise = True
+    include_dark_current_noise = True
+    include_thermal_noise = True
+    include_RIN_noise = True
+
+    @property
+    def include_noises(self):
+        return self._include_noises
+
+    @include_noises.setter
+    def include_noises(self, value):
+        self._include_noises = value
+        # Dynamically update other noise components
+        if not value:
+            self.include_shot_noise = False
+            self.include_dark_current_noise = False
+            self.include_thermal_noise = False
+            self.include_RIN_noise = False

FlowCyPy/particle_count.py

@@ -0,0 +1,127 @@
+from FlowCyPy.units import Quantity, particle, liter, second
+
+class ParticleCount:
+    """
+    A class to represent the quantity of particles in a flow, which can be defined
+    either as a concentration (particles per unit volume) or as a fixed number of particles.
+
+    Parameters
+    ----------
+    value : Quantity
+        The input quantity, either a concentration (e.g., particles/liter) or a fixed number of particles.
+    """
+
+    def __init__(self, value: Quantity):
+        """
+        Initializes the ParticleCount with either a concentration or a fixed number of particles.
+
+        Parameters
+        ----------
+        value : Quantity
+            A Quantity representing either a concentration (particles per unit volume)
+            or a fixed number of particles.
+
+        Raises
+        ------
+        ValueError
+            If the input value does not have the expected dimensionality.
+        """
+        if isinstance(value, ParticleCount):
+            self = value
+            return
+
+        if value.check(particle):
+            # Fixed number of particles
+            self.num_particles = value.to(particle)
+
+        elif value.check(particle / liter):
+            # Concentration of particles
+            self.concentration = value.to(particle / liter)
+        else:
+            raise ValueError(
+                "Value must have dimensions of either 'particles' or 'particles per unit volume'."
+            )
+
+    def calculate_number_of_events(self, flow_area: Quantity, flow_speed: Quantity, run_time: Quantity) -> Quantity:
+        """
+        Calculates the total number of particles based on the flow volume and the defined concentration.
+
+        Parameters
+        ----------
+        flow_volume : Quantity
+            The volume of the flow (e.g., in liters or cubic meters).
+
+        Returns
+        -------
+        Quantity
+            The total number of particles as a Quantity with the unit of 'particles'.
+
+        Raises
+        ------
+        ValueError
+            If no concentration is defined and the total number of particles cannot be calculated.
+        """
+        flow_volume = flow_area * flow_speed * run_time
+
+        if hasattr(self, 'concentration'):
+            return (self.concentration * flow_volume).to(particle)
+        elif hasattr(self, 'num_particles'):
+            return self.num_particles
+        else:
+            raise ValueError("Either a number of particles or a concentration must be defined.")
+
+    def compute_particle_flux(self, flow_speed: Quantity, flow_area: Quantity, run_time: Quantity) -> Quantity:
+        """
+        Computes the particle flux in the flow system, accounting for flow speed,
+        flow area, and either the particle concentration or a predefined number of particles.
+
+        Parameters
+        ----------
+        flow_speed : Quantity
+            The speed of the flow (e.g., in meters per second).
+        flow_area : Quantity
+            The cross-sectional area of the flow tube (e.g., in square meters).
+        run_time : Quantity
+            The total duration of the flow (e.g., in seconds).
+
+        Returns
+        -------
+        Quantity
+            The particle flux in particles per second (particle/second).
+        """
+        if hasattr(self, 'num_particles'):
+            return self.num_particles / run_time
+
+        flow_volume_per_second = (flow_speed * flow_area).to(liter / second)
+        particle_flux = (self.concentration * flow_volume_per_second).to(particle / second)
+        return particle_flux
+
+    def __repr__(self):
+        if hasattr(self, 'concentration'):
+            return f"{self.concentration}"
+        else:
+            return f"{self.num_particles}"
+
+    def __truediv__(self, factor: float):
+        if hasattr(self, 'concentration'):
+            self.concentration /= factor
+        else:
+            self.num_particles /= factor
+
+        return self
+
+    def __mul__(self, factor: float):
+        if hasattr(self, 'concentration'):
+            self.concentration *= factor
+        else:
+            self.num_particles *= factor
+
+        return self
+
+    @property
+    def value(self):
+        if hasattr(self, 'concentration'):
+            return self.concentration
+        else:
+            return self.num_particles
+

FlowCyPy/peak_locator/__init__.py

@@ -0,0 +1,4 @@
+from .base_class import BasePeakLocator
+from .basic import BasicPeakLocator
+from .moving_average import MovingAverage
+from .derivative import DerivativePeakLocator