FlowCyPy 0.5.0__py3-none-any.whl

FlowCyPy/logger.py

@@ -0,0 +1,322 @@
+import logging
+from tabulate import tabulate
+import pandas as pd
+from typing import List, Union, Optional
+from FlowCyPy.units import particle, milliliter
+
+
+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.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}"
+            measured_concentration = num_events * particle / self.correlator.cytometer.scatterer.flow_cell.volume.to(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)
+        ]
+
+
+class ScattererLogger:
+    """
+    Logs key properties of scatterers in formatted tables.
+
+    Parameters
+    ----------
+    scatterers : list
+        List of scatterer instances to log properties for.
+    """
+
+    def __init__(self, scatterers: List[object]):
+        """
+        Initializes the ScattererLogger with the scatterers to log.
+
+        Parameters
+        ----------
+        scatterers : list
+            List of scatterer objects.
+        """
+        self.scatterers = scatterers
+
+    def log_properties(self, table_format: str = "grid") -> None:
+        """
+        Logs properties of scatterers in formatted tables.
+
+        Parameters
+        ----------
+        table_format : str, optional
+            The format for the table display (default is 'grid').
+            Options include 'plain', 'github', 'grid', 'fancy_grid', etc., as supported by tabulate.
+        """
+        logging.info("\n=== Scatterer Properties Summary ===")
+
+        # First table: General properties
+        general_table_data = [self._get_population_properties(population) for population in self.scatterers.populations]
+        general_headers = [
+            "Name",
+            "Refractive Index",
+            "Medium Refractive Index",
+            "Size",
+            "Particle Count",
+            "Number of Events",
+            "Min Time Between Events",
+            "Avg Time Between Events"
+        ]
+        formatted_general_table = tabulate(general_table_data, headers=general_headers, tablefmt=table_format, floatfmt=".4f")
+        logging.info("\n" + formatted_general_table)
+
+    def _get_population_properties(self, population: object) -> List[Union[str, float]]:
+        """
+        Extracts key properties of a scatterer for the general properties table.
+
+        Parameters
+        ----------
+        population : object
+            A scatterer object with properties such as name, refractive index, size, etc.
+
+        Returns
+        -------
+        list
+            List of scatterer properties: [name, refractive index, size, concentration, number of events].
+        """
+        name = population.name
+        refractive_index = f"{population.refractive_index}"
+        medium_refractive_index = f"{self.scatterers.medium_refractive_index}"
+        size = f"{population.size}"
+        concentration = f"{population.particle_count}"
+        num_events = population.n_events
+
+        min_delta_position = abs(population.dataframe['Time'].diff()).min().to_compact()
+        avg_delta_position = population.dataframe['Time'].diff().mean().to_compact()
+
+        return [name, refractive_index, medium_refractive_index, size, concentration, num_events, avg_delta_position, min_delta_position]
+
+
+class SimulationLogger:
+    """
+    Logs key statistics about the simulated pulse events for each detector.
+    Provides an organized summary of simulation events, including total events,
+    average time between events, first and last event times, and minimum time between events.
+
+    Parameters
+    ----------
+    cytometer : object
+        The cytometer instance which containes info on detected pulse.
+    """
+
+    def __init__(self, cytometer: object):
+        self.cytometer = cytometer
+        self.detectors = cytometer.detectors
+        self.pulse_dataframe = cytometer.pulse_dataframe
+
+    def log_statistics(self, include_totals: bool = True, table_format: str = "grid") -> None:
+        """
+        Logs summary statistics for each detector in a formatted table.
+
+        Parameters
+        ----------
+        include_totals : bool, optional
+            If True, logs the total number of events across all detectors (default is True).
+        table_format : str, optional
+            The format for the table display (default is 'grid').
+            Options include 'plain', 'github', 'grid', 'fancy_grid', etc., as supported by tabulate.
+        """
+        logging.info("\n=== Simulation Statistics Summary ===")
+
+        table_data = [self._get_detector_stats(detector) for detector in self.detectors]
+        headers = [
+            "Detector",
+            "Number of Events",
+            "Saturated",
+            "First Event Time",
+            "Last Event Time",
+            "Avg Time Between Events",
+            "Min Time Between Events",
+            "Mean event rate"
+        ]
+
+        formatted_table = tabulate(table_data, headers=headers, tablefmt=table_format, floatfmt=".3f")
+        logging.info("\n" + formatted_table)
+
+        if include_totals:
+            total_events = sum(stat[1] for stat in table_data)  # Sum of events from all detectors
+            logging.info(f"\nTotal number of events detected across all detectors: {total_events}")
+
+    def _get_detector_stats(self, detector) -> List[Union[str, int, Optional[str]]]:
+        """
+        Computes statistics for a single detector.
+
+        Parameters
+        ----------
+        detector : object
+            A detector object with 'name' and pulse event data attributes.
+
+        Returns
+        -------
+        list
+            List of computed statistics: [detector name, num_events, first_event_time, last_event_time,
+            avg_time_between_events, min_time_between_events, mean_detection_rate]
+        """
+        centers = self.pulse_dataframe['Centers']
+        num_events = len(centers)
+
+        if num_events > 1:
+            centers_sorted = centers.sort_values()
+            time_diffs = centers_sorted.diff().dropna()  # Time differences between events
+            avg_time_between_events = self._format_time(time_diffs.mean())
+            min_time_between_events = self._format_time(time_diffs.min())
+        else:
+            avg_time_between_events = "N/A"
+            min_time_between_events = "N/A"
+
+        first_event_time = self._format_time(centers.min()) if num_events > 0 else "N/A"
+        last_event_time = self._format_time(centers.max()) if num_events > 0 else "N/A"
+
+        mean_event_rate = (num_events / self.cytometer.scatterer.flow_cell.run_time).to('Hz')
+
+        return [
+            detector.name,
+            num_events,
+            detector.is_saturated,  # Was the detector saturated at some point
+            first_event_time,
+            last_event_time,
+            avg_time_between_events,
+            min_time_between_events,
+            mean_event_rate
+        ]
+
+    def _format_time(self, time_value) -> str:
+        """
+        Formats a time value for display, converting to compact notation if available.
+
+        Parameters
+        ----------
+        time_value : pint.Quantity or pd.Timestamp or float
+            The time value to format.
+
+        Returns
+        -------
+        str
+            The formatted time string.
+        """
+        try:
+            return f"{time_value.to_compact():.4~P}"
+        except AttributeError:
+            return f"{time_value:.4f}" if pd.notnull(time_value) else "N/A"

FlowCyPy/noises.py

@@ -0,0 +1,29 @@
+
+
+class NoiseSetting:
+    _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,102 @@
+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 value.check(particle):
+            # Fixed number of particles
+            self.num_particles = value.to(particle)
+            self.concentration = None
+        elif value.check(particle / liter):
+            # Concentration of particles
+            self.concentration = value.to(particle / liter)
+            self.num_particles = None
+        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 self.num_particles is not None:
+            return self.num_particles
+        elif self.concentration is not None:
+            return (self.concentration * flow_volume).to(particle)
+        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 self.concentration is None:
+            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 self.num_particles is not None:
+            return f"{self.num_particles}"
+        elif self.concentration is not None:
+            return f"{self.concentration}"
+        return "Undefined"

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

FlowCyPy/peak_locator/base_class.py

@@ -0,0 +1,163 @@
+import numpy as np
+import pandas as pd
+from scipy.integrate import cumulative_trapezoid
+import matplotlib.pyplot as plt
+import pint_pandas
+from abc import ABC, abstractmethod
+from FlowCyPy.units import Quantity
+from scipy.signal import peak_widths
+
+
+class BasePeakLocator(ABC):
+    """
+    A base class to handle common functionality for peak detection,
+    including area calculation under peaks.
+    """
+
+    peak_properties: pd.DataFrame = None
+
+    def init_data(self, dataframe: pd.DataFrame) -> None:
+        """
+        Initialize signal and time data for peak detection.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            A DataFrame containing the signal data with columns 'Signal' and 'Time'.
+
+        Raises
+        ------
+        ValueError
+            If the DataFrame is missing required columns or is empty.
+        """
+        if not {'Signal', 'Time'}.issubset(dataframe.columns):
+            raise ValueError("The DataFrame must contain 'Signal' and 'Time' columns.")
+
+        if dataframe.empty:
+            raise ValueError("The DataFrame is empty. Please provide valid signal data.")
+
+        self.data = pd.DataFrame(index=np.arange(len(dataframe)))
+        self.data['Signal'] = dataframe['Signal']
+        self.data['Time'] = dataframe['Time']
+
+        self.dt = self.data.Time[1] - self.data.Time[0]
+
+    @abstractmethod
+    def _compute_algorithm_specific_features(self) -> None:
+        """
+        Abstract method for computing features specific to the detection algorithm.
+        This must be implemented by subclasses.
+        """
+        pass
+
+    def detect_peaks(self, compute_area: bool = True) -> pd.DataFrame:
+        """
+        Detect peaks and compute peak properties.
+
+        Parameters
+        ----------
+        compute_area : bool, optional
+            If True, computes the area under each peak (default is True).
+
+        Returns
+        -------
+        pd.DataFrame
+            A DataFrame containing peak properties (times, heights, widths, etc.).
+        """
+        peak_indices, widths_samples, width_heights, left_ips, right_ips = self._compute_algorithm_specific_features()
+
+        peak_times = self.data['Time'].values[peak_indices]
+        heights = self.data['Signal'].values[peak_indices]
+        widths = widths_samples * self.dt
+
+        # Store results in `peak_properties`
+        self.peak_properties = pd.DataFrame({
+            'PeakTimes': peak_times,
+            'Heights': heights,
+            'Widths': pint_pandas.PintArray(widths, dtype=widths.units),
+            'WidthHeights': pint_pandas.PintArray(width_heights, dtype=heights.units),
+            'LeftIPs': pint_pandas.PintArray(left_ips * self.dt, dtype=self.dt.units),
+            'RightIPs': pint_pandas.PintArray(right_ips * self.dt, dtype=self.dt.units),
+        })
+
+        # Compute areas if needed
+        if compute_area:
+            self._compute_peak_areas()
+
+        return self.peak_properties
+
+    def _compute_peak_areas(self) -> None:
+        """
+        Computes the areas under the detected peaks using cumulative integration.
+
+        The cumulative integral of the signal is interpolated at the left and right
+        interpolated positions of each peak to compute the enclosed area.
+
+        Adds an 'Areas' column to `self.peak_properties`.
+
+        Raises
+        ------
+        RuntimeError
+            If `peak_properties` or `data` has not been initialized.
+        """
+        if not hasattr(self, 'peak_properties') or self.peak_properties.empty:
+            raise RuntimeError("No peaks detected. Run `detect_peaks()` first.")
+
+        if not hasattr(self, 'data') or self.data.empty:
+            raise RuntimeError("Signal data is not initialized. Call `init_data()` first.")
+
+        # Compute cumulative integral of the signal
+        cumulative = cumulative_trapezoid(
+            self.data.Signal.values.quantity.magnitude,
+            x=self.data.Time.values.quantity.magnitude,
+            initial=0  # Include 0 at the start
+        )
+
+        # Interpolate cumulative integral at left and right interpolated positions
+        left_cum_integral = np.interp(
+            x=self.peak_properties.LeftIPs,
+            xp=self.data.index,
+            fp=cumulative
+        )
+        right_cum_integral = np.interp(
+            x=self.peak_properties.RightIPs,
+            xp=self.data.index,
+            fp=cumulative
+        )
+
+        # Compute areas under peaks
+        areas = right_cum_integral - left_cum_integral
+
+        # Add areas with units to peak properties
+        self.peak_properties['Areas'] = pint_pandas.PintArray(
+            areas, dtype=self.data.Signal.pint.units * self.data.Time.pint.units
+        )
+
+    def _add_to_ax(self, time_unit: str | Quantity, signal_unit: str | Quantity, ax: plt.Axes = None) -> None:
+        """
+        Plots the signal with detected peaks and FWHM lines.
+
+        Parameters
+        ----------
+        time_unit : str or Quantity
+            Unit for the time axis (e.g., 'microsecond').
+        signal_unit : str or Quantity
+            Unit for the signal axis (e.g., 'volt').
+        ax : plt.Axes
+            The matplotlib Axes to plot on. Creates a new figure if not provided.
+        """
+        # Plot vertical lines at peak times
+        for _, row in self.peak_properties.iterrows():
+            ax.axvline(row['PeakTimes'].to(time_unit), color='black', linestyle='-', lw=0.8)
+
+        self._add_custom_to_ax(ax=ax, time_unit=time_unit, signal_unit=signal_unit)
+
+    def _compute_peak_widths(self, peak_indices: list[int], values: np.ndarray) -> None:
+        # Compute peak properties
+        widths_samples, width_heights, left_ips, right_ips = peak_widths(
+            x=values,
+            peaks=peak_indices,
+            rel_height=self.rel_height
+        )
+
+        return widths_samples, width_heights, left_ips, right_ips