FlowCyPy 0.5.0__py3-none-any.whl

FlowCyPy/scatterer.py

@@ -0,0 +1,373 @@
+from typing import List, Optional, Union
+import matplotlib.pyplot as plt
+from MPSPlots.styles import mps
+import seaborn as sns
+import pandas as pd
+import numpy
+from FlowCyPy.units import Quantity, RIU, particle, liter
+from FlowCyPy.flow_cell import FlowCell
+from FlowCyPy.population import Population
+from FlowCyPy.utils import PropertiesReport
+from FlowCyPy.distribution import Base as BaseDistribution
+from FlowCyPy.logger import ScattererLogger
+from FlowCyPy.particle_count import ParticleCount
+from enum import Enum
+from pint_pandas import PintType, PintArray
+
+
+class CouplingModel(Enum):
+    MIE = 'mie'
+    RAYLEIGH = 'rayleigh'
+    UNIFORM = 'uniform'
+
+
+class Scatterer(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.flow_cell: FlowCell = None
+        self.n_events: int = None
+        self.dataframe: pd.DataFrame = None
+
+    def initialize(self, flow_cell: FlowCell, size_units: str = 'micrometer') -> None:
+        """
+        Initializes particle size, refractive index, and medium refractive index distributions.
+
+        Parameters
+        ----------
+        flow_cell : FlowCell
+            An instance of the FlowCell class that describes the flow cell being used.
+
+        """
+        self.flow_cell = flow_cell
+
+        for population in self.populations:
+            population.initialize(flow_cell=self.flow_cell)
+            population.dataframe.Size = population.dataframe.Size.pint.to(size_units)
+
+        if len(self.populations) != 0:
+            self.dataframe = pd.concat(
+                [population.dataframe for population in self.populations],
+                axis=0,
+                keys=[population.name for population in self.populations],
+            )
+            self.dataframe.index.names = ['Population', 'Index']
+
+        else:
+            dtypes = {
+                'Time': PintType('second'),            # Time column with seconds unit
+                'Position': PintType('meter'),         # Position column with meters unit
+                'Size': PintType('meter'),        # Size column with micrometers unit
+                'RefractiveIndex': PintType('meter')  # Dimensionless unit for refractive index
+            }
+
+            multi_index = pd.MultiIndex.from_tuples([], names=["Population", "Index"])
+
+            # Create an empty DataFrame with specified column types and a multi-index
+            self.dataframe = pd.DataFrame(
+                {col: pd.Series(dtype=dtype) for col, dtype in dtypes.items()},
+                index=multi_index
+            )
+
+        self.n_events = len(self.dataframe)
+
+    def distribute_time_linearly(self, sequential_population: bool = False) -> None:
+        """
+        Distributes particle arrival times linearly across the total runtime of the flow cell.
+
+        Optionally randomizes the order of times for all populations to simulate non-sequential particle arrivals.
+
+        Parameters
+        ----------
+        sequential_population : bool, optional
+            If `True`, organize the order of arrival times across all populations (default is `False`).
+
+        """
+        # Generate linearly spaced time values across the flow cell runtime
+        linear_spacing = numpy.linspace(0, self.flow_cell.run_time, self.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.dataframe.Time = PintArray(linear_spacing, dtype=self.dataframe.Time.pint.units)
+
+    def plot(self, ax: Optional[plt.Axes] = None, show: bool = True, alpha: float = 0.8, bandwidth_adjust: float = 1, log_plot: bool = False, color_palette: Optional[Union[str, dict]] = None) -> None:
+        """
+        Visualizes the joint distribution of scatterer sizes and refractive indices using a Seaborn jointplot.
+
+        Parameters
+        ----------
+        ax : matplotlib.axes.Axes, optional
+            Existing matplotlib axes to plot on. If `None`, a new figure and axes are created. Default is `None`.
+        show : bool, optional
+            If `True`, displays the plot after creation. Default is `True`.
+        alpha : float, optional
+            Transparency level for the scatter plot points, ranging from 0 (fully transparent) to 1 (fully opaque). Default is 0.8.
+        bandwidth_adjust : float, optional
+            Bandwidth adjustment factor for the kernel density estimate of the marginal distributions. Higher values produce smoother density estimates. Default is 1.
+        log_plot : bool, optional
+            If `True`, applies a logarithmic scale to both axes of the joint plot and their marginal distributions. Default is `False`.
+        color_palette : str or dict, optional
+            The color palette to use for the hue in the scatterplot. Can be a seaborn palette name
+            (e.g., 'viridis', 'coolwarm') or a dictionary mapping hue levels to specific colors. Default is None.
+
+        Returns
+        -------
+        None
+            This function does not return any value. It either displays the plot (if `show=True`) or simply creates it for later use.
+
+        Notes
+        -----
+        This method resets the index of the internal dataframe and extracts units from the 'Size' column.
+        The plot uses the specified matplotlib style (`mps`) for consistent styling.
+
+        """
+        df_reset = self.dataframe.reset_index()
+
+        if len(df_reset.Time) == 1:
+            return
+
+        x_unit = df_reset['Size'].pint.units
+
+        with plt.style.context(mps):
+            g = sns.jointplot(data=df_reset, x='Size', y='RefractiveIndex',
+                hue='Population', palette=color_palette, kind='scatter',
+                alpha=alpha, marginal_kws=dict(bw_adjust=bandwidth_adjust)
+            )
+
+        g.ax_joint.set_xlabel(f"Size [{x_unit}]")
+
+        if log_plot:
+            g.ax_joint.set_xscale('log')
+            g.ax_joint.set_yscale('log')
+            g.ax_marg_x.set_xscale('log')
+            g.ax_marg_y.set_yscale('log')
+
+        plt.tight_layout()
+
+        if show:
+            plt.show()
+
+    def print_properties(self) -> None:
+        """
+        Prints specific properties of the Scatterer instance, such as coupling factor and medium refractive index.
+
+        """
+        min_delta_position = abs(self.dataframe['Time'].diff()).min().to_compact()
+        mean_delta_position = self.dataframe['Time'].diff().mean().to_compact()
+
+        _dict = {
+            'coupling factor': self.coupling_model.value,
+            'medium refractive index': self.medium_refractive_index,
+            'minimum time between events': min_delta_position,
+            'average time between events': mean_delta_position
+        }
+
+        super(Scatterer, self).print_properties(**_dict)
+
+        for population in self.populations:
+            population._log_properties()
+
+    def _log_properties(self) -> None:
+        """
+        Logs key properties of the Scatterer instance in a formatted table, including its name,
+        refractive index, size, concentration, and number of events.
+
+        The results are displayed in a formatted table using `tabulate` for clarity.
+        """
+        # Gather properties
+        logger = ScattererLogger(self)
+
+        logger.log_properties(table_format="fancy_grid")
+
+    def add_population(self, population: Population, particle_count: ParticleCount) -> 'Scatterer':
+        """
+        Adds a population to the Scatterer 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.
+        particle_count : ParticleCount
+            The concentration or number of particle of the population. Must have the dimensionality of 'particles per liter'.
+
+        Returns
+        -------
+        Scatterer
+            The Scatterer instance (to support chaining).
+
+        Raises
+        ------
+        ValueError
+            If the concentration does not have the expected dimensionality.
+        """
+        population.particle_count = ParticleCount(particle_count)
+
+        self.populations.append(population)
+        return population
+
+    def _add_population(self, name: str, size: BaseDistribution, refractive_index: BaseDistribution, concentration: Quantity) -> 'Scatterer':
+        """
+        Adds a population to the Scatterer 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.
+        concentration : Quantity
+            The concentration of the population. Must have the dimensionality of 'particles per liter'.
+
+        Returns
+        -------
+        Scatterer
+            The Scatterer instance (to support chaining).
+
+        Raises
+        ------
+        ValueError
+            If the concentration does not have the expected dimensionality.
+        """
+        if concentration.dimensionality != (particle / liter).dimensionality:
+            raise ValueError(
+                f"Invalid concentration dimensionality: {concentration.dimensionality}. Expected dimensionality is 'particles per liter' or similar."
+            )
+
+        population = Population(
+            name=name,
+            size=size,
+            refractive_index=refractive_index,
+            concentration=concentration
+        )
+
+        self.populations.append(population)
+        return population
+
+    def remove_population(self, name: str) -> 'Scatterer':
+        """
+        Removes a population from the Scatterer instance by name.
+
+        Parameters
+        ----------
+        name : str
+            The name of the population to remove.
+
+        Returns
+        -------
+        Scatterer
+            The Scatterer instance (to support chaining).
+
+        Raises
+        ------
+        ValueError
+            If the population with the specified name does not exist.
+        """
+        population_names = [p.name for p in self.populations]
+        if name not in population_names:
+            raise ValueError(f"Population '{name}' not found in Scatterer.")
+
+        self.populations = [p for p in self.populations if p.name != name]
+        return self
+
+    def add_to_ax(self, *axes) -> None:
+        """
+        Adds vertical lines representing events for each population to the provided axes.
+
+        Parameters
+        ----------
+        *axes : matplotlib.axes.Axes
+            One or more matplotlib axes to which the vertical lines will be added.
+
+        Returns
+        -------
+        None
+        """
+        vlines_color_palette = plt.get_cmap('Set2')
+
+        for index, (population_name, group) in enumerate(self.dataframe.groupby(level=0)):
+            vlines_color = vlines_color_palette(index % 8)
+            x = group['Time']
+            units = x.max().to_compact().units
+            x.pint.values = x.pint.to(units)
+            for ax in axes:
+                ax.vlines(x=x, ymin=0, ymax=1, transform=ax.get_xaxis_transform(), color=vlines_color, lw=2.5, linestyle='--', label=population_name)
+
+            ax.set_xlabel(f'Time [{units}]')
+
+    @property
+    def concentrations(self) -> List[Quantity]:
+        """
+        Gets the concentration of each population in the Scatterer 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 Scatterer 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:
+        for population in self.populations:
+            population.concentration /= factor

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,26 @@
+# 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