FlowCyPy 0.5.0__py3-none-any.whl

FlowCyPy/distribution/base_class.py

@@ -0,0 +1,59 @@
+import numpy as np
+from typing import Optional, Tuple
+import matplotlib.pyplot as plt
+from MPSPlots.styles import mps
+from FlowCyPy.units import particle, Quantity
+
+
+class Base:
+    """
+    Base class for distributions used to define particle sizes in the flow cytometer.
+
+    This class provides a structure for generating random scatterer sizes based on different statistical distributions.
+    Each subclass must implement the `generate` method to generate a distribution of sizes and `get_pdf` to compute the
+    probability density function (PDF) values.
+
+    Parameters
+    ----------
+    scale_factor : float
+        A scaling factor applied to the PDF of the distribution. By default, it is set to 1 (equal weight).
+    """
+
+    scale_factor: Optional[float] = 1.0
+
+    def generate(self, n_samples: int) -> np.ndarray:
+        """Generate a distribution of scatterer sizes."""
+        raise NotImplementedError("Must be implemented by subclasses")
+
+    def get_pdf(self, x: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """Compute the probability density function (PDF) values."""
+        raise NotImplementedError("Must be implemented by subclasses")
+
+    def plot(self, n_samples: int = 4000, bins: int = 50) -> None:
+        """
+        Plots a histogram of the generated particle sizes based on the log-normal distribution.
+
+        Parameters
+        ----------
+        n_samples : int, optional
+            The number of particle sizes to generate for the histogram (default is 1000).
+        bins : int, optional
+            The number of bins in the histogram (default is 50).
+        """
+        samples = self.generate(Quantity(n_samples, particle))
+
+        # Plotting the PDF
+        with plt.style.context(mps):  # Assuming mps is a custom style
+            figure, ax = plt.subplots(1, 1)
+            ax.hist(samples, bins=bins, color='blue', edgecolor='black', alpha=0.7)
+
+            ax.set(
+                title='Distribution',
+                xlabel=f'Distributed parameter [{self._main_units}]',
+                ylabel='Probability Density Function (PDF)'
+            )
+
+            plt.show()
+
+    def __str__(self) -> str:
+        return self.__repr__()

FlowCyPy/distribution/delta.py

@@ -0,0 +1,86 @@
+
+from FlowCyPy.distribution.base_class import Base
+import numpy as np
+from typing import Tuple
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class Delta(Base):
+    r"""
+    Represents a delta-like distribution for particle sizes.
+
+    In a delta distribution, all particle sizes are the same, representing a delta function:
+
+    .. math::
+        f(x) = \delta(x - x_0)
+
+    where:
+    - :math:`x_0` is the singular particle size.
+
+    Parameters
+    ----------
+    position : Quantity
+        The particle size for the delta distribution in meters.
+    scale_factor : float, optional
+        A scaling factor applied to the PDF (not the sizes).
+    """
+
+    position: Quantity
+    _name = 'Delta'
+
+    def __post_init__(self):
+        self._main_units = self.position.units
+
+    def generate(self, n_samples: int) -> np.ndarray:
+        r"""
+        Generates a singular distribution of scatterer sizes.
+
+        All sizes generated will be exactly the same as `position`.
+
+        Parameters
+        ----------
+        n_samples : int
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        np.ndarray
+            An array of identical scatterer sizes in meters.
+        """
+        return np.ones(n_samples.magnitude) * self.position.magnitude * self._main_units
+
+    def get_pdf(self, x: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        r"""
+        Returns the x-values and the scaled PDF values for the singular distribution.
+
+        The PDF is represented as a delta-like function centered at `position`.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            The input x-values (particle sizes) over which to compute the PDF.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding scaled PDF values.
+        """
+        common_units = x.units
+
+        pdf = np.zeros_like(x)
+
+        idx = (np.abs(x.magnitude - self.position.to(common_units).magnitude)).argmin()  # Delta-like function for singular value
+        pdf[idx] = 1.0
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"Delta({self.position:.3f~P})"

FlowCyPy/distribution/lognormal.py

@@ -0,0 +1,94 @@
+from FlowCyPy.distribution.base_class import Base
+import numpy as np
+from typing import Tuple
+from scipy.stats import lognorm
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class LogNormal(Base):
+    r"""
+    Represents a log-normal distribution for particle sizes.
+
+    The log-normal distribution is described by its mean and standard deviation of the logarithm of the values:
+
+    .. math::
+        f(x) = \frac{1}{x \sigma \sqrt{2 \pi}} \exp \left( - \frac{(\ln(x) - \mu)^2}{2 \sigma^2} \right)
+
+    where:
+    - :math:`\mu` is the mean of the natural logarithm of the particle sizes.
+    - :math:`\sigma` is the standard deviation of the logarithm of particle sizes.
+
+    Parameters
+    ----------
+    mean : Quantity
+        The mean particle size in meters.
+    std_dev : Quantity
+        The standard deviation of the logarithm of particle sizes.
+    scale_factor : float, optional
+        A scaling factor applied to the PDF (not the sizes).
+    """
+
+    mean: Quantity
+    std_dev: Quantity
+    _name = 'Log-normal'
+
+    def __post_init__(self):
+        self._main_units = self.mean.units
+
+    def generate(self, n_samples: int) -> Quantity:
+        """
+        Generates a log-normal distribution of scatterer sizes.
+
+        The generated sizes follow a log-normal distribution, where the logarithm of the sizes is normally distributed.
+
+        Parameters
+        ----------
+        n_samples : Quantity
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        Quantity
+            An array of scatterer sizes in meters.
+        """
+        return np.random.lognormal(
+            mean=self.mean.to(self._main_units).magnitude,
+            sigma=self.std_dev.to(self._main_units).magnitude,
+            size=n_samples.magnitude
+        ) * self._main_units
+
+    def get_pdf(self, x: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Returns the x-values and the scaled PDF values for the log-normal distribution.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            The input x-values (particle sizes) over which to compute the PDF.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding scaled PDF values.
+        """
+        common_units = x.units
+
+        pdf = lognorm.pdf(
+            x.to(common_units).magnitude,
+            s=self.std_dev.to(common_units).magnitude,
+            scale=self.mean.to(common_units).magnitude
+        )
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"Log-Normal({self.mean:.3f~P}, {self.std_dev:.3f~P})"

FlowCyPy/distribution/normal.py

@@ -0,0 +1,95 @@
+from FlowCyPy.distribution.base_class import Base
+import numpy as np
+from typing import Tuple
+from scipy.stats import norm
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class Normal(Base):
+    r"""
+    Represents a normal (Gaussian) distribution for particle sizes.
+
+    The normal distribution is described by its mean and standard deviation:
+
+    .. math::
+        f(x) = \frac{1}{\sqrt{2 \pi \sigma^2}} \exp \left( - \frac{(x - \mu)^2}{2 \sigma^2} \right)
+
+    where:
+    - :math:`\mu` is the mean of the distribution (average particle size).
+    - :math:`\sigma` is the standard deviation (width of the distribution).
+    - :math:`x` represents particle sizes.
+
+    Parameters
+    ----------
+    mean : Quantity
+        The mean (average) particle size in meters.
+    std_dev : Quantity
+        The standard deviation of particle sizes in meters.
+    """
+
+    mean: Quantity
+    std_dev: Quantity
+    _name = 'Normal'
+
+    def __post_init__(self):
+        self._main_units = self.mean.units
+
+    def generate(self, n_samples: int) -> np.ndarray:
+        """
+        Generates a normal distribution of scatterer sizes.
+
+        The generated sizes are based on the normal distribution's mean and standard deviation.
+
+        Parameters
+        ----------
+        n_samples : int
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        np.ndarray
+            An array of scatterer sizes in meters.
+        """
+        return np.random.normal(
+            loc=self.mean.to(self._main_units).magnitude,
+            scale=self.std_dev.to(self._main_units).magnitude,
+            size=int(n_samples.magnitude)
+        ) * self._main_units
+
+    def get_pdf(self, x: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Returns the x-values and the scaled PDF values for the normal distribution.
+
+        The `scale_factor` is applied to the PDF, not the generated sizes.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            The input x-values (particle sizes) over which to compute the PDF.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding scaled PDF values.
+        """
+        common_units = x.units
+
+        pdf = norm.pdf(
+            x.magnitude,
+            loc=self.mean.to(common_units).magnitude,
+            scale=self.std_dev.to(common_units).magnitude
+        )
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"Normal({self.mean:.3f~P}, {self.std_dev:.3f~P})"

FlowCyPy/distribution/particle_size_distribution.py

@@ -0,0 +1,110 @@
+from FlowCyPy.distribution.base_class import Base
+import numpy as np
+from typing import Tuple
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class RosinRammler(Base):
+    r"""
+    Represents a Particle Size Distribution using the Rosin-Rammler model.
+
+    The Rosin-Rammler distribution is described by its characteristic size and
+    spread parameter, and is used to model particle sizes in systems such as
+    powders or granular materials.
+
+    The distribution function is given by:
+
+    .. math::
+        F(x) = 1 - \exp \left( - \left( \frac{x}{d} \right)^k \right)
+
+    where:
+        - :math:`x` is the particle size.
+        - :math:`d` is the characteristic particle size.
+        - :math:`k` is the spread parameter.
+
+    Parameters
+    ----------
+    characteristic_size : Quantity
+        The characteristic particle size in meters.
+    spread : float
+        The spread parameter (shape factor).
+    """
+
+    characteristic_size: Quantity
+    spread: float
+    _name = 'Rosin-Rammler'
+
+    def __post_init__(self):
+        self._main_units = self.characteristic_size.units
+
+    def generate(self, n_samples: Quantity) -> Quantity:
+        """
+        Generates a particle size distribution based on the Rosin-Rammler model.
+
+        Parameters
+        ----------
+        n_samples : Quantity
+            The number of particle sizes to generate (dimensionless).
+
+        Returns
+        -------
+        Quantity
+            An array of particle sizes in meters (or other units).
+        """
+        # Validate inputs
+        if not isinstance(n_samples, Quantity) or not n_samples.check("particle"):
+            raise ValueError("n_samples must be a dimensionless Quantity.")
+        if self.spread <= 0:
+            raise ValueError("Spread parameter must be greater than zero.")
+
+        # Convert characteristic size to main units
+        d = self.characteristic_size.to(self._main_units).magnitude
+
+        # Generate uniform random samples in [0, 1)
+        u = np.random.uniform(size=n_samples.magnitude)
+        u = np.clip(u, 1e-10, 1 - 1e-10)  # Avoid numerical issues
+
+        # Apply inverse CDF of Rosin-Rammler distribution
+        sizes = d * (-np.log(1 - u))**(1 / self.spread)
+
+        return sizes * self._main_units
+
+    def get_pdf(self, x: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        r"""
+        Returns the x-values and the scaled PDF values for the particle size distribution.
+
+        The PDF for the Rosin-Rammler distribution is derived from the CDF:
+
+        .. math::
+            f(x) = \frac{k}{d} \left( \frac{x}{d} \right)^{k-1} \exp \left( - \left( \frac{x}{d} \right)^k \right)
+
+        Parameters
+        ----------
+        x : np.ndarray
+            The input x-values (particle sizes) over which to compute the PDF.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding scaled PDF values.
+        """
+        common_units = x.units
+        d = self.characteristic_size.to(common_units).magnitude
+        k = self.spread
+
+        # Rosin-Rammler PDF formula
+        pdf = (k / d) * (x.magnitude / d)**(k - 1) * np.exp(-(x.magnitude / d)**k)
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"RR({self.characteristic_size:.3f~P}, {self.spread:.3f})"

FlowCyPy/distribution/uniform.py

@@ -0,0 +1,96 @@
+from FlowCyPy.distribution.base_class import Base
+import numpy as np
+from typing import Tuple
+from scipy.stats import uniform
+from PyMieSim.units import Quantity
+from pydantic.dataclasses import dataclass
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class Uniform(Base):
+    r"""
+    Represents a uniform distribution for particle sizes.
+
+    The uniform distribution assigns equal probability to all particle sizes within a specified range:
+
+    .. math::
+        f(x) = \frac{1}{b - a} \quad \text{for} \quad a \leq x \leq b
+
+    where:
+    - :math:`a` is the lower bound of the distribution.
+    - :math:`b` is the upper bound of the distribution.
+
+    Parameters
+    ----------
+    lower_bound : float
+        The lower bound for particle sizes in meters.
+    upper_bound : float
+        The upper bound for particle sizes in meters.
+    scale_factor : float, optional
+        A scaling factor applied to the PDF (not the sizes).
+    """
+
+    lower_bound: Quantity
+    upper_bound: Quantity
+    _name = 'Uniform'
+
+    def __post_init__(self):
+        self._main_units = self.lower_bound.units
+
+    def generate(self, n_samples: Quantity) -> Quantity:
+        """
+        Generates a uniform distribution of scatterer sizes.
+
+        The generated sizes are uniformly distributed between the specified `lower_bound` and `upper_bound`.
+
+        Parameters
+        ----------
+        n_samples : Quantity
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        np.ndarray
+            An array of scatterer sizes in meters.
+        """
+        return np.random.uniform(
+            self.lower_bound.to(self._main_units).magnitude,
+            self.upper_bound.to(self._main_units).magnitude,
+            n_samples.magnitude
+        ) * self._main_units
+
+    def get_pdf(self, x: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Returns the x-values and the scaled PDF values for the uniform distribution.
+
+        The `scale_factor` is applied to the PDF, not the generated sizes.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            The input x-values (particle sizes) over which to compute the PDF.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding scaled PDF values.
+        """
+        common_unit = self.lower_bound.units
+
+        pdf = uniform.pdf(
+            x.to(common_unit).magnitude,
+            loc=self.lower_bound.magnitude,
+            scale=self.upper_bound.to(common_unit).magnitude - self.lower_bound.magnitude
+        )
+
+        return x, pdf
+
+    def __repr__(self) -> str:
+        return f"Uniform({self.lower_bound:.3f~P}, {self.upper_bound:.3f~P})"

FlowCyPy/distribution/weibull.py

@@ -0,0 +1,80 @@
+import numpy as np
+from typing import Tuple
+from PyMieSim.units import Quantity
+from FlowCyPy.distribution.base_class import Base
+from pydantic.dataclasses import dataclass
+
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class Weibull(Base):
+    r"""
+    Represents a Weibull distribution for particle sizes.
+
+    The Weibull distribution is commonly used for modeling size distributions in biological systems.
+
+    Parameters
+    ----------
+    shape : Quantity
+        The shape parameter (k), controls the skewness of the distribution.
+    scale : Quantity
+        The scale parameter (λ), controls the spread of the distribution.
+    scale_factor : float, optional
+        A scaling factor applied to the PDF (not the sizes).
+    """
+
+    shape: Quantity
+    scale: Quantity
+    _name = 'Weibull'
+
+    def __post_init__(self):
+        self._main_units = self.shape.units
+
+    def generate(self, n_samples: int) -> np.ndarray:
+        """
+        Generates a Weibull distribution of scatterer sizes.
+
+        Parameters
+        ----------
+        n_samples : int
+            The number of particle sizes to generate.
+
+        Returns
+        -------
+        np.ndarray
+            An array of particle sizes in meters.
+        """
+        common_unit = self.shape.units
+
+        return np.random.weibull(
+            self.shape.to(self._main_units).magnitude,
+            size=n_samples.magnitude
+        ) * common_unit
+
+    def get_pdf(self, x: np.ndarray) -> Tuple[np.ndarray, np.ndarray]:
+        """
+        Returns the x-values and the PDF values for the Weibull distribution.
+
+        Parameters
+        ----------
+        x : np.ndarray
+            The input x-values (particle sizes) over which to compute the PDF.
+
+        Returns
+        -------
+        Tuple[np.ndarray, np.ndarray]
+            The input x-values and the corresponding PDF values.
+        """
+        a = self.shape / self.scale
+        b = (x / self.scale)
+        c = np.exp(-(x / self.scale) ** self.shape)
+        pdf = a * b ** (self.shape - 1) * c
+
+        return x, self.scale_factor * pdf