FlowCyPy 0.5.3__tar.gz → 0.5.7__tar.gz

{flowcypy-0.5.3 → flowcypy-0.5.7}/FlowCyPy/__init__.py

@@ -7,7 +7,7 @@ except ImportError:
 from .units import ureg, watt, meter, second, liter, particle
 from .cytometer import FlowCytometer
 from .event_correlator import EventCorrelator
-from .scatterer import Scatterer, CouplingModel
+from .scatterer_collection import ScattererCollection, CouplingModel
 from .population import Population
 from .detector import Detector
 from .flow_cell import FlowCell

{flowcypy-0.5.3 → flowcypy-0.5.7}/FlowCyPy/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.5.3'
-__version_tuple__ = version_tuple = (0, 5, 3)
+__version__ = version = '0.5.7'
+__version_tuple__ = version_tuple = (0, 5, 7)

{flowcypy-0.5.3 → flowcypy-0.5.7}/FlowCyPy/coupling_mechanism/empirical.py

@@ -1,10 +1,10 @@
 import numpy as np
-from FlowCyPy import Scatterer, Detector
+from FlowCyPy import ScattererCollection, Detector
 from FlowCyPy.source import BaseBeam
 from FlowCyPy.units import watt, meter
 
 
-def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: Scatterer, granularity: float = 1.0, A: float = 1.5, n: float = 2.0) -> float:
+def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: ScattererCollection, granularity: float = 1.0, A: float = 1.5, n: float = 2.0) -> float:
     """
     Empirical model for scattering intensity based on particle size, granularity, and detector angle.
 

{flowcypy-0.5.3 → flowcypy-0.5.7}/FlowCyPy/coupling_mechanism/mie.py

@@ -1,5 +1,5 @@
 import numpy as np
-from FlowCyPy import Scatterer, Detector
+from FlowCyPy import ScattererCollection, Detector
 from FlowCyPy.source import BaseBeam
 from PyMieSim.experiment.scatterer import Sphere as PMS_SPHERE
 from PyMieSim.experiment.source import PlaneWave
@@ -94,13 +94,13 @@ def apply_rin_noise(source: BaseBeam, total_size: int, bandwidth: float) -> np.n
     return amplitude_with_rin
 
 
-def initialize_scatterer(scatterer: Scatterer, source: PlaneWave) -> PMS_SPHERE:
+def initialize_scatterer(scatterer: ScattererCollection, source: PlaneWave) -> PMS_SPHERE:
     """
     Initializes the scatterer object for the PyMieSim experiment.
 
     Parameters
     ----------
-    scatterer : Scatterer
+    scatterer : ScattererCollection
         The scatterer object containing particle data.
     source : PlaneWave
         The light source for the simulation.
@@ -114,7 +114,7 @@ def initialize_scatterer(scatterer: Scatterer, source: PlaneWave) -> PMS_SPHERE:
     ri_list = scatterer.dataframe['RefractiveIndex'].values
 
     if len(size_list) == 0:
-        raise ValueError("Scatterer size list is empty.")
+        raise ValueError("ScattererCollection size list is empty.")
 
     size_list = size_list.quantity.magnitude * size_list.units
     ri_list = ri_list.quantity.magnitude * ri_list.units
@@ -155,7 +155,7 @@ def initialize_detector(detector: Detector, total_size: int) -> PMS_PHOTODIODE:
     )
 
 
-def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: Scatterer, tolerance: float = 1e-5) -> np.ndarray:
+def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: ScattererCollection, tolerance: float = 1e-5) -> np.ndarray:
     """
     Computes the detected signal by analyzing the scattering properties of particles.
 
@@ -165,7 +165,7 @@ def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: Sca
         The light source object containing wavelength, power, and other optical properties.
     detector : Detector
         The detector object containing properties such as numerical aperture and angles.
-    scatterer : Scatterer
+    scatterer : ScattererCollection
         The scatterer object containing particle size and refractive index data.
     tolerance : float, optional
         The tolerance for deciding if two values of size and refractive index are "close enough" to be cached.

{flowcypy-0.5.3 → flowcypy-0.5.7}/FlowCyPy/coupling_mechanism/rayleigh.py

@@ -1,11 +1,11 @@
 
 import numpy as np
-from FlowCyPy import Scatterer, Detector
+from FlowCyPy import ScattererCollection, Detector
 from FlowCyPy.source import BaseBeam
 from FlowCyPy.units import meter
 
 
-def compute_scattering_cross_section(scatterer: Scatterer, source: BaseBeam, detector: Detector) -> np.ndarray:
+def compute_scattering_cross_section(scatterer: ScattererCollection, source: BaseBeam, detector: Detector) -> np.ndarray:
     r"""
     Computes the Rayleigh scattering cross-section for a spherical particle with angle dependency.
 
@@ -28,8 +28,8 @@ def compute_scattering_cross_section(scatterer: Scatterer, source: BaseBeam, det
 
     Parameters
     ----------
-    scatterer : Scatterer
-        An instance of `Scatterer` containing the scatterer properties such as size and refractive index.
+    scatterer : ScattererCollection
+        An instance of `ScattererCollection` containing the scatterer properties such as size and refractive index.
     source : BaseBeam
         An instance of `BaseBeam` containing the laser properties, including the wavelength.
     detector : Detector
@@ -63,7 +63,7 @@ def compute_scattering_cross_section(scatterer: Scatterer, source: BaseBeam, det
     return cross_section.magnitude * meter**2
 
 
-def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: Scatterer) -> float:
+def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: ScattererCollection) -> float:
     r"""
     Computes the power detected by a detector from a Rayleigh scattering event.
 

{flowcypy-0.5.3 → flowcypy-0.5.7}/FlowCyPy/coupling_mechanism/uniform.py

@@ -1,9 +1,9 @@
 import numpy as np
-from FlowCyPy import Scatterer, Detector, ureg
+from FlowCyPy import ScattererCollection, Detector, ureg
 from FlowCyPy.source import BaseBeam
 
 
-def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: Scatterer) -> np.ndarray:
+def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: ScattererCollection) -> np.ndarray:
     r"""
     Computes the power detected by a detector from a uniform distribution.
 

flowcypy-0.5.7/FlowCyPy/cytometer.py

@@ -0,0 +1,363 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import logging
+import numpy as np
+import matplotlib.pyplot as plt
+from typing import List, Callable, Optional
+from MPSPlots.styles import mps
+from FlowCyPy.flow_cell import FlowCell
+from FlowCyPy.detector import Detector
+import pandas as pd
+import pint_pandas
+from FlowCyPy.units import Quantity, milliwatt
+from FlowCyPy.logger import SimulationLogger
+import seaborn as sns
+
+# Set up logging configuration
+logging.basicConfig(
+    level=logging.INFO,
+    format='%(levelname)s - %(message)s'
+)
+
+
+class FlowCytometer:
+    """
+    A simulation class for modeling flow cytometer signals, including Forward Scatter (FSC) and Side Scatter (SSC) channels.
+
+    The FlowCytometer class integrates optical and flow dynamics to simulate signal generation in a flow cytometer.
+    It handles particle distributions, flow cell properties, laser source configurations, and detector behavior to
+    replicate realistic cytometry conditions. This includes the generation of synthetic signal pulses for each
+    particle event and noise modeling for accurate signal representation.
+
+    Parameters
+    ----------
+    flow_cell : FlowCell
+        The flow cell object representing the fluidic and optical environment through which particles travel.
+    detectors : List[Detector]
+        A list of `Detector` objects representing the detectors used to measure optical signals (e.g., FSC and SSC). Exactly two detectors must be provided.
+    coupling_mechanism : str, optional
+        The scattering mechanism used to couple the signal from the particles to the detectors.
+        Supported mechanisms include: 'mie' (default): Mie scattering, 'rayleigh': Rayleigh scattering, 'uniform': Uniform signal coupling, 'empirical': Empirical data-driven coupling
+    background_power : Quantity, optional
+        The background optical power added to the detector signal. Defaults to 0 milliwatts.
+
+    Attributes
+    ----------
+    flow_cell : FlowCell
+        The flow cell instance representing the system environment.
+    scatterer_collection : ScattererCollection
+        A collection of particles or scatterers passing through the flow cytometer.
+    source : GaussianBeam
+        The laser beam source providing illumination to the flow cytometer.
+    detectors : List[Detector]
+        The detectors used to collect and process signals from the scatterers.
+    coupling_mechanism : str
+        The selected mechanism for signal coupling.
+    background_power : Quantity
+        The optical background power added to the detector signals.
+
+    Raises
+    ------
+    AssertionError
+        If the number of detectors provided is not exactly two, or if both detectors share the same name.
+
+    """
+    def __init__(
+            self,
+            flow_cell: FlowCell,
+            detectors: List[Detector],
+            coupling_mechanism: Optional[str] = 'mie',
+            background_power: Optional[Quantity] = 0 * milliwatt):
+
+        self.flow_cell = flow_cell
+        self.scatterer_collection = flow_cell.scatterer_collection
+        self.source = flow_cell.source
+        self.detectors = detectors
+        self.coupling_mechanism = coupling_mechanism
+        self.background_power = background_power
+
+        assert len(self.detectors) == 2, 'For now, FlowCytometer can only take two detectors for the analysis.'
+        assert self.detectors[0].name != self.detectors[1].name, 'Both detectors cannot have the same name'
+
+    def run_coupling_analysis(self) -> None:
+        """
+        Computes and assigns the optical coupling power for each particle-detection event.
+
+        This method evaluates the coupling between the scatterers in the flow cell and the detectors
+        using the specified detection mechanism. The computed coupling power is stored in the 
+        `scatterer_collection` dataframe under detector-specific columns.
+
+        Updates
+        -------
+        scatterer_collection.dataframe : pandas.DataFrame
+            Adds columns for each detector, labeled as "detector: <detector_name>", containing the computed
+            coupling power for all particle events.
+
+        Raises
+        ------
+        ValueError
+            If an invalid coupling mechanism is specified during initialization.
+        """        
+        detection_mechanism = self._get_detection_mechanism()
+
+        for detector in self.detectors:
+            self.coupling_power = detection_mechanism(
+                source=self.source,
+                detector=detector,
+                scatterer=self.scatterer_collection
+            )
+
+            self.scatterer_collection.dataframe["detector: " + detector.name] = pint_pandas.PintArray(self.coupling_power, dtype=self.coupling_power.units)
+        
+        self._generate_pulse_parameters()
+
+    def initialize_signal(self) -> None:
+        """
+        Initializes the raw signal for each detector based on the source and flow cell configuration.
+
+        This method prepares the detectors for signal capture by associating each detector with the
+        light source and generating a time-dependent raw signal placeholder.
+
+        Effects
+        -------
+        Each detector's `raw_signal` attribute is initialized with time-dependent values
+        based on the flow cell's runtime.
+
+        """        
+        # Initialize the detectors
+        for detector in self.detectors:
+            detector.source = self.source
+            detector.init_raw_signal(run_time=self.flow_cell.run_time)     
+
+    def simulate_pulse(self) -> None:
+        """
+        Simulates the generation of optical signal pulses for each particle event.
+
+        This method calculates Gaussian signal pulses based on particle positions, coupling power, and
+        widths. It adds the generated pulses, background power, and noise components (thermal and dark current)
+        to each detector's raw signal.
+
+        Notes
+        -----
+        - Adds Gaussian pulses to each detector's `raw_signal`.
+        - Includes noise and background power in the simulated signals.
+        - Updates detector dataframes with captured signal information.
+
+        Raises
+        ------
+        ValueError
+            If the scatterer collection lacks required data columns ('Widths', 'Time').
+        """
+        logging.debug("Starting pulse simulation.")
+
+        _widths = self.scatterer_collection.dataframe['Widths'].values
+        _centers = self.scatterer_collection.dataframe['Time'].values
+
+        for detector in self.detectors:
+            _coupling_power = self.scatterer_collection.dataframe["detector: " + detector.name].values
+
+            # Generate noise components
+            detector._add_thermal_noise_to_raw_signal()
+
+            detector._add_dark_current_noise_to_raw_signal()
+
+            # Broadcast the time array to the shape of (number of signals, len(detector.time))
+            time_grid = np.expand_dims(detector.dataframe.Time.values.numpy_data, axis=0) * _centers.units
+
+            centers = np.expand_dims(_centers.numpy_data, axis=1) * _centers.units
+            widths = np.expand_dims(_widths.numpy_data, axis=1) * _widths.units
+
+            # Compute the Gaussian for each height, center, and width using broadcasting
+            power_gaussians = _coupling_power[:, np.newaxis] * np.exp(- (time_grid - centers) ** 2 / (2 * widths ** 2))
+
+            total_power = np.sum(power_gaussians, axis=0) + self.background_power
+
+            # Sum all the Gaussians and add them to the detector.raw_signal
+            detector._add_optical_power_to_raw_signal(optical_power=total_power)
+
+            detector.capture_signal()
+
+        self._log_statistics()
+
+    def _log_statistics(self) -> SimulationLogger:
+        """
+        Logs and displays key statistics about the simulated events.
+
+        This includes metrics such as:
+        - Total number of events processed.
+        - Average time between events.
+        - First and last event times.
+        - Minimum time intervals between events.
+
+        Returns
+        -------
+        SimulationLogger
+            An instance of the logger containing all recorded statistics.
+
+        Effects
+        -------
+        Outputs formatted tables to the console or log file, depending on the logger's configuration.
+        """
+        logger = SimulationLogger(cytometer=self)
+
+        logger.log_statistics(include_totals=True, table_format="fancy_grid")
+
+        return logger
+
+    def _get_detection_mechanism(self) -> Callable:
+        """
+        Retrieves the detection mechanism function for signal coupling based on the selected method.
+
+        Supported Coupling Mechanisms
+        -----------------------------
+        - 'mie': Mie scattering.
+        - 'rayleigh': Rayleigh scattering.
+        - 'uniform': Uniform scattering.
+        - 'empirical': Empirical (data-driven) scattering.
+
+        Returns
+        -------
+        Callable
+            A function that computes the detected signal for scatterer sizes and particle distributions.
+
+        Raises
+        ------
+        ValueError
+            If an unsupported coupling mechanism is specified.
+        """
+        from FlowCyPy import coupling_mechanism
+
+        # Determine which coupling mechanism to use and compute the corresponding factors
+        match self.coupling_mechanism.lower():
+            case 'rayleigh':
+                return coupling_mechanism.rayleigh.compute_detected_signal
+            case 'uniform':
+                return coupling_mechanism.uniform.compute_detected_signal
+            case 'mie':
+                return coupling_mechanism.mie.compute_detected_signal
+            case 'empirical':
+                return coupling_mechanism.empirical.compute_detected_signal
+            case _:
+                raise ValueError("Invalid coupling mechanism. Choose 'rayleigh' or 'uniform'.")
+
+    def _generate_pulse_parameters(self) -> None:
+        """
+        Generates and assigns random Gaussian pulse parameters for each particle event.
+
+        The generated parameters include:
+        - Centers: The time at which each pulse occurs.
+        - Widths: The standard deviation (spread) of each pulse in seconds.
+
+        Effects
+        -------
+        scatterer_collection.dataframe : pandas.DataFrame
+            Adds a 'Widths' column with computed pulse widths for each particle.
+            Uses the flow speed and beam waist to calculate pulse widths.
+        """
+        columns = pd.MultiIndex.from_product(
+            [[p.name for p in self.detectors], ['Centers', 'Heights']]
+        )
+
+        self.pulse_dataframe = pd.DataFrame(columns=columns)
+                
+        self.pulse_dataframe['Centers'] = self.scatterer_collection.dataframe['Time']
+
+        widths = self.source.waist / self.flow_cell.flow_speed * np.ones(self.scatterer_collection.n_events)
+
+        self.scatterer_collection.dataframe['Widths'] = pint_pandas.PintArray(widths, dtype=widths.units)
+
+    def plot(self, figure_size: tuple = (10, 6), add_peak_locator: bool = False, show: bool = True) -> None:
+        """
+        Visualizes the raw signals for all detector channels along with the scatterer distribution.
+
+        Parameters
+        ----------
+        figure_size : tuple, optional
+            Dimensions of the generated plot (default: (10, 6)).
+        add_peak_locator : bool, optional
+            If True, adds visual markers for detected signal peaks (default: False).
+
+        Effects
+        -------
+        Displays a multi-panel plot showing:
+        - Raw signals for each detector channel.
+        - Scatterer distribution along the time axis.
+        """
+        logging.info("Plotting the signal for the different channels.")
+
+        n_detectors = len(self.detectors)
+
+        with plt.style.context(mps):
+            _, axes = plt.subplots(ncols=1, nrows=n_detectors + 1, figsize=figure_size, sharex=True, sharey=True, gridspec_kw={'height_ratios': [1, 1, 0.4]})
+
+        time_unit, signal_unit = self.detectors[0].plot(ax=axes[0], show=False, add_peak_locator=add_peak_locator)
+        self.detectors[1].plot(ax=axes[1], show=False, time_unit=time_unit, signal_unit=signal_unit, add_peak_locator=add_peak_locator)
+
+        axes[-1].get_yaxis().set_visible(False)
+        self.scatterer_collection.add_to_ax(axes[-1])
+
+        # Add legends to each subplot
+        for ax in axes:
+            ax.legend()
+
+        if show: # Display the plot
+            plt.show()       
+
+    def plot_coupling_density(self, log_scale: bool = False, show: bool = True) -> None:
+        """
+        Plots the density distribution of optical coupling in the FSC and SSC channels.
+
+        This method generates a joint plot showing the relationship between the signals from
+        the forward scatter ('detector: forward') and side scatter ('detector: side') detectors.
+        The plot is color-coded by particle population and can optionally display axes on a logarithmic scale.
+
+        Parameters
+        ----------
+        log_scale : bool, optional
+            If True, applies a logarithmic scale to both the x and y axes of the plot (default: False).
+        show : bool, optional
+            If True, displays the plot immediately. If False, the plot is created but not displayed,
+            allowing for further customization or saving externally (default: True).
+
+        """
+        with plt.style.context(mps):
+            joint_plot = sns.jointplot(
+                data=self.scatterer_collection.dataframe,
+                y='detector: side',
+                x='detector: forward',
+                hue="Population",
+                alpha=0.8,
+            )
+
+
+        if log_scale:
+            joint_plot.ax_joint.set_xscale('log')
+            joint_plot.ax_joint.set_yscale('log')    
+
+        if show: # Display the plot
+            plt.show()            
+
+    def add_detector(self, **kwargs) -> Detector:
+        """
+        Dynamically adds a new detector to the system configuration.
+
+        Parameters
+        ----------
+        **kwargs : dict
+            Keyword arguments passed to the `Detector` constructor.
+
+        Returns
+        -------
+        Detector
+            The newly added detector instance.
+
+        Effects
+        -------
+        - Appends the created detector to the `detectors` list.
+        """        
+        detector = Detector(**kwargs)
+
+        self.detectors.append(detector)
+
+        return detector

{flowcypy-0.5.3 → flowcypy-0.5.7}/FlowCyPy/event_correlator.py

@@ -8,7 +8,6 @@ from FlowCyPy.units import second
 import warnings
 from FlowCyPy.cytometer import FlowCytometer
 from FlowCyPy.logger import EventCorrelatorLogger
-from FlowCyPy.report import Report
 
 
 class EventCorrelator:
@@ -224,21 +223,3 @@ class EventCorrelator:
 
             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()