FlowCyPy 0.5.6__tar.gz → 0.5.8__tar.gz

{flowcypy-0.5.6 → flowcypy-0.5.8}/FlowCyPy/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.5.6'
-__version_tuple__ = version_tuple = (0, 5, 6)
+__version__ = version = '0.5.8'
+__version_tuple__ = version_tuple = (0, 5, 8)

flowcypy-0.5.8/FlowCyPy/cytometer.py

@@ -0,0 +1,396 @@
+#!/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
+        self.plot = self.PlotInterface(self)
+
+        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 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
+
+    class PlotInterface:
+        def __init__(self, cytometer):
+            self.cytometer = cytometer
+
+        def signals(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.")
+
+            scatterer_collection = self.cytometer.scatterer_collection
+            detectors = self.cytometer.detectors
+
+            n_detectors = len(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 = detectors[0].plot(ax=axes[0], show=False, add_peak_locator=add_peak_locator)
+            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)
+            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 coupling_distribution(self, log_scale: bool = False, show: bool = True, equal_limits: bool = False, save_path: str = None) -> 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).
+            equal_limits : bool, optional
+                If True, sets the same limits for both the x and y axes based on the maximum range
+                across both axes. If False, the limits are set automatically based on the data (default: False).
+
+            """
+            scatterer_collection = self.cytometer.scatterer_collection
+            detector_0, detector_1 = self.cytometer.detectors
+
+            with plt.style.context(mps):
+                joint_plot = sns.jointplot(
+                    data=scatterer_collection.dataframe,
+                    x=f'detector: {detector_0.name}',
+                    y=f'detector: {detector_1.name}',
+                    hue="Population",
+                    alpha=0.8,
+                )
+
+            if log_scale:
+                joint_plot.ax_joint.set_xscale('log')
+                joint_plot.ax_joint.set_yscale('log')
+
+            if equal_limits:
+                # Get data limits
+                x_data = scatterer_collection.dataframe[f'detector: {detector_0.name}']
+                y_data = scatterer_collection.dataframe[f'detector: {detector_1.name}']
+
+                x_min, x_max = x_data.min(), x_data.max()
+                y_min, y_max = y_data.min(), y_data.max()
+
+                # Find the overall min and max
+                overall_min = min(x_min, y_min)
+                overall_max = max(x_max, y_max)
+
+                # Set equal limits
+                joint_plot.ax_joint.set_xlim(overall_min, overall_max)
+                joint_plot.ax_joint.set_ylim(overall_min, overall_max)
+
+            if save_path:
+                joint_plot.figure.savefig(save_path, dpi=300, bbox_inches='tight')
+                print(f"Plot saved to {save_path}")
+
+            if show:  # Display the plot
+                plt.show()

{flowcypy-0.5.6 → flowcypy-0.5.8}/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()

{flowcypy-0.5.6 → flowcypy-0.5.8}/FlowCyPy/flow_cell.py

@@ -130,14 +130,14 @@ class FlowCell(object):
             ['Flow Area', f"{self.flow_area:.2f~#P}"],
             ['Total Time', f"{self.run_time:.2f~#P}"]
         ]
-    
+
     # def initialize(self, scatterer: Population | ScattererCollection) -> None:
     #     if isinstance(scatterer, Population):
     #         return self._initialize_population(scatterer)
 
     #     elif isinstance(scatterer, ScattererCollection):
     #         return self._initialize_scatterer_collection(scatterer)
-    
+
     def _initialize_population(self, population: Population) -> None:
         population.dataframe = pandas.DataFrame()
 
@@ -164,13 +164,13 @@ class FlowCell(object):
         scatterer : Scatterer
             An instance of the Scatterer class that describes the scatterer collection being used.
 
-        """        
+        """
         self.scatterer_collection = scatterer_collection
 
         for population in self.scatterer_collection.populations:
             self._initialize_population(population)
             population.dataframe.Size = population.dataframe.Size.pint.to(size_units)
-        
+
         if len(self.scatterer_collection.populations) != 0:
             self.scatterer_collection.dataframe = pandas.concat(
                 [population.dataframe for population in self.scatterer_collection.populations],
@@ -195,7 +195,7 @@ class FlowCell(object):
                 index=multi_index
             )
 
-        self.scatterer_collection.n_events = len(self.scatterer_collection.dataframe)        
+        self.scatterer_collection.n_events = len(self.scatterer_collection.dataframe)
 
     def distribute_time_linearly(self, sequential_population: bool = False) -> None:
         """
@@ -210,14 +210,14 @@ class FlowCell(object):
 
         """
         # Generate linearly spaced time values across the flow cell runtime
-        linear_spacing = numpy.linspace(0, self.run_time, self.n_events)
+        linear_spacing = numpy.linspace(0, self.run_time, self.scatterer_collection.n_events)
 
         # Optionally randomize the linear spacing
         if not sequential_population:
             numpy.random.shuffle(linear_spacing)
 
         # Assign the linearly spaced or randomized times to the scatterer DataFrame
-        self.scatterer_collectionscatterer.dataframe.Time = PintArray(linear_spacing, dtype=self.scatterer_collection.dataframe.Time.pint.units)        
+        self.scatterer_collection.dataframe.Time = PintArray(linear_spacing, dtype=self.scatterer_collection.dataframe.Time.pint.units)
 
     def _generate_longitudinal_positions(self, population: Population) -> None:
         r"""

{flowcypy-0.5.6 → flowcypy-0.5.8}/FlowCyPy/noises.py

@@ -1,6 +1,11 @@
+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:
+class NoiseSetting(metaclass=RestrictiveMeta):
     _instance = None
 
     def __new__(cls, *args, **kwargs):

{flowcypy-0.5.6 → flowcypy-0.5.8}/FlowCyPy/particle_count.py

@@ -27,14 +27,17 @@ class ParticleCount:
         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)
-            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'."
@@ -61,10 +64,10 @@ class ParticleCount:
         """
         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:
+        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.")
 
@@ -87,7 +90,7 @@ class ParticleCount:
         Quantity
             The particle flux in particles per second (particle/second).
         """
-        if self.concentration is None:
+        if hasattr(self, 'num_particles'):
             return self.num_particles / run_time
 
         flow_volume_per_second = (flow_speed * flow_area).to(liter / second)
@@ -95,8 +98,19 @@ class ParticleCount:
         return particle_flux
 
     def __repr__(self):
-        if self.num_particles is not None:
-            return f"{self.num_particles}"
-        elif self.concentration is not None:
+        if hasattr(self, 'concentration'):
             return f"{self.concentration}"
-        return "Undefined"
+        else:
+            return f"{self.num_particles}"
+    
+    def __truediv__(self, factor: float):
+        if hasattr(self, 'concentration'):
+            self.concentration /= factor
+        else:
+            self.num_particles /= factor
+
+    def __mul__(self, factor: float):
+        if hasattr(self, 'concentration'):
+            self.concentration *= factor
+        else:
+            self.num_particles *= factor            

{flowcypy-0.5.6 → flowcypy-0.5.8}/FlowCyPy/population.py

@@ -38,13 +38,14 @@ class Population(PropertiesReport):
     name: str
     refractive_index: Union[distribution.Base, Quantity]
     size: Union[distribution.Base, Quantity]
-    particle_count: ParticleCount = field(init=False)
+    particle_count: ParticleCount | Quantity
 
     def __post_init__(self):
         """
         Automatically converts all Quantity attributes to their base SI units (i.e., without any prefixes).
         This strips units like millimeter to meter, kilogram to gram, etc.
         """
+        self.particle_count = ParticleCount(self.particle_count)
         # Convert all Quantity attributes to base SI units (without any prefixes)
         for attr_name, attr_value in vars(self).items():
             if isinstance(attr_value, Quantity):
@@ -131,5 +132,8 @@ class Population(PropertiesReport):
             return value
 
         raise TypeError(f"suze must be of type Quantity or distribution.Base, but got {type(value)}")
+    
+    def dilute(self, factor: float) -> None:
+        self.particle_count /= factor
 
 from FlowCyPy.populations_instances import *  # noqa F403

{flowcypy-0.5.6 → flowcypy-0.5.8}/FlowCyPy/populations_instances.py

@@ -1,7 +1,28 @@
-from FlowCyPy.units import Quantity, nanometer, RIU, micrometer
+from FlowCyPy.units import Quantity, nanometer, RIU, micrometer, particle
 from FlowCyPy.population import Population
 from FlowCyPy import distribution
 
+class CallablePopulationMeta(type):
+    def __getattr__(cls, attr):
+        raise AttributeError(f"{cls.__name__} must be called as {cls.__name__}() to access its population instance.")
+
+
+class CallablePopulation(metaclass=CallablePopulationMeta):
+    def __init__(self, name, size_dist, ri_dist):
+        self._name = name
+        self._size_distribution = size_dist
+        self._ri_distribution = ri_dist
+
+    def __call__(self, particle_count: Quantity = 1 * particle):
+        return Population(
+            particle_count=particle_count,
+            name=self._name,
+            size=self._size_distribution,
+            refractive_index=self._ri_distribution,
+        )
+
+
+# Define populations
 _populations = (
     ('Exosome',          70 * nanometer, 2.0, 1.39 * RIU, 0.02 * RIU),
     ('MicroVesicle',    400 * nanometer, 1.5, 1.39 * RIU, 0.02 * RIU),
@@ -13,7 +34,7 @@ _populations = (
     ('CellularDebris',   3 * micrometer, 1.0, 1.40 * RIU, 0.03 * RIU),
 )
 
-
+# Dynamically create population classes
 for (name, size, size_spread, ri, ri_spread) in _populations:
     size_distribution = distribution.RosinRammler(
         characteristic_size=size,
@@ -25,19 +46,14 @@ for (name, size, size_spread, ri, ri_spread) in _populations:
         std_dev=ri_spread
     )
 
-    population = Population(
-        name=name,
-        size=size_distribution,
-        refractive_index=ri_distribution,
-    )
-
-    locals()[name] = population
+    # Create a class dynamically for each population
+    cls = type(name, (CallablePopulation,), {})
+    globals()[name] = cls(name, size_distribution, ri_distribution)
 
 
+# Helper function for microbeads
 def get_microbeads(size: Quantity, refractive_index: Quantity, name: str) -> Population:
-
     size_distribution = distribution.Delta(position=size)
-
     ri_distribution = distribution.Delta(position=refractive_index)
 
     microbeads = Population(