FlowCyPy 0.7.0__py3-none-any.whl

FlowCyPy/coupling_mechanism.py

@@ -0,0 +1,205 @@
+import numpy as np
+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
+from PyMieSim.experiment.detector import Photodiode as PMS_PHOTODIODE
+from PyMieSim.experiment import Setup
+from PyMieSim.units import degree, watt, AU, hertz
+from FlowCyPy.noises import NoiseSetting
+
+
+def apply_rin_noise(source: BaseBeam, total_size: int, bandwidth: float) -> np.ndarray:
+    r"""
+    Applies Relative Intensity Noise (RIN) to the source amplitude if enabled, accounting for detection bandwidth.
+
+    Parameters
+    ----------
+    source : BaseBeam
+        The light source containing amplitude and RIN information.
+    total_size : int
+        The number of particles being simulated.
+    bandwidth : float
+        The detection bandwidth in Hz.
+
+    Returns
+    -------
+    np.ndarray
+        Array of amplitudes with RIN noise applied.
+
+    Equations
+    ---------
+    1. Relative Intensity Noise (RIN):
+        RIN quantifies the fluctuations in the laser's intensity relative to its mean intensity.
+        RIN is typically specified as a power spectral density (PSD) in units of dB/Hz:
+        \[
+        \text{RIN (dB/Hz)} = 10 \cdot \log_{10}\left(\frac{\text{Noise Power (per Hz)}}{\text{Mean Power}}\right)
+        \]
+
+    2. Conversion from dB/Hz to Linear Scale:
+        To compute noise power, RIN must be converted from dB to a linear scale:
+        \[
+        \text{RIN (linear)} = 10^{\text{RIN (dB/Hz)} / 10}
+        \]
+
+    3. Total Noise Power:
+        The total noise power depends on the bandwidth (\(B\)) of the detection system:
+        \[
+        P_{\text{noise}} = \text{RIN (linear)} \cdot B
+        \]
+
+    4. Standard Deviation of Amplitude Fluctuations:
+        The noise standard deviation for amplitude is derived from the total noise power:
+        \[
+        \sigma_{\text{amplitude}} = \sqrt{P_{\text{noise}}} \cdot \text{Amplitude}
+        \]
+        Substituting \(P_{\text{noise}}\), we get:
+        \[
+        \sigma_{\text{amplitude}} = \sqrt{\text{RIN (linear)} \cdot B} \cdot \text{Amplitude}
+        \]
+
+    Implementation
+    --------------
+    - The RIN value from the source is converted to linear scale using:
+        \[
+        \text{RIN (linear)} = 10^{\text{source.RIN} / 10}
+        \]
+    - The noise standard deviation is scaled by the detection bandwidth (\(B\)) in Hz:
+        \[
+        \sigma_{\text{amplitude}} = \sqrt{\text{RIN (linear)} \cdot B} \cdot \text{source.amplitude}
+        \]
+    - Gaussian noise with mean \(0\) and standard deviation \(\sigma_{\text{amplitude}}\) is applied to the source amplitude.
+
+    Notes
+    -----
+    - The bandwidth parameter (\(B\)) must be in Hz and reflects the frequency range of the detection system.
+    - The function assumes that RIN is specified in dB/Hz. If RIN is already in linear scale, the conversion step can be skipped.
+    """
+    amplitude_with_rin = np.ones(total_size) * source.amplitude
+
+    if NoiseSetting.include_RIN_noise and NoiseSetting.include_noises:
+        # Convert RIN from dB/Hz to linear scale if necessary
+        rin_linear = 10**(source.RIN / 10)
+
+        # Compute noise standard deviation, scaled by bandwidth
+        std_dev_amplitude = np.sqrt(rin_linear * bandwidth.to(hertz).magnitude) * source.amplitude
+
+        # Apply Gaussian noise to the amplitude
+        amplitude_with_rin += np.random.normal(
+            loc=0,
+            scale=std_dev_amplitude.to(source.amplitude.units).magnitude,
+            size=total_size
+        ) * source.amplitude.units
+
+    return amplitude_with_rin
+
+
+def initialize_scatterer(scatterer: ScattererCollection, source: PlaneWave) -> PMS_SPHERE:
+    """
+    Initializes the scatterer object for the PyMieSim experiment.
+
+    Parameters
+    ----------
+    scatterer : ScattererCollection
+        The scatterer object containing particle data.
+    source : PlaneWave
+        The light source for the simulation.
+
+    Returns
+    -------
+    PMS_SPHERE
+        Initialized scatterer for the experiment.
+    """
+    size_list = scatterer.dataframe['Size'].values
+    ri_list = scatterer.dataframe['RefractiveIndex'].values
+
+    if len(size_list) == 0:
+        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
+
+    return PMS_SPHERE(
+        diameter=size_list,
+        property=ri_list,
+        medium_property=np.ones(len(size_list)) * scatterer.medium_refractive_index,
+        source=source
+    )
+
+
+def initialize_detector(detector: Detector, total_size: int) -> PMS_PHOTODIODE:
+    """
+    Initializes the detector object for the PyMieSim experiment.
+
+    Parameters
+    ----------
+    detector : Detector
+        The detector object containing configuration data.
+    total_size : int
+        The number of particles being simulated.
+
+    Returns
+    -------
+    PMS_PHOTODIODE
+        Initialized detector for the experiment.
+    """
+    ONES = np.ones(total_size)
+
+    return PMS_PHOTODIODE(
+        NA=ONES * detector.numerical_aperture,
+        cache_NA=ONES * 0 * AU,
+        gamma_offset=ONES * detector.gamma_angle,
+        phi_offset=ONES * detector.phi_angle,
+        polarization_filter=ONES * np.nan * degree,
+        sampling=ONES * detector.sampling
+    )
+
+
+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.
+
+    Parameters
+    ----------
+    source : BaseBeam
+        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 : 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.
+
+    Returns
+    -------
+    np.ndarray
+        Array of coupling values for each particle, based on the detected signal.
+    """
+    size_list = scatterer.dataframe['Size'].values
+
+    if len(size_list) == 0:
+        return np.array([]) * watt
+
+    total_size = len(size_list)
+    amplitude_with_rin = apply_rin_noise(source, total_size, detector.bandwidth)
+
+    pms_source = PlaneWave(
+        wavelength=np.ones(total_size) * source.wavelength,
+        polarization=np.ones(total_size) * 0 * degree,
+        amplitude=amplitude_with_rin
+    )
+
+    pms_scatterer = initialize_scatterer(scatterer, pms_source)
+    pms_detector = initialize_detector(detector, total_size)
+
+    # Configure the detector
+    pms_detector.mode_number = ['NC00'] * total_size
+    pms_detector.rotation = np.ones(total_size) * 0 * degree
+    pms_detector.__post_init__()
+
+    # Set up the experiment
+    experiment = Setup(source=pms_source, scatterer=pms_scatterer, detector=pms_detector)
+
+    # Compute coupling values
+    coupling_value = experiment.get_sequential('coupling').squeeze()
+    return np.atleast_1d(coupling_value) * watt

FlowCyPy/cytometer.py

@@ -0,0 +1,314 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+import logging
+import numpy as np
+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 import units
+from FlowCyPy.units import Quantity, milliwatt
+from pint_pandas import PintArray
+from FlowCyPy.acquisition import Acquisition
+from FlowCyPy.signal_digitizer import SignalDigitizer
+
+
+# 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,
+            scatterer_collection: object,
+            flow_cell: FlowCell,
+            signal_digitizer: SignalDigitizer,
+            detectors: List[Detector],
+            coupling_mechanism: Optional[str] = 'mie',
+            background_power: Optional[Quantity] = 0 * milliwatt):
+
+        self.scatterer_collection = scatterer_collection
+        self.flow_cell = flow_cell
+        self.source = flow_cell.source
+        self.detectors = detectors
+        self.signal_digitizer = signal_digitizer
+        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'
+
+        for detector in detectors:
+            detector.cytometer = self
+
+    def run_coupling_analysis(self, scatterer_dataframe: pd.DataFrame) -> 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_dataframe=scatterer_dataframe,
+                medium_refractive_index=self.scatterer_collection.medium_refractive_index
+            )
+
+            scatterer_dataframe[detector.name] = pint_pandas.PintArray(self.coupling_power, dtype=self.coupling_power.units)
+
+    def _generate_pulse_parameters(self, scatterer_dataframe: pd.DataFrame) -> 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'] = scatterer_dataframe['Time']
+
+        widths = self.source.waist / self.flow_cell.flow_speed * np.ones(len(scatterer_dataframe))
+
+        scatterer_dataframe['Widths'] = pint_pandas.PintArray(widths, dtype=widths.units)
+
+    def initialize_signal(self, run_time: Quantity) -> 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.
+
+        """
+        dataframes = []
+
+        # Initialize the detectors
+        for detector in self.detectors:
+            dataframe = detector.get_initialized_signal(run_time=run_time, signal_digitizer=self.signal_digitizer)
+
+            dataframes.append(dataframe)
+
+        self.dataframe = pd.concat(dataframes, keys=[d.name for d in self.detectors])
+
+        self.dataframe.index.names = ["Detector", "Index"]
+
+    def get_acquisition(self, run_time: Quantity) -> 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').
+        """
+        if not run_time.check('second'):
+            raise ValueError(f"flow_speed must be in meter per second, but got {run_time.units}")
+
+        self.initialize_signal(run_time=run_time)
+
+        scatterer_dataframe = self.flow_cell.generate_event_dataframe(self.scatterer_collection.populations, run_time=run_time)
+
+        self.scatterer_collection.fill_dataframe_with_sampling(scatterer_dataframe)
+
+        self.run_coupling_analysis(scatterer_dataframe)
+
+        self._generate_pulse_parameters(scatterer_dataframe)
+
+        self.scatterer_collection.dataframe = scatterer_dataframe
+
+        _widths = scatterer_dataframe['Widths'].pint.to('second').pint.quantity.magnitude
+        _centers = scatterer_dataframe['Time'].pint.to('second').pint.quantity.magnitude
+
+        for detector in self.detectors:
+            _coupling_power = scatterer_dataframe[detector.name].values
+
+            detector_signal = self.dataframe.xs(detector.name)['Signal']
+
+            # Generate noise components
+            detector._add_thermal_noise_to_raw_signal(signal=detector_signal)
+
+            detector._add_dark_current_noise_to_raw_signal(signal=detector_signal)
+
+            # Broadcast the time array to the shape of (number of signals, len(detector.time))
+            time = self.dataframe.xs(detector.name)['Time'].pint.magnitude
+
+            time_grid = np.expand_dims(time, axis=0) * units.second
+
+            centers = np.expand_dims(_centers, axis=1) * units.second
+            widths = np.expand_dims(_widths, axis=1) * units.second
+
+            # 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(
+                signal=detector_signal,
+                optical_power=total_power,
+                wavelength=self.flow_cell.source.wavelength
+            )
+
+            digitized_signal = detector.capture_signal(signal=detector_signal)
+
+            self.dataframe.loc[detector.name, 'Signal'] = PintArray(detector_signal, detector_signal.pint.units)
+
+            self.dataframe.loc[detector.name, 'DigitizedSignal'] = PintArray(digitized_signal, units.bit_bins)
+
+        experiment = Acquisition(
+            cytometer=self,
+            run_time=run_time,
+            scatterer_dataframe=scatterer_dataframe,
+            detector_dataframe=self.dataframe
+        )
+
+        return experiment
+
+    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 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
+