FlowCyPy 1.0.4__cp313-cp313-macosx_26_0_arm64.whl

FlowCyPy/__init__.py

@@ -0,0 +1,60 @@
+try:
+    from ._version import version as __version__  # noqa: F401
+
+except ImportError:
+    __version__ = "0.0.0"
+
+debug_mode = False
+
+
+_LAZY_EXPORTS = {
+    "FlowCytometer": (".flow_cytometer", "FlowCytometer"),
+    "Workflow": (".workflow", "Workflow"),
+    "Fluidics": (".fluidics", "Fluidics"),
+    "distributions": (".fluidics", "distributions"),
+    "populations": (".fluidics", "populations"),
+    "OptoElectronics": (".opto_electronics", "OptoElectronics"),
+    "circuits": (".opto_electronics", "circuits"),
+    "source": (".opto_electronics", "source"),
+    "DigitalProcessing": (".digital_processing", "DigitalProcessing"),
+    "classifier": (".digital_processing", "classifier"),
+    "discriminator": (".digital_processing", "discriminator"),
+    "peak_locator": (".digital_processing", "peak_locator"),
+    "ureg": (".units", "ureg"),
+}
+
+
+def __getattr__(name: str):
+    """Resolve public objects only when they are first accessed.
+
+    Keeping the compatibility exports lazy makes ``import FlowCyPy`` cheap
+    while retaining the established top-level API.
+    """
+    try:
+        module_name, attribute_name = _LAZY_EXPORTS[name]
+    except KeyError as error:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from error
+
+    from importlib import import_module
+
+    value = getattr(import_module(module_name, __name__), attribute_name)
+    globals()[name] = value
+    return value
+
+__all__ = [
+    "__version__",
+    "FlowCytometer",
+    "Workflow",
+    "Fluidics",
+    "distributions",
+    "populations",
+    "OptoElectronics",
+    "circuits",
+    "source",
+    "DigitalProcessing",
+    "classifier",
+    "discriminator",
+    "peak_locator",
+    "ureg",
+    "debug_mode",
+]

FlowCyPy/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '1.0.4'
+__version_tuple__ = version_tuple = (1, 0, 4)
+
+__commit_id__ = commit_id = 'g347e1bfc3'

FlowCyPy/digital_processing/__init__.py

@@ -0,0 +1,3 @@
+from .pipeline import DigitalProcessing, discriminator, peak_locator
+
+__all__ = ["DigitalProcessing", "discriminator", "peak_locator"]

FlowCyPy/digital_processing/pipeline.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+import FlowCyPy.units as _
+from . import discriminator
+from . import peak_locator
+
+
+class DigitalProcessing:
+    """
+    Container for analog and digital signal processing stages in a simulated flow cytometry pipeline.
+
+    This class orchestrates the application of analog electronic filtering, digitization, triggering,
+    and peak detection algorithms. It integrates key building blocks of the signal acquisition chain
+    in a modular and extensible way.
+
+    Parameters
+    ----------
+    discriminator : discriminator.BaseDiscriminator
+        Component responsible for extracting signal segments based on threshold-crossing
+        or window-based logic applied to the analog signal.
+    peak_algorithm : peak_locator.BasePeakLocator
+        Peak detection algorithm that locates and characterizes peaks in the digitized signal
+        (e.g., based on amplitude, area, or width).
+    """
+
+    def __init__(
+        self,
+        discriminator: discriminator.BaseDiscriminator = None,
+        peak_algorithm: peak_locator.BasePeakLocator = None,
+    ):
+        self.discriminator = discriminator
+        self.peak_algorithm = peak_algorithm

FlowCyPy/directories.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+
+from pathlib import Path
+
+import FlowCyPy
+
+__all__ = ["root_path", "project_path", "doc_path", "doc_css_path", "logo_path"]
+
+root_path = Path(FlowCyPy.__path__[0])
+
+project_path = root_path.parents[0]
+
+example_directory = root_path.joinpath("examples")
+
+doc_path = project_path.joinpath("docs")
+
+doc_css_path = doc_path.joinpath("source/_static/default.css")
+
+logo_path = doc_path.joinpath("images/logo.png")
+
+examples_path = root_path.joinpath("examples")
+
+if __name__ == "__main__":
+    for path_name in __all__:
+        path = locals()[path_name]
+        print(path)
+        assert path.exists(), f"Path {path_name} do not exists"
+
+# -

FlowCyPy/flow_cytometer.py

@@ -0,0 +1,492 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+import logging
+import math
+from typing import Optional
+import numpy as np
+from TypedUnit import Power, Time, ureg, validate_units
+
+from FlowCyPy.fluidics import Fluidics
+from FlowCyPy.fluidics import populations
+from FlowCyPy.fluidics.event_collection import EventCollection
+from FlowCyPy.opto_electronics import OptoElectronics
+from FlowCyPy.run_record import RunRecord
+from FlowCyPy.digital_processing import DigitalProcessing
+from FlowCyPy.sub_frames.acquisition import AcquisitionDataFrame
+from FlowCyPy.sub_frames.peaks import PeakDataFrame
+from FlowCyPy.sub_frames.triggered import TriggerDataFrame
+
+
+logger = logging.getLogger(__name__)
+
+
+class FlowCytometer:
+    """
+    High level orchestrator for the flow cytometry simulation pipeline.
+
+    This class keeps only the persistent fluidic definition and the constant
+    optical background level. All other configuration objects are passed
+    explicitly to the methods that use them.
+
+    This design keeps the workflow fully visible to the caller and avoids any
+    ambiguity about which opto electronic or signal processing configuration is
+    active for a given computation.
+
+    Parameters
+    ----------
+    fluidics : Fluidics
+        Fluidic subsystem, including flow cell and population definitions.
+    background_power : pint.Quantity, optional
+        Constant optical background added to every detector channel.
+    """
+
+    @validate_units
+    def __init__(
+        self,
+        fluidics: Fluidics,
+        background_power: Optional[Power] = 0 * ureg.milliwatt,
+    ):
+        self.fluidics = fluidics
+        self.background_power = background_power
+
+    def _add_explicit_model_signals(
+        self,
+        event_collection: EventCollection,
+        signal_dict: dict,
+        opto_electronics: OptoElectronics,
+    ) -> None:
+        """
+        Add explicit model detector signals to the optical power dictionary.
+
+        Parameters
+        ----------
+        event_collection : EventCollection
+            Population event blocks.
+        signal_dict : dict
+            Optical power signal dictionary updated in place.
+        opto_electronics : OptoElectronics
+            Opto electronic configuration.
+        """
+        for events in event_collection:
+            if not isinstance(events.sampling_method, populations.ExplicitModel):
+                continue
+
+            if events.empty:
+                continue
+
+            time_array_seconds = signal_dict["Time"].to("second").magnitude
+
+            if time_array_seconds.size == 0:
+                continue
+
+            if time_array_seconds.size == 1:
+                acquisition_window_seconds = time_array_seconds[0]
+            else:
+                acquisition_window_seconds = (
+                    time_array_seconds[-1] - time_array_seconds[0]
+                    + (time_array_seconds[1] - time_array_seconds[0])
+                )
+
+            event_times = events.get_quantity("Time").to("second")
+            event_velocities = events.get_quantity("Velocity").to("meter / second")
+            pulse_widths = opto_electronics.source.get_particle_width(
+                event_velocities
+            ).to("second")
+
+            event_time_values = event_times.magnitude
+            velocity_values = event_velocities.magnitude
+            pulse_width_values = pulse_widths.magnitude
+            support_margin_seconds = 4.0 * pulse_width_values
+
+            prepend_mask = event_time_values >= (
+                acquisition_window_seconds - support_margin_seconds
+            )
+            append_mask = event_time_values < support_margin_seconds
+
+            wrapped_time_values = np.concatenate(
+                [
+                    event_time_values[prepend_mask] - acquisition_window_seconds,
+                    event_time_values,
+                    event_time_values[append_mask] + acquisition_window_seconds,
+                ]
+            )
+            wrapped_velocity_values = np.concatenate(
+                [
+                    velocity_values[prepend_mask],
+                    velocity_values,
+                    velocity_values[append_mask],
+                ]
+            )
+
+            wrapped_times = wrapped_time_values * ureg.second
+            wrapped_velocities = wrapped_velocity_values * ureg.meter / ureg.second
+
+            for detector in opto_electronics.detectors:
+                event_amplitudes = events.get_quantity(detector.name).to("watt")
+                amplitude_values = event_amplitudes.magnitude
+                wrapped_amplitude_values = np.concatenate(
+                    [
+                        amplitude_values[prepend_mask],
+                        amplitude_values,
+                        amplitude_values[append_mask],
+                    ]
+                )
+
+                generated_pulse_signal = opto_electronics.source.generate_pulses(
+                    velocities=wrapped_velocities,
+                    pulse_centers=wrapped_times,
+                    pulse_amplitudes=wrapped_amplitude_values * ureg.watt,
+                    time_array=signal_dict["Time"],
+                    base_level=0 * ureg.watt,
+                )
+
+                signal_dict[detector.name] += generated_pulse_signal
+
+    def _add_gamma_model_signals(
+        self,
+        event_collection: EventCollection,
+        signal_dict: dict,
+        opto_electronics: OptoElectronics,
+    ) -> None:
+        """
+        Add gamma model detector signals to the optical power dictionary.
+
+        Parameters
+        ----------
+        event_collection : EventCollection
+            Population event blocks.
+        signal_dict : dict
+            Optical power signal dictionary updated in place.
+        opto_electronics : OptoElectronics
+            Opto electronic configuration.
+        """
+        for events in event_collection:
+            if not isinstance(events.sampling_method, populations.GammaModel):
+                continue
+
+            if events.empty:
+                continue
+
+            expected_number_of_particles = events.metadata["ExpectedNumberOfParticles"]
+
+            if expected_number_of_particles == 0:
+                continue
+
+            if len(opto_electronics.detectors) == 0:
+                raise ValueError("opto_electronics must contain at least one detector.")
+
+            reference_detector = opto_electronics.detectors[0]
+
+            reference_mean_amplitude = events.get_quantity(
+                reference_detector.name
+            ).mean()
+
+            reference_power_trace = opto_electronics.source.get_gamma_trace(
+                time_array=signal_dict["Time"],
+                shape=expected_number_of_particles,
+                scale=reference_mean_amplitude,
+                mean_velocity=events.metadata["VelocityMean"],
+            )
+
+            if reference_mean_amplitude.magnitude == 0:
+                raise ValueError(
+                    "Gamma Model reference mean amplitude is zero, cannot normalize."
+                )
+
+            particle_trace = reference_power_trace / reference_mean_amplitude
+
+            events.metadata["ParticleTrace"] = particle_trace
+            events.metadata["TimeTrace"] = signal_dict["Time"]
+
+            for detector in opto_electronics.detectors:
+                mean_amplitude = events.get_quantity(detector.name).mean()
+                detector_power_trace = particle_trace * mean_amplitude
+                signal_dict[detector.name] += detector_power_trace
+
+    def compute_analog(
+        self,
+        run_time: Time,
+        event_collection: EventCollection,
+        opto_electronics: OptoElectronics,
+    ) -> dict:
+        """
+        Compute the full analog detector waveforms from an event collection.
+
+        Parameters
+        ----------
+        run_time : Time
+            Acquisition duration.
+        event_collection : EventCollection
+            Population event blocks with optical coupling already evaluated.
+        opto_electronics : OptoElectronics
+            Opto electronic configuration.
+
+        Returns
+        -------
+        dict
+            Analog voltage signal dictionary.
+        """
+        self._validate_run_time(run_time)
+        power_signal_dict = opto_electronics.initialize_optical_signal_dict(
+            run_time=run_time,
+            background_power=self.background_power,
+        )
+
+        self._add_explicit_model_signals(
+            event_collection=event_collection,
+            signal_dict=power_signal_dict,
+            opto_electronics=opto_electronics,
+        )
+
+        self._add_gamma_model_signals(
+            event_collection=event_collection,
+            signal_dict=power_signal_dict,
+            opto_electronics=opto_electronics,
+        )
+
+        return opto_electronics.convert_optical_power_to_voltage(power_signal_dict)
+
+    def process_analog(
+        self,
+        run_time: Time,
+        event_collection: EventCollection,
+        analog_dict: dict,
+        digital_processing: DigitalProcessing,
+        opto_electronics: OptoElectronics,
+    ) -> RunRecord:
+        """
+        Process an existing analog acquisition through the downstream signal
+        processing chain.
+
+        Parameters
+        ----------
+        run_time : Time
+            Acquisition duration.
+        event_collection : EventCollection
+            Event collection associated with the analog signals.
+        analog_dict : dict
+            Analog voltage signal dictionary.
+        digital_processing : DigitalProcessing
+            Signal processing configuration.
+        opto_electronics : OptoElectronics
+            Opto electronic configuration associated with the analog signal.
+
+        Returns
+        -------
+        RunRecord
+            Run record containing the analog acquisition and all downstream
+            results that could be computed.
+        """
+        run_record = RunRecord(
+            run_time=run_time,
+            event_collection=event_collection,
+            opto_electronics=opto_electronics,
+            digital_processing=digital_processing,
+        )
+
+        processed_analog_dict = opto_electronics.apply_analog_processing(
+            analog_dict=analog_dict,
+        )
+
+        run_record.signal.analog = AcquisitionDataFrame._construct_from_signal_dict(
+            signal_dict=processed_analog_dict,
+        )
+
+        triggered_analog_dict = (
+            digital_processing.discriminator.run_with_dict(processed_analog_dict)
+            if digital_processing.discriminator is not None
+            else None
+        )
+
+        if triggered_analog_dict is None:
+            return run_record
+
+        if len(triggered_analog_dict["segment_id"]) == 0:
+            logger.debug(
+                "No triggers detected. Returning analog signal without digital processing."
+            )
+            return run_record
+
+        triggered_digital_dict = opto_electronics.digitizer.digitize_data_dict(
+            triggered_analog_dict
+        )
+
+        run_record.signal.digital = TriggerDataFrame._construct_from_flat_dict(
+            triggered_digital_dict,
+        )
+
+        if digital_processing.peak_algorithm is not None:
+            peaks_dict = digital_processing.peak_algorithm.run(triggered_digital_dict)
+
+            run_record.peaks = PeakDataFrame._construct_from_dict(peaks_dict)
+
+        return run_record
+
+    def process_run(
+        self,
+        run_record: RunRecord,
+        digital_processing: DigitalProcessing,
+    ) -> RunRecord:
+        """
+        Process an existing acquired run through the downstream signal
+        processing chain.
+
+        This method is intended for notebook workflows where the caller already
+        has a ``RunRecord`` returned by ``acquire()`` and wants to apply
+        downstream processing without passing the acquisition configuration again.
+
+        Parameters
+        ----------
+        run_record : RunRecord
+            Existing run record containing analog acquisition data and the
+            opto electronic configuration used to produce it.
+        digital_processing : DigitalProcessing
+            Signal processing configuration.
+
+        Returns
+        -------
+        RunRecord
+            Processed run record.
+
+        Raises
+        ------
+        ValueError
+            If the input run record does not contain an ``opto_electronics``
+            configuration.
+        ValueError
+            If the input run record does not contain analog signal data.
+        """
+        if run_record.opto_electronics is None:
+            raise ValueError(
+                "The provided run_record does not contain opto_electronics. "
+                "Make sure it was created with acquire() or manually populated."
+            )
+
+        if run_record.signal is None or run_record.signal.analog is None:
+            raise ValueError(
+                "The provided run_record does not contain analog signal data."
+            )
+
+        return self.process_analog(
+            run_time=run_record.run_time,
+            event_collection=run_record.event_collection,
+            analog_dict=run_record.signal.analog.raw_data,
+            digital_processing=digital_processing,
+            opto_electronics=run_record.opto_electronics,
+        )
+
+    def acquire(
+        self,
+        run_time: Time,
+        opto_electronics: OptoElectronics,
+        random_state: int | np.random.Generator | None = None,
+    ) -> RunRecord:
+        """
+        Run the acquisition pipeline up to the analog stage.
+
+        Parameters
+        ----------
+        run_time : Time
+            Acquisition duration.
+        opto_electronics : OptoElectronics
+            Opto electronic configuration.
+
+        Returns
+        -------
+        RunRecord
+            Run record containing the event collection, analog voltage
+            waveforms, and the opto electronic configuration used to produce
+            them.
+        """
+        self._validate_run_time(run_time)
+        self._validate_opto_electronics(opto_electronics)
+        event_collection = self.fluidics.generate_event_collection(
+            run_time=run_time,
+            sampling_rate=opto_electronics.digitizer.sampling_rate,
+            random_state=random_state,
+        )
+
+        opto_electronics.add_coupling_to_dataframe(
+            event_collection=event_collection,
+            compute_cross_section=False,
+        )
+
+        processed_analog_dict = self.compute_analog(
+            run_time=run_time,
+            event_collection=event_collection,
+            opto_electronics=opto_electronics,
+        )
+
+        run_record = RunRecord(
+            run_time=run_time,
+            event_collection=event_collection,
+            opto_electronics=opto_electronics,
+        )
+
+        run_record.signal.analog = AcquisitionDataFrame._construct_from_signal_dict(
+            signal_dict=processed_analog_dict,
+        )
+
+        return run_record
+
+    @staticmethod
+    def _validate_run_time(run_time: Time) -> None:
+        """Reject empty, negative, non-finite, or unitless run durations."""
+        try:
+            seconds = float(run_time.to("second").magnitude)
+        except (AttributeError, TypeError, ValueError) as error:
+            raise TypeError("run_time must be a time quantity.") from error
+
+        if not math.isfinite(seconds) or seconds <= 0:
+            raise ValueError("run_time must be finite and strictly positive.")
+
+    @staticmethod
+    def _validate_opto_electronics(opto_electronics: OptoElectronics) -> None:
+        """Validate detector channels before starting an acquisition."""
+        detectors = getattr(opto_electronics, "detectors", None)
+        if not detectors:
+            raise ValueError("opto_electronics must contain at least one detector.")
+
+        names = [getattr(detector, "name", None) for detector in detectors]
+        if any(not isinstance(name, str) or not name.strip() for name in names):
+            raise ValueError("Each detector must have a non-empty name.")
+        if len(names) != len(set(names)):
+            raise ValueError("Detector names must be unique.")
+
+    def run(
+        self,
+        run_time: Time,
+        opto_electronics: OptoElectronics,
+        digital_processing: Optional[DigitalProcessing] = None,
+        random_state: int | np.random.Generator | None = None,
+    ) -> RunRecord:
+        """
+        Run the full simulation pipeline from event generation to peak extraction.
+
+        Parameters
+        ----------
+        run_time : Time
+            Acquisition duration.
+        opto_electronics : OptoElectronics
+            Opto electronic configuration.
+        digital_processing : DigitalProcessing, optional
+            Signal processing configuration. If None, no digital processing is applied.
+
+        Returns
+        -------
+        RunRecord
+            Full run record containing all available stages.
+        """
+        if digital_processing is None:
+            digital_processing = DigitalProcessing()
+
+        acquired_run_record = self.acquire(
+            run_time=run_time,
+            opto_electronics=opto_electronics,
+            random_state=random_state,
+        )
+
+        return self.process_run(
+            run_record=acquired_run_record,
+            digital_processing=digital_processing,
+        )