FlowCyPy 0.5.0__py3-none-any.whl

FlowCyPy/__init__.py

@@ -0,0 +1,15 @@
+try:
+    from ._version import version as __version__  # noqa: F401
+
+except ImportError:
+    __version__ = "0.0.0"
+
+from .units import ureg, watt, meter, second, liter, particle
+from .cytometer import FlowCytometer
+from .event_correlator import EventCorrelator
+from .scatterer import Scatterer, CouplingModel
+from .population import Population
+from .detector import Detector
+from .flow_cell import FlowCell
+from .source import GaussianBeam
+from .noises import NoiseSetting

FlowCyPy/_version.py

@@ -0,0 +1,16 @@
+# file generated by setuptools_scm
+# don't change, don't track in version control
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple, Union
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)

FlowCyPy/classifier.py

@@ -0,0 +1,196 @@
+from sklearn.cluster import KMeans
+from sklearn.cluster import DBSCAN
+import pandas as pd
+from typing import List, Dict, Tuple
+
+
+class BaseClassifier:
+    def filter_dataframe(self, features: list, detectors: list = None) -> object:
+        """
+        Filter the DataFrame based on the selected features and detectors.
+
+        Parameters
+        ----------
+        features : list
+            List of features to use for filtering. Options include 'Heights', 'Widths', 'Areas'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+
+        Returns
+        -------
+        DataFrame
+            A filtered DataFrame containing only the selected detectors and features.
+
+        Raises
+        ------
+        ValueError
+            If no matching features are found for the given detectors and features.
+        """
+        # Determine detectors to use
+        if detectors is None:
+            detectors = self.dataframe.columns.get_level_values(0).unique().tolist()
+
+        # Build the list of selected columns
+        selected_features = [
+            (detector, feature) for detector in detectors for feature in features
+            if (detector, feature) in self.dataframe.columns
+        ]
+
+        if not selected_features:
+            raise ValueError("No matching features found for the given detectors and features.")
+
+        # Return the filtered DataFrame
+        return self.dataframe[selected_features]
+
+
+class KmeansClassifier(BaseClassifier):
+    def __init__(self, dataframe: object) -> None:
+        """
+        Initialize the Classifier.
+
+        Parameters
+        ----------
+        dataframe : DataFrame
+            The input dataframe with multi-index columns.
+        """
+        self.dataframe = dataframe
+        self.dataframe['Label'] = 0  # Initialize labels as 0
+
+
+
+    def run(self, number_of_cluster: int, features: list = ['Heights'], detectors: list = None, random_state: int = 42) -> None:
+        """
+        Run KMeans clustering on the selected features and detectors.
+
+        Parameters
+        ----------
+        number_of_cluster : int
+            Number of clusters for KMeans.
+        features : list
+            List of features to use for clustering. Options include 'Heights', 'Widths', 'Areas'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+        random_state : int, optional
+            Random state for KMeans, by default 42.
+        """
+        # Filter the DataFrame
+        X = self.filter_dataframe(features=features, detectors=detectors)
+
+        # Ensure data is dequantified if it uses Pint quantities
+        if hasattr(X, 'pint'):
+            X = X.pint.dequantify()
+
+        # Run KMeans
+        kmeans = KMeans(n_clusters=number_of_cluster, random_state=random_state)
+        self.dataframe['Label'] = kmeans.fit_predict(X)
+
+class DBScanClassifier(BaseClassifier):
+    def __init__(self, dataframe: object) -> None:
+        """
+        Initialize the DBScanClassifier.
+
+        Parameters
+        ----------
+        dataframe : DataFrame
+            The input dataframe with multi-index columns.
+        """
+        self.dataframe = dataframe
+        self.dataframe['Label'] = -1  # Initialize labels as -1 (noise for DBSCAN)
+
+    def run(self, eps: float = 0.5, min_samples: int = 5, features: list = ['Heights'], detectors: list = None) -> None:
+        """
+        Run DBSCAN clustering on the selected features and detectors.
+
+        Parameters
+        ----------
+        eps : float, optional
+            The maximum distance between two samples for them to be considered as in the same neighborhood, by default 0.5.
+        min_samples : int, optional
+            The number of samples in a neighborhood for a point to be considered a core point, by default 5.
+        features : list
+            List of features to use for clustering. Options include 'Heights', 'Widths', 'Areas'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+        """
+        # Filter the DataFrame
+        X = self.filter_dataframe(features=features, detectors=detectors)
+
+        # Ensure data is dequantified if it uses Pint quantities
+        if hasattr(X, 'pint'):
+            X = X.pint.dequantify()
+
+        # Handle missing values (if necessary)
+        X = X.fillna(0).to_numpy()
+
+        # Run DBSCAN
+        dbscan = DBSCAN(eps=eps, min_samples=min_samples)
+        self.dataframe['Label'] = dbscan.fit_predict(X)
+
+
+class RangeClassifier:
+    """
+    A classifier for assigning population labels based on defined ranges.
+
+    Parameters
+    ----------
+    dataframe : pd.DataFrame
+        The input dataframe with features to classify.
+    feature : str
+        The column name of the feature to classify.
+
+    Attributes
+    ----------
+    dataframe : pd.DataFrame
+        The dataframe with an added 'Label' column.
+    ranges : List[Tuple[float, float, str]]
+        The list of ranges and their associated labels.
+    """
+
+    def __init__(self, dataframe: pd.DataFrame) -> None:
+        """
+        Initialize the classifier.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            The input dataframe with features to classify.
+        feature : str
+            The column name of the feature to classify.
+        """
+        self.dataframe = dataframe
+        self.ranges = []  # To store the ranges and their labels
+
+    def run(self, ranges: Dict[str, Tuple[float, float]]) -> None:
+        """
+        Classify the dataframe by assigning population labels based on specified ranges applied to the index.
+
+        Parameters
+        ----------
+        ranges : dict
+            A dictionary where keys are population names (labels) and values are tuples
+            specifying the (lower, upper) bounds of the range for that population.
+
+        Example
+        -------
+        >>> ranges = {
+        >>>     'Population 0': (0, 100),
+        >>>     'Population 1': (100, 150),
+        >>>     'Population 2': (150, 200)
+        >>> }
+        >>> classifier.run(ranges)
+        """
+        # Create conditions and corresponding labels
+        conditions = []
+        labels = []
+        for label, (lower, upper) in ranges.items():
+            conditions.append((self.dataframe.index >= lower) & (self.dataframe.index < upper))
+            labels.append(label)
+
+        # Use np.select to efficiently apply conditions
+        self.dataframe['Label'] = pd.Series(
+            pd.cut(self.dataframe.index,
+                   bins=[float('-inf')] + [upper for _, (_, upper) in ranges.items()],
+                   labels=list(ranges.keys()),
+                   include_lowest=True),
+            index=self.dataframe.index)
+

FlowCyPy/coupling_mechanism/__init__.py

@@ -0,0 +1,4 @@
+from . import uniform
+from . import rayleigh
+from . import mie
+from . import empirical

FlowCyPy/coupling_mechanism/empirical.py

@@ -0,0 +1,47 @@
+import numpy as np
+from FlowCyPy import Scatterer, 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:
+    """
+    Empirical model for scattering intensity based on particle size, granularity, and detector angle.
+
+    This function models forward scatter (FSC) as proportional to the particle's size squared and
+    side scatter (SSC) as proportional to the granularity and modulated by angular dependence
+    (sin^n(theta)). Granularity is a dimensionless measure of the particle's internal complexity or
+    surface irregularities:
+
+    - A default value of 1.0 is used for moderate granularity (e.g., typical white blood cells).
+    - Granularity values < 1.0 represent smoother particles with less internal complexity (e.g., bacteria).
+    - Granularity values > 1.0 represent particles with higher internal complexity or surface irregularities (e.g., granulocytes).
+
+    Parameters
+    ----------
+    detector : Detector
+        The detector object containing theta_angle (in radians).
+    particle_size : float
+        The size of the particle (in meters).
+    granularity : float, optional
+        A measure of the particle's internal complexity or surface irregularities (dimensionless).
+        Default is 1.0.
+    A : float, optional
+        Empirical scaling factor for angular dependence. Default is 1.5.
+    n : float, optional
+        Power of sine function for angular dependence. Default is 2.0.
+
+    Returns
+    -------
+    float
+        The detected scattering intensity for the given particle and detector.
+    """
+    size_list = scatterer.dataframe['Size'].pint.to(meter).values.numpy_data
+
+    # Forward scatter is proportional to size^2
+    fsc_intensity = size_list**2
+
+    # Side scatter is proportional to granularity and modulated by angular dependence
+    ssc_intensity = granularity * (1 + A * np.sin(np.radians(detector.phi_angle))**n) * np.ones_like(size_list)
+
+    return fsc_intensity * watt if detector.phi_angle < np.radians(10) else ssc_intensity * watt

FlowCyPy/coupling_mechanism/mie.py

@@ -0,0 +1,205 @@
+import numpy as np
+from FlowCyPy import Scatterer, 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: Scatterer, source: PlaneWave) -> PMS_SPHERE:
+    """
+    Initializes the scatterer object for the PyMieSim experiment.
+
+    Parameters
+    ----------
+    scatterer : Scatterer
+        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("Scatterer 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: Scatterer, 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 : Scatterer
+        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/coupling_mechanism/rayleigh.py

@@ -0,0 +1,115 @@
+
+import numpy as np
+from FlowCyPy import Scatterer, Detector
+from FlowCyPy.source import BaseBeam
+from FlowCyPy.units import meter
+
+
+def compute_scattering_cross_section(scatterer: Scatterer, source: BaseBeam, detector: Detector) -> np.ndarray:
+    r"""
+    Computes the Rayleigh scattering cross-section for a spherical particle with angle dependency.
+
+    The Rayleigh scattering cross-section depends on the angle at which the scattered light is observed.
+    The total scattering cross-section is modified by a factor of :math:`\sin^2(\theta)`, where :math:`\theta`
+    is the angle between the direction of the incident light and the scattered light, as observed by the detector.
+
+    The Rayleigh scattering cross-section is given by the formula:
+
+    .. math::
+        \sigma_s(\theta) = \sigma_0 \sin^2(\theta)
+
+    Where:
+        - :math:`\sigma_s(\theta)` is the scattering cross-section at angle :math:`\theta` (in m²),
+        - :math:`\sigma_0 = \frac{8 \pi}{3} \left( \frac{2 \pi}{\lambda} \right)^4 \left( \frac{n^2 - 1}{n^2 + 2} \right)^2 r^6` is the total Rayleigh scattering cross-section (in m²),
+        - :math:`r` is the radius of the particle (in m),
+        - :math:`\lambda` is the wavelength of the incident light (in m),
+        - :math:`n` is the refractive index of the scatterer (dimensionless),
+        - :math:`\theta` is the angle of observation (in radians).
+
+    Parameters
+    ----------
+    scatterer : Scatterer
+        An instance of `Scatterer` 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
+        An instance of `Detector` that contains the angle of observation (`theta_angle` in radians).
+
+    Returns
+    -------
+    np.ndarray
+        The angle-dependent Rayleigh scattering cross-section (in square meters, m²).
+    """
+
+    size_list = scatterer.dataframe['Size'].pint.to(meter).values.numpy_data
+    ri_list = scatterer.dataframe['RefractiveIndex'].values.numpy_data
+
+    # Extract properties
+    wavelength = source.wavelength
+    phi = detector.phi_angle  # Angle of observation in radians
+
+    # Rayleigh scattering cross-section formula components
+    factor_0 = 8 * np.pi / 3
+    factor_1 = (2 * np.pi / wavelength) ** 4
+
+    factor_2 = ((ri_list ** 2 - 1) / (ri_list ** 2 + 2)) ** 2
+
+    # Compute the total Rayleigh scattering cross-section (assuming size in meters)
+    sigma_0 = factor_0 * factor_1 * factor_2 * size_list ** 6
+
+    # Modify by the angular dependency: sin^2(theta)
+    cross_section = sigma_0 * np.sin(phi * np.pi / 180) ** 2
+
+    return cross_section.magnitude * meter**2
+
+
+def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: Scatterer) -> float:
+    r"""
+    Computes the power detected by a detector from a Rayleigh scattering event.
+
+    The power scattered by a particle is proportional to the power density of the incident light
+    and the scattering cross-section of the particle:
+
+    .. math::
+        P_s = I_{\text{incident}} \cdot \sigma_s
+
+    The power detected by the detector depends on the solid angle subtended by the detector
+    and the total solid angle over which the power is scattered (assumed to be \( 4\pi \) steradians):
+
+    .. math::
+        P_{\text{detected}} = P_s \cdot \frac{\Omega}{4 \pi} \cdot \eta
+
+    Where:
+    - :math:`P_{\text{detected}}` is the power detected by the detector (in watts, W).
+    - :math:`\Omega` is the solid angle subtended by the detector (in steradians, sr).
+    - :math:`\eta` is the detector efficiency (dimensionless, between 0 and 1).
+
+    Parameters
+    ----------
+    source : BaseBeam
+        An instance of `BaseBeam` containing the laser properties, including the optical power and numerical aperture.
+    detector : Detector
+        An instance of `Detector` containing the detector properties, including numerical aperture and responsitivity.
+
+    Returns
+    -------
+    float
+        The power detected by the detector (in watts, W).
+    """
+    scattering_cross_section = compute_scattering_cross_section(
+        source=source,
+        scatterer=scatterer,
+        detector=detector
+    )
+
+    # Calculate incident power density at the beam waist
+    incident_power_density = (2 * source.optical_power) / (np.pi * source.waist ** 2)
+
+    # Calculate the scattered power using the scattering cross-section
+    scattered_power = incident_power_density * scattering_cross_section
+
+    # Detector captures a portion of scattered power proportional to its solid angle over 4π steradians
+    solid_angle = detector.numerical_aperture ** 2
+    detected_power = scattered_power * (solid_angle / (4 * np.pi))
+
+    return detected_power

FlowCyPy/coupling_mechanism/uniform.py

@@ -0,0 +1,39 @@
+import numpy as np
+from FlowCyPy import Scatterer, Detector, ureg
+from FlowCyPy.source import BaseBeam
+
+
+def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: Scatterer) -> np.ndarray:
+    r"""
+    Computes the power detected by a detector from a uniform distribution.
+
+    The power scattered by a particle is proportional to the power density of the incident light
+    and the scattering cross-section of the particle:
+
+    .. math::
+        P_s = I_{\text{incident}} \cdot \sigma_s
+
+    The power detected by the detector depends on the solid angle subtended by the detector
+    and the total solid angle over which the power is scattered (assumed to be \( 4\pi \) steradians):
+
+    .. math::
+        P_{\text{detected}} = P_s \cdot \frac{\Omega}{4 \pi} \cdot \eta
+
+    Where:
+    - :math:`P_{\text{detected}}` is the power detected by the detector (in watts, W).
+    - :math:`\Omega` is the solid angle subtended by the detector (in steradians, sr).
+    - :math:`\eta` is the detector efficiency (dimensionless, between 0 and 1).
+
+    Parameters
+    ----------
+    source : BaseBeam
+        An instance of `BaseBeam` containing the laser properties, including the optical power and numerical aperture.
+    detector : Detector
+        An instance of `Detector` containing the detector properties, including numerical aperture and responsitivity.
+
+    Returns
+    -------
+    float
+        The power detected by the detector (in watts, W).
+    """
+    return np.ones(len(scatterer.dataframe)) * ureg.watt