FlowCyPy 0.7.0__py3-none-any.whl

FlowCyPy/plottings.py

@@ -0,0 +1,269 @@
+from typing import Optional, Union, Tuple
+from MPSPlots.styles import mps
+import matplotlib.pyplot as plt
+import seaborn as sns
+import pandas as pd
+import numpy as np
+
+
+class MetricPlotter:
+    """
+    A class for creating 2D density and scatter plots of scattering intensities from two detectors.
+
+    Parameters
+    ----------
+    coincidence_dataframe : pd.DataFrame
+        The dataframe containing the coincidence data, including detector and feature columns.
+    detector_names : tuple of str
+        A tuple containing the names of the two detectors (detector 0 and detector 1).
+    """
+
+    def __init__(self, coincidence_dataframe: pd.DataFrame, detector_names: Tuple[str, str]):
+        self.coincidence_dataframe = coincidence_dataframe.reset_index()
+        self.detector_names = detector_names
+
+    def _extract_feature_data(self, feature: str):
+        """
+        Extracts and processes the feature data for the two detectors.
+
+        Parameters
+        ----------
+        feature : str
+            The feature to extract.
+
+        Returns
+        -------
+        Tuple[pd.Series, pd.Series, str, str]
+            Processed x_data, y_data, x_units, and y_units.
+        """
+        name_0, name_1 = self.detector_names
+        x_data = self.coincidence_dataframe[(name_0, feature)]
+        y_data = self.coincidence_dataframe[(name_1, feature)]
+
+        x_units = x_data.max().to_compact().units
+        y_units = y_data.max().to_compact().units
+
+        x_data = x_data.pint.to(x_units)
+        y_data = y_data.pint.to(y_units)
+
+        return x_data, y_data, x_units, y_units
+
+    def _create_density_plot(
+        self,
+        x_data: pd.Series,
+        y_data: pd.Series,
+        bandwidth_adjust: float,
+    ):
+        """
+        Creates a KDE density plot.
+
+        Parameters
+        ----------
+        x_data : pd.Series
+            The x-axis data.
+        y_data : pd.Series
+            The y-axis data.
+        bandwidth_adjust : float
+            Adjustment factor for the KDE bandwidth.
+
+        Returns
+        -------
+        sns.JointGrid
+            The seaborn JointGrid object.
+        """
+        return sns.jointplot(
+            data=self.coincidence_dataframe,
+            x=x_data,
+            y=y_data,
+            kind="kde",
+            alpha=0.8,
+            fill=True,
+            joint_kws={"alpha": 0.7, "bw_adjust": bandwidth_adjust},
+        )
+
+    def _add_scatterplot(
+        self,
+        g: sns.JointGrid,
+        x_data: pd.Series,
+        y_data: pd.Series,
+        color_palette: Optional[Union[str, dict]],
+    ):
+        """
+        Adds a scatterplot layer to the KDE density plot.
+
+        Parameters
+        ----------
+        g : sns.JointGrid
+            The seaborn JointGrid object to which the scatterplot is added.
+        x_data : pd.Series
+            The x-axis data.
+        y_data : pd.Series
+            The y-axis data.
+        color_palette : str or dict, optional
+            The color palette to use for the hue in the scatterplot.
+
+        Returns
+        -------
+        None
+        """
+        sns.scatterplot(
+            data=self.coincidence_dataframe,
+            x=x_data,
+            y=y_data,
+            hue="Label",
+            palette=color_palette,
+            ax=g.ax_joint,
+            alpha=0.6,
+            zorder=1,
+        )
+
+    def _apply_axis_labels(
+        self,
+        g: sns.JointGrid,
+        feature: str,
+        x_units: str,
+        y_units: str) -> None:
+        """
+        Sets the x and y labels with units on the plot.
+
+        Parameters
+        ----------
+        g : sns.JointGrid
+            The seaborn JointGrid object.
+        feature : str
+            The feature being plotted.
+        x_units : str
+            Units of the x-axis data.
+        y_units : str
+            Units of the y-axis data.
+
+        Returns
+        -------
+        None
+        """
+        name_0, name_1 = self.detector_names
+        g.ax_joint.set_xlabel(f"{feature} : {name_0} [{x_units:P}]")
+        g.ax_joint.set_ylabel(f"{feature}: {name_1} [{y_units:P}]")
+
+    def _apply_axis_limits(
+        self,
+        g: sns.JointGrid,
+        x_limits: Optional[Tuple],
+        y_limits: Optional[Tuple],
+        x_units: str,
+        y_units: str):
+        """
+        Sets the axis limits if specified.
+
+        Parameters
+        ----------
+        g : sns.JointGrid
+            The seaborn JointGrid object.
+        x_limits : tuple, optional
+            The x-axis limits (min, max), by default None.
+        y_limits : tuple, optional
+            The y-axis limits (min, max), by default None.
+        x_units : str
+            Units of the x-axis data.
+        y_units : str
+            Units of the y-axis data.
+
+        Returns
+        -------
+        None
+        """
+        if x_limits:
+            x0, x1 = x_limits
+            x0 = x0.to(x_units).magnitude
+            x1 = x1.to(x_units).magnitude
+            g.ax_joint.set_xlim(x0, x1)
+
+        if y_limits:
+            y0, y1 = y_limits
+            y0 = y0.to(y_units).magnitude
+            y1 = y1.to(y_units).magnitude
+            g.ax_joint.set_ylim(y0, y1)
+
+    def plot(
+        self,
+        feature: str,
+        show: bool = True,
+        log_plot: bool = True,
+        x_limits: Optional[Tuple] = None,
+        y_limits: Optional[Tuple] = None,
+        equal_axes: bool = False,
+        bandwidth_adjust: float = 1.0,
+        color_palette: Optional[Union[str, dict]] = 'tab10') -> None:
+        """
+        Generates a 2D density plot of the scattering intensities, overlaid with individual peak heights.
+
+        Parameters
+        ----------
+        feature : str
+            The feature to plot (e.g., 'intensity').
+        show : bool, optional
+            Whether to display the plot immediately, by default True.
+        log_plot : bool, optional
+            Whether to use logarithmic scaling for the plot axes, by default True.
+        x_limits : tuple, optional
+            The x-axis limits (min, max), by default None.
+        y_limits : tuple, optional
+            The y-axis limits (min, max), by default None.
+        equal_axes : bool, optional
+            Whether to enforce the same range for the x and y axes, by default False.
+        bandwidth_adjust : float, optional
+            Bandwidth adjustment factor for the kernel density estimate of the marginal distributions. Default is 1.0.
+        color_palette : str or dict, optional
+            The color palette to use for the hue in the scatterplot.
+
+        Returns
+        -------
+        None
+        """
+        x_data, y_data, x_units, y_units = self._extract_feature_data(feature)
+
+        # Determine equal axis limits if required
+        if equal_axes:
+            min_x = x_limits[0].to(x_units).magnitude if x_limits else x_data.min()
+            max_x = x_limits[1].to(x_units).magnitude if x_limits else x_data.max()
+            min_y = y_limits[0].to(y_units).magnitude if y_limits else y_data.min()
+            max_y = y_limits[1].to(y_units).magnitude if y_limits else y_data.max()
+
+            # Set common limits
+            min_val = min(min_x, min_y)
+            max_val = max(max_x, max_y)
+            x_limits = (min_val, max_val)
+            y_limits = (min_val, max_val)
+
+        with plt.style.context(mps):
+            if not log_plot:
+                # KDE + Scatterplot for linear plots
+                g = self._create_density_plot(x_data, y_data, bandwidth_adjust)
+                self._add_scatterplot(g, x_data, y_data, color_palette)
+                self._apply_axis_labels(g, feature, x_units, y_units)
+                self._apply_axis_limits(g, x_limits, y_limits, x_units, y_units)
+            else:
+                # Scatterplot only for log-scaled plots
+                fig, ax = plt.subplots()
+                sns.scatterplot(
+                    x=x_data,
+                    y=y_data,
+                    hue=self.coincidence_dataframe["Label"],
+                    palette=color_palette,
+                    alpha=0.6,
+                    ax=ax,
+                )
+                ax.set_xscale("log")
+                ax.set_yscale("log")
+                ax.set_xlabel(f"{feature} : {self.detector_names[0]} [{x_units:P}]")
+                ax.set_ylabel(f"{feature} : {self.detector_names[1]} [{y_units:P}]")
+                if x_limits:
+                    ax.set_xlim([lim.to(x_units).magnitude for lim in x_limits])
+                if y_limits:
+                    ax.set_ylim([lim.to(y_units).magnitude for lim in y_limits])
+                ax.legend()
+
+            plt.tight_layout()
+            if show:
+                plt.show()
+

FlowCyPy/population.py

@@ -0,0 +1,136 @@
+
+from typing import Union
+from FlowCyPy import distribution
+import pandas as pd
+from pydantic.dataclasses import dataclass
+from pydantic import field_validator
+from FlowCyPy import units
+from FlowCyPy.utils import PropertiesReport
+from PyMieSim.units import Quantity, RIU, meter
+from FlowCyPy.particle_count import ParticleCount
+from pint_pandas import PintArray
+
+
+config_dict = dict(
+    arbitrary_types_allowed=True,
+    kw_only=True,
+    slots=True,
+    extra='forbid'
+)
+
+
+@dataclass(config=config_dict)
+class Population(PropertiesReport):
+    """
+    A class representing a population of scatterers in a flow cytometry setup.
+
+    Parameters
+    ----------
+    name : str
+        Name of the population distribution.
+    refractive_index : Union[distribution.Base, Quantity]
+        Refractive index or refractive index distributions.
+    size : Union[distribution.Base, Quantity]
+        Particle size or size distributions.
+    particle_count : ParticleCount
+        Scatterer density in particles per cubic meter, default is 1 particle/m³.
+
+    """
+    name: str
+    refractive_index: Union[distribution.Base, Quantity]
+    size: Union[distribution.Base, Quantity]
+    particle_count: ParticleCount | Quantity
+
+    def __post_init__(self):
+        """
+        Automatically converts all Quantity attributes to their base SI units (i.e., without any prefixes).
+        This strips units like millimeter to meter, kilogram to gram, etc.
+        """
+        self.particle_count = ParticleCount(self.particle_count)
+        # Convert all Quantity attributes to base SI units (without any prefixes)
+        for attr_name, attr_value in vars(self).items():
+            if isinstance(attr_value, Quantity):
+                # Convert the quantity to its base unit (strip prefix)
+                setattr(self, attr_name, attr_value.to_base_units())
+
+    @field_validator('refractive_index')
+    def _validate_refractive_index(cls, value):
+        """
+        Validates that the refractive index is either a Quantity or a valid distribution.Base instance.
+
+        Parameters
+        ----------
+        value : Union[distribution.Base, Quantity]
+            The refractive index to validate.
+
+        Returns
+        -------
+        Union[distribution.Base, Quantity]
+            The validated refractive index.
+
+        Raises
+        ------
+        TypeError
+            If the refractive index is not of type Quantity or distribution.Base.
+        """
+        if isinstance(value, Quantity):
+            assert value.check(RIU), "The refractive index value provided does not have refractive index units [RIU]"
+            return distribution.Delta(position=value)
+
+        if isinstance(value, distribution.Base):
+            return value
+
+        raise TypeError(f"refractive_index must be of type Quantity<RIU or refractive_index_units> or distribution.Base, but got {type(value)}")
+
+    @field_validator('size')
+    def _validate_size(cls, value):
+        """
+        Validates that the size is either a Quantity or a valid distribution.Base instance.
+
+        Parameters
+        ----------
+        value : Union[distribution.Base, Quantity]
+            The size to validate.
+
+        Returns
+        -------
+        Union[distribution.Base, Quantity]
+            The validated size.
+
+        Raises
+        ------
+        TypeError
+            If the size is not of type Quantity or distribution.Base.
+        """
+        if isinstance(value, Quantity):
+            assert value.check(meter), "The size value provided does not have length units [meter]"
+            return distribution.Delta(position=value)
+
+        if isinstance(value, distribution.Base):
+            return value
+
+        raise TypeError(f"suze must be of type Quantity or distribution.Base, but got {type(value)}")
+
+    def dilute(self, factor: float) -> None:
+        self.particle_count /= factor
+
+    def generate_sampling(self, sampling: Quantity) -> tuple:
+        size = self.size.generate(sampling)
+
+        ri = self.refractive_index.generate(sampling)
+
+        return size, ri
+
+    def _get_sampling(self, sampling: int) -> pd.DataFrame:
+        size = self.size.generate(sampling)
+
+        ri = self.refractive_index.generate(sampling)
+
+        dataframe = pd.DataFrame(columns=['Size', 'RefractiveIndex'])
+
+        dataframe['Size'] = PintArray(size, dtype=size.units)
+        dataframe['RefractiveIndex'] = PintArray(ri, dtype=ri.units)
+
+        return dataframe
+
+from FlowCyPy.populations_instances import *  # noqa F403

FlowCyPy/populations_instances.py

@@ -0,0 +1,65 @@
+from FlowCyPy.units import Quantity, nanometer, RIU, micrometer, particle
+from FlowCyPy.population import Population
+from FlowCyPy import distribution
+
+class CallablePopulationMeta(type):
+    def __getattr__(cls, attr):
+        raise AttributeError(f"{cls.__name__} must be called as {cls.__name__}() to access its population instance.")
+
+
+class CallablePopulation(metaclass=CallablePopulationMeta):
+    def __init__(self, name, size_dist, ri_dist):
+        self._name = name
+        self._size_distribution = size_dist
+        self._ri_distribution = ri_dist
+
+    def __call__(self, particle_count: Quantity = 1 * particle):
+        return Population(
+            particle_count=particle_count,
+            name=self._name,
+            size=self._size_distribution,
+            refractive_index=self._ri_distribution,
+        )
+
+
+# Define populations
+_populations = (
+    ('Exosome',          70 * nanometer, 2.0, 1.39 * RIU, 0.02 * RIU),
+    ('MicroVesicle',    400 * nanometer, 1.5, 1.39 * RIU, 0.02 * RIU),
+    ('ApoptoticBodies',  2 * micrometer, 1.2, 1.40 * RIU, 0.03 * RIU),
+    ('HDL',              10 * nanometer, 3.5, 1.33 * RIU, 0.01 * RIU),
+    ('LDL',              20 * nanometer, 3.0, 1.35 * RIU, 0.02 * RIU),
+    ('VLDL',             50 * nanometer, 2.0, 1.445 * RIU, 0.0005 * RIU),
+    ('Platelet',       2000 * nanometer, 2.5, 1.38 * RIU, 0.01 * RIU),
+    ('CellularDebris',   3 * micrometer, 1.0, 1.40 * RIU, 0.03 * RIU),
+)
+
+# Dynamically create population classes
+for (name, size, size_spread, ri, ri_spread) in _populations:
+    size_distribution = distribution.RosinRammler(
+        characteristic_size=size,
+        spread=size_spread
+    )
+
+    ri_distribution = distribution.Normal(
+        mean=ri,
+        std_dev=ri_spread
+    )
+
+    # Create a class dynamically for each population
+    cls = type(name, (CallablePopulation,), {})
+    globals()[name] = cls(name, size_distribution, ri_distribution)
+
+
+# Helper function for microbeads
+def get_microbeads(size: Quantity, refractive_index: Quantity, name: str) -> Population:
+    size_distribution = distribution.Delta(position=size)
+    ri_distribution = distribution.Delta(position=refractive_index)
+
+    microbeads = Population(
+        name=name,
+        size=size_distribution,
+        refractive_index=ri_distribution
+    )
+
+    return microbeads