FlowCyPy 0.7.3__tar.gz → 0.7.4__tar.gz

{flowcypy-0.7.3 → flowcypy-0.7.4}/FlowCyPy/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.7.3'
-__version_tuple__ = version_tuple = (0, 7, 3)
+__version__ = version = '0.7.4'
+__version_tuple__ = version_tuple = (0, 7, 4)

{flowcypy-0.7.3 → flowcypy-0.7.4}/FlowCyPy/acquisition.py

@@ -465,21 +465,32 @@ class Acquisition:
         def __init__(self, acquisition: object):
             self.acquisition = acquisition
 
-        def signals(self, figure_size: tuple = (10, 6), show: bool = True) -> None:
+        def signals(
+            self,
+            figure_size: tuple = (10, 6),
+            show: bool = True,
+            show_populations: str | List[str] = None,
+            save_filename: str = None
+        ) -> None:
             """
             Visualizes raw signals for all detector channels and the scatterer distribution.
 
             Parameters
             ----------
             figure_size : tuple, optional
-                Size of the plot (default: (10, 6)).
-            add_peak_locator : bool, optional
-                Adds peak location markers to the signals if True (default: False).
+                Size of the plot in inches (default: (10, 6)).
             show : bool, optional
-                Displays the plot immediately if True (default: True).
+                If True, displays the plot immediately (default: True).
+            show_populations : str or list of str, optional
+                List of population names to highlight in the event plot. If None, shows all populations.
+            save_filename : str, optional
+                If provided, saves the figure to the specified file.
             """
-            n_plots = self.acquisition.n_detectors + 1
+            # Handle `show_populations` default case
+            if show_populations is None:
+                show_populations = self.acquisition.data.scatterer.index.get_level_values('Population').unique()
 
+            n_plots = self.acquisition.n_detectors + 1  # One extra plot for events
             time_units = self.acquisition.data.continuous.Time.max().to_compact().units
 
             with plt.style.context(mps):
@@ -488,52 +499,99 @@ class Acquisition:
                     nrows=n_plots,
                     figsize=figure_size,
                     sharex=True,
-                    height_ratios=[1] * (n_plots - 1) + [0.5],
+                    height_ratios=[1] * (n_plots - 1) + [0.5]
                 )
 
+            # Plot digitized and continuous signals for each detector
             for ax, (detector_name, group) in zip(axes[:-1], self.acquisition.data.continuous.groupby("Detector")):
                 detector = self.get_detector(detector_name)
 
-                ax.step(group["Time"].pint.to(time_units), group["DigitizedSignal"], label="Digitized Signal", where='mid')
+                # Convert time and signal data to the appropriate units
+                time_data = group["Time"].pint.to(time_units)
+                digitized_signal = group["DigitizedSignal"]
+
+                # Plot digitized signal
+                ax.step(time_data, digitized_signal, label="Digitized Signal", where='mid')
                 ax.set_ylabel(detector_name)
                 ax.set_ylim([0, self.acquisition.cytometer.signal_digitizer._bit_depth])
 
+                # Twin axis for continuous signal
                 ax2 = ax.twinx()
-                ax2_x = self.acquisition.data.continuous.loc[detector_name, 'Time']
-                ax2_y = self.acquisition.data.continuous.loc[detector_name, 'Signal']
-                ax2_y_units = ax2_y.max().to_compact().units
-                ax2.plot(
-                    ax2_x.pint.to(time_units),
-                    ax2_y.pint.to(ax2_y_units),
-                    color='black',
-                    linewidth=1,
-                    linestyle='-',
-                    label='Continuous signal',
-                    zorder=0,
-                )
-
-                ax2.set_ylim(detector._saturation_levels if detector._saturation_levels[0] != detector._saturation_levels[1] else None)
+                cont_time, cont_signal, cont_signal_units = self._get_continuous_signal(detector_name, time_units)
+                ax2.plot(cont_time, cont_signal, color='black', linewidth=1, linestyle='-', label='Continuous Signal', zorder=0)
 
-            self._add_event_to_ax(ax=axes[-1], time_units=time_units)
+                # Set y-limits for the continuous signal
+                if detector._saturation_levels[0] != detector._saturation_levels[1]:
+                    ax2.set_ylim(detector._saturation_levels)
 
+            # Add event markers to the last subplot
+            self._add_event_to_ax(ax=axes[-1], time_units=time_units, show_populations=show_populations)
             axes[-1].set_xlabel(f"Time [{time_units}]")
+
+            # Save or show the figure
+            if save_filename:
+                fig.savefig(fname=save_filename)
             if show:
                 plt.show()
 
-        def _add_event_to_ax(self, ax: plt.Axes, time_units: units.Quantity, palette: str = 'tab10') -> None:
+
+        def _get_continuous_signal(self, detector_name: str, time_units: units.Quantity):
+            """
+            Retrieves and converts the continuous signal data for a given detector.
+
+            Parameters
+            ----------
+            detector_name : str
+                Name of the detector.
+            time_units : units.Quantity
+                Desired time units.
+
+            Returns
+            -------
+            tuple
+                (time array, signal array, signal units)
+            """
+            data = self.acquisition.data.continuous.loc[detector_name]
+            cont_time = data['Time'].pint.to(time_units)
+            cont_signal = data['Signal']
+            cont_signal_units = cont_signal.max().to_compact().units
+            return cont_time, cont_signal.pint.to(cont_signal_units), cont_signal_units
+
+        def _add_event_to_ax(
+            self,
+            ax: plt.Axes,
+            time_units: units.Quantity,
+            palette: str = 'tab10',
+            show_populations: str | List[str] = None
+        ) -> None:
+            """
+            Adds vertical markers for event occurrences in the scatterer data.
+
+            Parameters
+            ----------
+            ax : plt.Axes
+                The matplotlib axis to modify.
+            time_units : units.Quantity
+                Time units to use for plotting.
+            palette : str, optional
+                Color palette for different populations (default: 'tab10').
+            show_populations : str or list of str, optional
+                Populations to display. If None, all populations are shown.
+            """
+            # Get unique population names
             unique_populations = self.acquisition.data.scatterer.index.get_level_values('Population').unique()
             color_mapping = dict(zip(unique_populations, sns.color_palette(palette, len(unique_populations))))
 
             for population_name, group in self.acquisition.data.scatterer.groupby('Population'):
+                if show_populations is not None and population_name not in show_populations:
+                    continue
                 x = group.Time.pint.to(time_units)
                 color = color_mapping[population_name]
                 ax.vlines(x, ymin=0, ymax=1, transform=ax.get_xaxis_transform(), label=population_name, color=color)
 
             ax.tick_params(axis='y', left=False, labelleft=False)
-
             ax.get_yaxis().set_visible(False)
             ax.set_xlabel(f"Time [{time_units}]")
-
             ax.legend()
 
         @helper.plot_sns

{flowcypy-0.7.3 → flowcypy-0.7.4}/FlowCyPy/cytometer.py

@@ -13,6 +13,7 @@ from FlowCyPy.flow_cell import FlowCell
 from FlowCyPy.detector import Detector
 from FlowCyPy.acquisition import Acquisition
 from FlowCyPy.signal_digitizer import SignalDigitizer
+from FlowCyPy.helper import validate_units
 
 
 # Set up logging configuration
@@ -87,7 +88,7 @@ class FlowCytometer:
         for detector in detectors:
             detector.cytometer = self
 
-    def run_coupling_analysis(self, scatterer_dataframe: pd.DataFrame) -> None:
+    def _run_coupling_analysis(self, scatterer_dataframe: pd.DataFrame) -> None:
         """
         Computes and assigns the optical coupling power for each particle-detection event.
 
@@ -184,7 +185,7 @@ class FlowCytometer:
 
         scatterer_dataframe['Widths'] = PintArray(widths, dtype=widths.units)
 
-    def initialize_signal(self, run_time: Quantity) -> None:
+    def _initialize_signal(self, run_time: Quantity) -> None:
         """
         Initializes the raw signal for each detector based on the source and flow cell configuration.
 
@@ -209,6 +210,7 @@ class FlowCytometer:
 
         self.dataframe.index.names = ["Detector", "Index"]
 
+    @validate_units(run_time=units.second)
     def get_acquisition(self, run_time: Quantity) -> None:
         """
         Simulates the generation of optical signal pulses for each particle event.
@@ -231,13 +233,13 @@ class FlowCytometer:
         if not run_time.check('second'):
             raise ValueError(f"flow_speed must be in meter per second, but got {run_time.units}")
 
-        self.initialize_signal(run_time=run_time)
+        self._initialize_signal(run_time=run_time)
 
-        scatterer_dataframe = self.flow_cell.generate_event_dataframe(self.scatterer_collection.populations, run_time=run_time)
+        scatterer_dataframe = self.flow_cell._generate_event_dataframe(self.scatterer_collection.populations, run_time=run_time)
 
         self.scatterer_collection.fill_dataframe_with_sampling(scatterer_dataframe)
 
-        self.run_coupling_analysis(scatterer_dataframe)
+        self._run_coupling_analysis(scatterer_dataframe)
 
         self._generate_pulse_parameters(scatterer_dataframe)
 

{flowcypy-0.7.3 → flowcypy-0.7.4}/FlowCyPy/flow_cell.py

@@ -12,6 +12,7 @@ from FlowCyPy.population import Population
 from FlowCyPy.scatterer_collection import ScattererCollection
 from FlowCyPy.units import meter, particle, Quantity
 from FlowCyPy import units
+from FlowCyPy.helper import validate_units
 
 config_dict = dict(
     arbitrary_types_allowed=True,
@@ -21,6 +22,7 @@ config_dict = dict(
 )
 
 
+
 @dataclass(config=config_dict)
 class FlowCell:
     """
@@ -63,12 +65,14 @@ class FlowCell:
             raise ValueError(f"flow_area must be in meter ** 2, but got {value.units}")
         return value
 
+    @validate_units(run_time=units.second)
     def get_volume(self, run_time: Quantity) -> Quantity:
         """
         Computes the volume passing through the flow cell over the given run time.
         """
-        return self.flow_area * self.flow_speed * run_time
+        return (self.volume_flow * run_time).to_compact()
 
+    @validate_units(run_time=units.second)
     def get_population_sampling(self, run_time: Quantity, scatterer_collection: ScattererCollection) -> list[Quantity]:
         """
         Calculates the number of events (or particle counts) for each population based on the run time.
@@ -82,12 +86,11 @@ class FlowCell:
             for p in scatterer_collection.populations
         ]
 
-    def generate_event_dataframe(self, populations: List[Population], run_time: Quantity) -> pd.DataFrame:
+    def _generate_event_dataframe(self, populations: List[Population], run_time: Quantity) -> pd.DataFrame:
         """
         Generates a DataFrame of event times for each population based on the specified scheme.
         """
         # Generate individual DataFrames for each population
-
         population_event_frames = [
             self._generate_poisson_events(population=population, run_time=run_time)
             for population in populations

{flowcypy-0.7.3 → flowcypy-0.7.4}/FlowCyPy/helper.py

@@ -2,6 +2,49 @@ from typing import Callable
 import matplotlib.pyplot as plt
 from MPSPlots.styles import mps
 
+from functools import wraps
+import inspect
+from FlowCyPy.units import Quantity
+
+def validate_units(**expected_units):
+    """
+    Decorator to enforce that function arguments of type Quantity have the correct units.
+
+    Parameters
+    ----------
+    expected_units : dict
+        A dictionary where keys are argument names and values are the expected Pint units.
+
+    Raises
+    ------
+    ValueError
+        If any argument does not have the expected unit.
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Get function signature and argument values
+            sig = inspect.signature(func)
+            bound_args = sig.bind(*args, **kwargs)
+            bound_args.apply_defaults()
+
+            for arg_name, expected_unit in expected_units.items():
+                if arg_name in bound_args.arguments:
+                    value = bound_args.arguments[arg_name]
+
+                    # Check if the value is a Pint Quantity
+                    if not isinstance(value, Quantity):
+                        raise TypeError(f"Argument '{arg_name}' must be a Pint Quantity, but got {type(value)}")
+
+                    # Check if the argument has the expected units
+                    if not value.check(value.units):
+                        raise ValueError(f"Argument '{arg_name}' must have units of {expected_unit}, but got {value.units}")
+
+            return func(*bound_args.args, **bound_args.kwargs)
+
+        return wrapper
+    return decorator
+
 
 def plot_sns(function: Callable) -> Callable:
     """

{flowcypy-0.7.3 → flowcypy-0.7.4}/FlowCyPy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: FlowCyPy
-Version: 0.7.3
+Version: 0.7.4
 Summary: A package for flow-cytometry simulations.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License

{flowcypy-0.7.3 → flowcypy-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: FlowCyPy
-Version: 0.7.3
+Version: 0.7.4
 Summary: A package for flow-cytometry simulations.
 Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
 License: MIT License

flowcypy-0.7.4/developments/scripts/temp.py

@@ -0,0 +1,70 @@
+from FlowCyPy import FlowCytometer, ScattererCollection, Detector, GaussianBeam, FlowCell
+from FlowCyPy import distribution, Population
+from FlowCyPy.signal_digitizer import SignalDigitizer
+from FlowCyPy import units
+
+source = GaussianBeam(
+    numerical_aperture=0.4 * units.AU,     # Numerical aperture: 0.4
+    wavelength=1550 * units.nanometer,     # Wavelength: 1550 nm
+    optical_power=200 * units.milliwatt    # Optical power: 2 mW
+)
+
+flow_cell = FlowCell(
+    source=source,
+    volume_flow=10 * units.microliter / units.second, # Flow speed: 10 microliter per second
+    flow_area=(40 * units.micrometer) ** 2, # Flow area: 40 x 40 micrometers
+)
+
+LP_concentration = 40_000
+
+scatterer_collection = ScattererCollection(medium_refractive_index=1.33 * units.RIU)
+
+population_0 = Population(
+    name='EV',
+    particle_count=1e+9 * units.particle / units.milliliter,
+    size=distribution.RosinRammler(characteristic_size=200 * units.nanometer, spread=4.5),
+    refractive_index=distribution.Normal(mean=1.42 * units.RIU, std_dev=0.05 * units.RIU)
+)
+
+population_1 = Population(
+    name='LP',
+    particle_count=LP_concentration * 1e+9 * units.particle / units.milliliter,
+    size=distribution.RosinRammler(characteristic_size=100 * units.nanometer, spread=4.5),
+    refractive_index=distribution.Normal(mean=1.39 * units.RIU, std_dev=0.05 * units.RIU)
+)
+
+scatterer_collection.add_population(population_1, population_0)
+
+scatterer_collection.dilute(100)
+
+signal_digitizer = SignalDigitizer(
+    bit_depth=1024,
+    saturation_levels='auto',
+    sampling_freq=10 * units.megahertz,           # Sampling frequency: 10 MHz
+)
+
+detector_fsc = Detector(
+    name='FSC',                         # Forward Scatter detector
+    numerical_aperture=1.2 * units.AU,        # Numerical aperture: 0.2
+    phi_angle=0 * units.degree,               # Angle: 180 degrees for forward scatter
+)
+
+detector_ssc = Detector(
+    name='SSC',                         # Side Scatter detector
+    numerical_aperture=1.2 * units.AU,        # Numerical aperture: 0.2
+    phi_angle=90 * units.degree,              # Angle: 90 degrees for side scatter
+)
+
+cytometer = FlowCytometer(
+    signal_digitizer=signal_digitizer,
+    scatterer_collection=scatterer_collection,
+    flow_cell=flow_cell,
+    detectors=[detector_fsc, detector_ssc],  # Detectors: FSC and SSC
+)
+
+acquisition = cytometer.get_acquisition(run_time=0.2 * units.millisecond)
+
+acquisition.plot.signals(
+    show_populations=['EV'],
+    # save_filename=f'LP_{LP_concentration}.png'
+)

{flowcypy-0.7.3 → flowcypy-0.7.4}/docs/examples/extras/flow_cytometer_signal.py

@@ -45,19 +45,23 @@ scatterer_collection = ScattererCollection(medium_refractive_index=1.33 * units.
 
 population_0 = Population(
     name='EV',
-    particle_count=1e+9 * units.particle / units.milliliter,
-    size=distribution.RosinRammler(characteristic_size=50 * units.nanometer, spread=4.5),
-    refractive_index=distribution.Normal(mean=1.39 * units.RIU, std_dev=0.05 * units.RIU)
+    # particle_count=1e+9 * units.particle / units.milliliter,
+    particle_count=10 * units.particle,
+    size=distribution.RosinRammler(characteristic_size=200 * units.nanometer, spread=4.5),
+    refractive_index=distribution.Normal(mean=1.42 * units.RIU, std_dev=0.05 * units.RIU)
 )
 
 population_1 = Population(
     name='LP',
-    particle_count=1e+9 * units.particle / units.milliliter,
-    size=distribution.RosinRammler(characteristic_size=200 * units.nanometer, spread=4.5),
-    refractive_index=distribution.Normal(mean=1.45 * units.RIU, std_dev=0.05 * units.RIU)
+    # particle_count=1e+9 * units.particle / units.milliliter,
+    particle_count=50_000 * units.particle,
+    size=distribution.RosinRammler(characteristic_size=100 * units.nanometer, spread=4.5),
+    refractive_index=distribution.Normal(mean=1.39 * units.RIU, std_dev=0.05 * units.RIU)
 )
 
-scatterer_collection.add_population(population_0, population_1)
+scatterer_collection.add_population(population_1, population_0)
+
+# scatterer_collection.dilute(100)
 
 # Step 5: Set up the detectors
 # ----------------------------
@@ -99,7 +103,7 @@ cytometer = FlowCytometer(
 acquisition = cytometer.get_acquisition(run_time=0.2 * units.millisecond)
 
 # Visualize the scatter signals from both detectors
-acquisition.plot.signals()
+acquisition.plot.signals(show_populations=['EV'])
 
 # %%
 #

{flowcypy-0.7.3 → flowcypy-0.7.4}/tests/test_coupling_mechanism.py

@@ -83,7 +83,7 @@ def test_generate_scatterer_size(scatterer_collection, default_flow_cell):
     """
     Test if the sizes are generated correctly in the ScattererCollection.
     """
-    scatterer_dataframe = default_flow_cell.generate_event_dataframe(
+    scatterer_dataframe = default_flow_cell._generate_event_dataframe(
         scatterer_collection.populations,
         run_time=0.001 * units.second
     )
@@ -101,7 +101,7 @@ def test_rayleigh_mechanism_output(detector, scatterer_collection, source, defau
     """
     Test the detected power output of the Rayleigh scattering mechanism.
     """
-    scatterer_dataframe = default_flow_cell.generate_event_dataframe(
+    scatterer_dataframe = default_flow_cell._generate_event_dataframe(
         scatterer_collection.populations,
         run_time=0.001 * units.second
     )

{flowcypy-0.7.3 → flowcypy-0.7.4}/tests/test_population.py

@@ -62,7 +62,7 @@ def scatterer_collection(populations):
 
 @pytest.fixture
 def population_dataframe(flow_cell, populations):
-    dataframe = flow_cell.generate_event_dataframe(populations, run_time=RUN_TIME)
+    dataframe = flow_cell._generate_event_dataframe(populations, run_time=RUN_TIME)
 
     return dataframe
 

{flowcypy-0.7.3 → flowcypy-0.7.4}/tests/test_scatterer_distribution.py

@@ -53,7 +53,7 @@ def test_generate_distribution_size(distribution, default_flow_cell):
 
     scatterer_collection.add_population(population_0)
 
-    dataframe = default_flow_cell.generate_event_dataframe(
+    dataframe = default_flow_cell._generate_event_dataframe(
         scatterer_collection.populations,
         run_time=100e-4 * units.second
     )
@@ -115,7 +115,7 @@ def test_generate_longitudinal_positions(default_flow_cell, distribution):
 
     scatterer_collection.add_population(population_0)
 
-    dataframe = default_flow_cell.generate_event_dataframe(
+    dataframe = default_flow_cell._generate_event_dataframe(
         scatterer_collection.populations,
         run_time=100e-4 * units.second
     )