FlowCyPy 0.7.0__py3-none-any.whl

FlowCyPy/scatterer_collection.py

@@ -0,0 +1,306 @@
+from typing import List, Optional, Union
+from MPSPlots.styles import mps
+import pandas as pd
+from FlowCyPy.units import Quantity, RIU, particle, liter
+from FlowCyPy.population import Population
+from FlowCyPy.utils import PropertiesReport
+import matplotlib.patches as mpatches
+from typing import Optional, List
+from pint_pandas import PintArray
+import seaborn as sns
+import matplotlib.pyplot as plt
+import numpy as np
+from matplotlib.colors import LinearSegmentedColormap
+from enum import Enum
+from FlowCyPy import units
+
+
+class CouplingModel(Enum):
+    MIE = 'mie'
+    RAYLEIGH = 'rayleigh'
+    UNIFORM = 'uniform'
+
+
+class ScattererCollection(PropertiesReport):
+    """
+    Defines and manages the size and refractive index distributions of scatterers (particles)
+    passing through a flow cytometer. This class generates random scatterer sizes and refractive
+    indices based on a list of provided distributions (e.g., Normal, LogNormal, Uniform, etc.).
+
+    """
+    def __init__(self, medium_refractive_index: Quantity = 1.0 * RIU, populations: List[Population] = None, coupling_model: Optional[CouplingModel] = CouplingModel.MIE):
+        """
+        Parameters
+        ----------
+        populations : List[Population]
+            A list of Population instances that define different scatterer populations.
+        coupling_model : Optional[CouplingModel], optional
+            The type of coupling factor to use (CouplingModel.MIE, CouplingModel.RAYLEIGH, CouplingModel.UNIFORM). Default is CouplingModel.MIE.
+        medium_refractive_index : float
+            The refractive index of the medium. Default is 1.0.
+        """
+        self.populations = populations or []
+        self.medium_refractive_index = medium_refractive_index
+        self.coupling_model = coupling_model
+        self.dataframe: pd.DataFrame = None
+
+    def get_population_ratios(self) -> list[float]:
+        total_concentration = sum([p.particle_count.value for p in self.populations])
+
+        return [(p.particle_count.value / total_concentration).magnitude for p in self.populations]
+
+    def get_population_dataframe(self, total_sampling: Optional[Quantity]) -> pd.DataFrame:
+        """
+        Generate a DataFrame by sampling particles from populations.
+
+        Parameters
+        ----------
+        total_sampling : Quantity, optional
+            Total number of samples to draw, distributed across populations based on their ratios.
+
+        Returns
+        -------
+        pd.DataFrame
+            A MultiIndex DataFrame containing the sampled data from all populations. The first
+            index level indicates the population name, and the second level indexes the sampled data.
+        """
+        ratios = self.get_population_ratios()
+
+        sampling_list = [int(ratio * total_sampling.magnitude) for ratio in ratios]
+
+        population_names = [p.name for p in self.populations]
+
+        # Create tuples for the MultiIndex
+        multi_index_tuples = [
+            (pop_name, idx) for pop_name, n in zip(population_names, sampling_list) for idx in range(n)
+        ]
+
+        # Create the MultiIndex
+        multi_index = pd.MultiIndex.from_tuples(multi_index_tuples, names=["Population", "Index"])
+
+        # Initialize an empty DataFrame with the MultiIndex
+        scatterer_dataframe = pd.DataFrame(index=multi_index)
+
+        self.fill_dataframe_with_sampling(scatterer_dataframe=scatterer_dataframe)
+
+        return scatterer_dataframe
+
+    def add_population(self, *population: Population) -> 'ScattererCollection':
+        """
+        Adds a population to the ScattererCollection instance with the specified attributes.
+
+        Parameters
+        ----------
+        name : str
+            The name of the population.
+        size : BaseDistribution
+            The size distribution of the population.
+        refractive_index : BaseDistribution
+            The refractive index distribution of the population.
+
+        Returns
+        -------
+        ScattererCollection
+            The ScattererCollection instance (to support chaining).
+
+        Raises
+        ------
+        ValueError
+            If the concentration does not have the expected dimensionality.
+        """
+        self.populations.extend(population)
+        return population
+
+    @property
+    def concentrations(self) -> List[Quantity]:
+        """
+        Gets the concentration of each population in the ScattererCollection instance.
+
+        Returns
+        -------
+        List[Quantity]
+            A list of concentrations for each population.
+        """
+        return [population.concentration for population in self.populations]
+
+    @concentrations.setter
+    def concentrations(self, values: Union[List[Quantity], Quantity]) -> None:
+        """
+        Sets the concentration of each population in the ScattererCollection instance.
+
+        Parameters
+        ----------
+        values : Union[List[Quantity], Quantity]
+            A list of concentrations to set for each population, or a single concentration value to set for all populations.
+
+        Raises
+        ------
+        ValueError
+            If the length of the values list does not match the number of populations or if any concentration has an incorrect dimensionality.
+        """
+        if isinstance(values, (list, tuple)):
+            if len(values) != len(self.populations):
+                raise ValueError("The length of the values list must match the number of populations.")
+
+            for value in values:
+                if value.dimensionality != (particle / liter).dimensionality:
+                    raise ValueError(
+                        f"Invalid concentration dimensionality: {value.dimensionality}. Expected dimensionality is 'particles per liter' or similar."
+                    )
+
+            for population, value in zip(self.populations, values):
+                population.concentration = value
+        else:
+            if values.dimensionality != (particle / liter).dimensionality:
+                raise ValueError(
+                    f"Invalid concentration dimensionality: {values.dimensionality}. Expected dimensionality is 'particles per liter' or similar."
+                )
+            for population in self.populations:
+                population.concentration = values
+
+    def dilute(self, factor: float) -> None:
+        """
+        Dilutes the populations in the flow cytometry system by a given factor.
+
+        Parameters
+        ----------
+        factor : float
+            The dilution factor to apply to each population. For example, a factor
+            of 0.5 reduces the population density by half.
+
+        Returns
+        -------
+        None
+            The method modifies the populations in place.
+
+        Notes
+        -----
+
+            - This method iterates over all populations in the system and applies the `dilute` method of each population.
+            - The specific implementation of how a population is diluted depends on the `dilute` method defined in the `population` object.
+
+        Examples
+        --------
+        Dilute all populations by 50%:
+        >>> system.dilute(0.5)
+        """
+        for population in self.populations:
+            population.dilute(factor)
+
+    def fill_dataframe_with_sampling(self, scatterer_dataframe: pd.DataFrame) -> None:
+        """
+        Fills a DataFrame with size and refractive index sampling data for each population.
+
+        Parameters
+        ----------
+        scatterer_dataframe : pd.DataFrame
+            A DataFrame indexed by population names (first level) and containing the
+            following columns: `'Size'`: To be filled with particle size data. `'RefractiveIndex'`:
+            To be filled with refractive index data. The DataFrame must already have the required structure.
+
+        Returns
+        -------
+        None
+            The method modifies the `scatterer_dataframe` in place, adding size and
+            refractive index sampling data.
+
+        After filling, the DataFrame will be populated with size and refractive index data.
+        """
+        for population in self.populations:
+            # Check if population.name is in the dataframe's index
+            if population.name not in scatterer_dataframe.index:
+                continue  # Skip this iteration if population.name is not present
+
+            # Safely access the sub-dataframe and proceed
+            sub_dataframe = scatterer_dataframe.xs(population.name)
+            sampling = len(sub_dataframe) * units.particle
+
+            size, ri = population.generate_sampling(sampling)
+
+            scatterer_dataframe.loc[population.name, 'Size'] = PintArray(size, dtype=size.units)
+            scatterer_dataframe.loc[population.name, 'RefractiveIndex'] = PintArray(ri, dtype=ri.units)
+
+    def plot(self, n_points: int = 200) -> None:
+        """
+        Visualizes the joint and marginal distributions of size and refractive index
+        for multiple populations in the scatterer collection.
+
+        This method creates a joint plot using `sns.JointGrid`, where:
+
+            - The joint area displays filled contours representing the PDF values of size and refractive index.
+            - The marginal areas display the size and refractive index PDFs as filled plots.
+
+        Each population is plotted with a distinct color using a transparent colormap for the joint area.
+
+        Parameters
+        ----------
+        n_points : int, optional
+            The number of points used to compute the size and refractive index PDFs. Default is 100.
+            Increasing this value results in smoother distributions but increases computation time.
+
+        Notes
+        -----
+
+            - The joint area uses a transparent colormap, transitioning from fully transparent to fully opaque for better visualization of overlapping populations.
+            - Marginal plots show semi-transparent filled curves for clarity.
+
+        Example
+        -------
+        >>> scatterer_collection.plot(n_points=200)
+
+        """
+        def create_transparent_colormap(base_color):
+            """
+            Create a colormap that transitions from transparent to a specified base color.
+            """
+            return LinearSegmentedColormap.from_list(
+                "transparent_colormap",
+                [(base_color[0], base_color[1], base_color[2], 0),  # Fully transparent
+                (base_color[0], base_color[1], base_color[2], 1)],  # Fully opaque
+                N=256
+            )
+
+        # Create a JointGrid for visualization
+        with plt.style.context(mps):
+            grid = sns.JointGrid()
+
+        # Initialize a list to store legend handles
+        legend_handles = []
+
+        for index, population in enumerate(self.populations):
+            # Get size and refractive index PDFs
+            size, size_pdf = population.size.get_pdf(n_samples=n_points)
+            size_pdf /= size_pdf.max()
+            ri, ri_pdf = population.refractive_index.get_pdf(n_samples=n_points)
+            ri_pdf /= ri_pdf.max()
+
+            # Create a grid of size and ri values
+            X, Y = np.meshgrid(size, ri)
+            Z = np.outer(ri_pdf, size_pdf)  # Compute the PDF values on the grid
+
+            # Create a transparent colormap for this population
+            base_color = sns.color_palette()[index]
+            transparent_cmap = create_transparent_colormap(base_color)
+
+            # Plot the joint area as a filled contour plot
+            grid.ax_joint.contourf(
+                X, Y, Z, levels=10, cmap=transparent_cmap, extend="min"
+            )
+
+            legend_handles.append(mpatches.Patch(color=base_color, label=population.name))
+
+
+            # Plot the marginal distributions
+            grid.ax_marg_x.fill_between(size.magnitude, size_pdf, color=f"C{index}", alpha=0.5)
+            grid.ax_marg_y.fill_betweenx(ri.magnitude, ri_pdf, color=f"C{index}", alpha=0.5)
+
+        # Set axis labels
+        grid.ax_joint.legend(handles=legend_handles, title="Populations")
+
+        grid.ax_joint.set_xlabel(f"Size [{size.units}]")
+        grid.ax_joint.set_ylabel(f"Refractive Index [{ri.units}]")
+
+        plt.tight_layout()
+
+        # Show the plot
+        plt.show()

FlowCyPy/signal_digitizer.py

@@ -0,0 +1,90 @@
+from pydantic.dataclasses import dataclass
+from pydantic import field_validator
+from typing import Union, Tuple
+import logging
+import numpy as np
+from FlowCyPy.units import Quantity, volt
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+@dataclass(config=config_dict)
+class SignalDigitizer:
+    """
+    Handles signal digitization and saturation for a detector.
+
+    Attributes
+    ----------
+    sampling_freq : Quantity
+        The sampling frequency of the detector in hertz.
+    bit_depth : Union[int, str]
+        The number of discretization bins or bit-depth (e.g., '12bit').
+    saturation_levels : Union[str, Tuple[Quantity, Quantity]]
+        A tuple defining the lower and upper bounds for saturation, or 'auto' to set bounds dynamically.
+    """
+    sampling_freq: Quantity
+    bit_depth: Union[int, str] = '10bit'
+    saturation_levels: Union[str, Tuple[Quantity, Quantity], Quantity] = 'auto'
+
+    @property
+    def _bit_depth(self) -> int:
+        return self._process_bit_depth(self.bit_depth)
+
+    @property
+    def bandwidth(self) -> Quantity:
+        """
+        Automatically calculates the bandwidth based on the sampling frequency.
+
+        Returns
+        -------
+        Quantity
+            The bandwidth of the detector, which is half the sampling frequency (Nyquist limit).
+        """
+        return self.sampling_freq / 2
+
+    @staticmethod
+    def _process_bit_depth(bit_depth: Union[int, str]) -> int:
+        """
+        Converts bit-depth to the number of bins.
+
+        Parameters
+        ----------
+        bit_depth : Union[int, str]
+            The bit-depth as an integer or a string (e.g., '10bit').
+
+        Returns
+        -------
+        int
+            The number of bins corresponding to the bit-depth.
+        """
+        if isinstance(bit_depth, str):
+            bit_depth = int(bit_depth.rstrip('bit'))
+            bit_depth = 2 ** bit_depth
+
+        return bit_depth
+
+    @field_validator('sampling_freq')
+    def _validate_sampling_freq(cls, value):
+        """
+        Validates that the sampling frequency is provided in hertz.
+
+        Parameters
+        ----------
+        value : Quantity
+            The sampling frequency to validate.
+
+        Returns
+        -------
+        Quantity
+            The validated sampling frequency.
+
+        Raises:
+            ValueError: If the sampling frequency is not in hertz.
+        """
+        if not value.check('Hz'):
+            raise ValueError(f"sampling_freq must be in hertz, but got {value.units}")
+        return value

FlowCyPy/source.py

@@ -0,0 +1,249 @@
+
+from typing import Optional
+from pydantic.dataclasses import dataclass
+from pydantic import field_validator
+from FlowCyPy.units import meter, joule, particle, degree, volt, AU
+from PyMieSim.units import Quantity
+from FlowCyPy.utils import PropertiesReport
+from FlowCyPy.physical_constant import PhysicalConstant
+import numpy as np
+
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+class BaseBeam(PropertiesReport):
+    """
+    Mixin class providing unit validation for quantities used in optical sources.
+    """
+
+    def initialization(self):
+        """
+        Initialize beam waists based on the numerical apertures and calculate electric field amplitude at the focus.
+        """
+        self.frequency = PhysicalConstant.c / self.wavelength
+        self.photon_energy = (PhysicalConstant.h * self.frequency).to(joule) / particle
+
+        # Calculate amplitude at focus
+        self.amplitude = self.calculate_field_amplitude_at_focus()
+
+    def calculate_field_amplitude_at_focus(self) -> Quantity:
+        return NotImplementedError('This method should be implemneted by the derived class!')
+
+    @field_validator('wavelength', mode='plain')
+    def validate_wavelength(cls, value, field):
+        if not isinstance(value, Quantity):
+            raise ValueError(f"{value} must be a Quantity with distance units [<prefix>meter].")
+
+        if not value.check('meter'):
+            raise ValueError(f"{field} must be a Quantity with distance units [<prefix>meter], but got {value.units}.")
+
+        return value
+
+    @field_validator('polarization', mode='plain')
+    def validate_polarization(cls, value, field):
+        if not isinstance(value, Quantity):
+            raise ValueError(f"{value} must be a Quantity with angle units [<prefix>degree or <prefix>radian].")
+
+        if not value.check('degree'):
+            raise ValueError(f"{field} must be a Quantity with angle units [<prefix>degree or <prefix>radian], but got {value.units}.")
+
+        return value
+
+    @field_validator('optical_power', mode='plain')
+    def validate_optical_power(cls, value, field):
+        if not isinstance(value, Quantity):
+            raise ValueError(f"{value} must be a Quantity with power units [<prefix>watt].")
+
+        if not value.check('watt'):
+            raise ValueError(f"{field} must be a Quantity with power units [<prefix>watt], but got {value.units}.")
+
+        return value
+
+    @field_validator('numerical_aperture', 'numerical_aperture_x', 'numerical_aperture_y', mode='plain')
+    def validate_numerical_apertures(cls, value, field):
+        if not isinstance(value, Quantity):
+            raise ValueError(f"{value} must be a Quantity with arbitrary units [AU].")
+
+        if not value.check(AU):
+            raise ValueError(f"{field} must be a Quantity with arbitrary units [AU], but got {value.units}.")
+
+        if value.magnitude < 0 or value.magnitude > 1:
+            raise ValueError(f"{field} must be between 0 and 1, but got {value.magnitude}")
+        return value
+
+
+@dataclass(config=config_dict)
+class GaussianBeam(BaseBeam):
+    """
+    Represents a monochromatic Gaussian laser beam focused by a standard lens.
+
+    Parameters
+    ----------
+    optical_power : Quantity
+        The optical power of the laser (in watts).
+    wavelength : Quantity
+        The wavelength of the laser (in meters).
+    numerical_aperture : Quantity
+        The numerical aperture (NA) of the lens focusing the Gaussian beam (unitless).
+    polarization : Optional[Quantity]
+        The polarization of the laser source in degrees (default is 0 degrees).
+    RIN : Optional[float], optional
+        The Relative Intensity Noise (RIN) of the laser, specified as dB/Hz. Default is -120.0 dB/Hz, representing a pretty stable laser.
+
+    Attributes
+    ----------
+    waist : Quantity
+        The beam waist at the focus, calculated as `waist = wavelength / (pi * numerical_aperture)`.
+    frequency : Quantity
+        The frequency of the laser, calculated as `frequency = c / wavelength`.
+    photon_energy : Quantity
+        The energy of a single photon, calculated as `photon_energy = h * frequency`.
+    amplitude : Quantity
+        The electric field amplitude at the focus, derived from optical power, waist, and fundamental constants.
+
+    Notes
+    -----
+    RIN Interpretation:
+        - The Relative Intensity Noise (RIN) represents fluctuations in the laser's intensity relative to its mean optical power.
+        - For a Gaussian beam, the instantaneous intensity at any given time can be modeled as: I(t) = <I> * (1 + ΔI)
+
+    where:
+        - `<I>` is the mean intensity derived from the optical power.
+        - `ΔI` is the noise component, modeled as a Gaussian random variable with:
+            - Mean = 0 (fluctuations are around the mean intensity).
+            - Variance = RIN * <I>².
+
+    """
+    optical_power: Quantity
+    wavelength: Quantity
+    numerical_aperture: Quantity
+    polarization: Optional[Quantity] = 0 * degree
+    RIN: Optional[float] = -120.0
+
+    def __post_init__(self):
+        """
+        Initialize additional parameters like beam waist, frequency, photon energy,
+        and electric field amplitude at the focus.
+        """
+        self.initialization()
+
+    def calculate_field_amplitude_at_focus(self) -> Quantity:
+        r"""
+        Calculate the electric field amplitude (E0) at the focus for a Gaussian beam.
+
+        The electric field amplitude at the focus is given by:
+
+        .. math::
+            E_0 = \sqrt{\frac{2 P}{\pi \epsilon_0 c w_0^2}}
+
+        where:
+            - `P` is the optical power of the beam,
+            - `epsilon_0` is the permittivity of free space,
+            - `c` is the speed of light,
+            - `w_0` is the beam waist at the focus.
+
+        Returns
+        -------
+        Quantity
+            The electric field amplitude at the focus in volts per meter.
+        """
+        self.waist = self.wavelength / (PhysicalConstant.pi * self.numerical_aperture)
+
+        E0 = np.sqrt(2 * self.optical_power / (PhysicalConstant.pi * PhysicalConstant.epsilon_0 * PhysicalConstant.c * self.waist**2))
+
+        return E0.to(volt / meter)
+
+
+@dataclass(config=config_dict)
+class AstigmaticGaussianBeam(BaseBeam):
+    """
+    Represents an astigmatic Gaussian laser beam focused by a cylindrical lens system.
+
+    Parameters
+    ----------
+    optical_power : Quantity
+        The optical power of the laser (in watts).
+    wavelength : Quantity
+        The wavelength of the laser (in meters).
+    numerical_aperture_x : Quantity
+        The numerical aperture of the lens along the x-axis (unitless).
+    numerical_aperture_y : Quantity
+        The numerical aperture of the lens along the y-axis (unitless).
+    polarization : Optional[Quantity]
+        The polarization of the laser source in degrees (default is 0 degrees).
+    RIN : Optional[float], optional
+        The Relative Intensity Noise (RIN) of the laser, specified as a fractional value (e.g., 0.01 for 1% RIN).
+        Default is 0.0, representing a perfectly stable laser.
+
+    Attributes
+    ----------
+    waist_x : Quantity
+        The beam waist at the focus along the x-axis, calculated as `waist_x = wavelength / (pi * numerical_aperture_x)`.
+    waist_y : Quantity
+        The beam waist at the focus along the y-axis, calculated as `waist_y = wavelength / (pi * numerical_aperture_y)`.
+    amplitude : Quantity
+        The electric field amplitude at the focus, derived from optical power, waist_x, waist_y, and fundamental constants.
+
+    Notes
+    -----
+    RIN Interpretation:
+        - The Relative Intensity Noise (RIN) represents fluctuations in the laser's intensity relative to its mean optical power.
+        - For a Gaussian beam, the instantaneous intensity at any given time can be modeled as:
+
+        I(t) = <I> * (1 + ΔI)
+
+    where:
+        - `<I>` is the mean intensity derived from the optical power.
+        - `ΔI` is the noise component, modeled as a Gaussian random variable with:
+            - Mean = 0 (fluctuations are around the mean intensity).
+            - Variance = RIN * <I>².
+
+    """
+    optical_power: Quantity
+    wavelength: Quantity
+    numerical_aperture_x: Quantity
+    numerical_aperture_y: Quantity
+    polarization: Optional[Quantity] = 0 * degree
+    RIN: Optional[float] = 0.0
+
+    def __post_init__(self):
+        """
+        Initialize additional parameters like beam waist, frequency, photon energy,
+        and electric field amplitude at the focus.
+        """
+        self.initialization()
+
+    def calculate_field_amplitude_at_focus(self) -> Quantity:
+        """
+        Calculate the electric field amplitude (E0) at the focus for an astigmatic Gaussian beam.
+
+        The electric field amplitude at the focus is given by:
+
+        .. math::
+            E_0 = \\sqrt{\\frac{2 P}{\\pi \\epsilon_0 c w_{0x} w_{0y}}}
+
+        where:
+            - `P` is the optical power of the beam,
+            - `epsilon_0` is the permittivity of free space,
+            - `c` is the speed of light,
+            - `w_{0x}` is the beam waist at the focus along the x-axis,
+            - `w_{0y}` is the beam waist at the focus along the y-axis.
+
+        Returns
+        -------
+        Quantity
+            The electric field amplitude at the focus in volts per meter.
+        """
+        # Calculate waists based on numerical apertures
+        self.waist_x = (self.wavelength / (PhysicalConstant.pi * self.numerical_aperture_x))
+        self.waist_y = (self.wavelength / (PhysicalConstant.pi * self.numerical_aperture_y))
+
+        E0 = np.sqrt(2 * self.optical_power / (PhysicalConstant.pi * PhysicalConstant.epsilon_0 * PhysicalConstant.c * self.waist_x * self.waist_y))
+
+        return E0.to(volt / meter)

FlowCyPy/units.py

@@ -0,0 +1,30 @@
+# Initialize a unit registry
+from PyMieSim.units import ureg, Quantity # noqa F401
+from PyMieSim.units import *  # noqa F401
+
+_scaled_units_str_list = [
+    'watt', 'volt', 'meter', 'second', 'liter', 'hertz', 'ohm', 'ampere'
+]
+
+for _units_str in _scaled_units_str_list:
+    for scale in ['nano', 'micro', 'milli', '', 'kilo', 'mega']:
+        _unit = scale + _units_str
+        globals()[_unit] = getattr(ureg, _unit)
+
+
+joule = ureg.joule
+coulomb = ureg.coulomb
+power = ureg.watt.dimensionality
+kelvin = ureg.kelvin
+celsius = ureg.celsius
+particle = ureg.particle
+degree = ureg.degree
+distance = ureg.meter.dimensionality
+time = ureg.second.dimensionality
+volume = ureg.liter.dimensionality
+frequency = ureg.hertz.dimensionality
+dB = ureg.dB
+
+# Define a custom unit 'bit_bins'
+ureg.define("bit_bins = [detector_resolution]")
+bit_bins = ureg.bit_bins