FlowCyPy 1.2.0__cp314-cp314-macosx_26_0_arm64.whl

FlowCyPy/__init__.py

@@ -0,0 +1,63 @@
+try:
+    from ._version import version as __version__
+
+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"),
+    "DetectionAnalyzer": (".analysis", "DetectionAnalyzer"),
+}
+
+
+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
+
+# Preserve the established public export order.
+__all__ = [  # noqa: RUF022
+    "__version__",
+    "FlowCytometer",
+    "Workflow",
+    "Fluidics",
+    "distributions",
+    "populations",
+    "OptoElectronics",
+    "circuits",
+    "source",
+    "DigitalProcessing",
+    "classifier",
+    "discriminator",
+    "peak_locator",
+    "ureg",
+    "debug_mode",
+    "DetectionAnalyzer",
+]

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.2.0'
+__version_tuple__ = version_tuple = (1, 2, 0)
+
+__commit_id__ = commit_id = 'g04a10e5f9'

FlowCyPy/analysis.py

@@ -0,0 +1,177 @@
+"""Analysis helpers for simulated flow-cytometry acquisitions."""
+
+
+from collections.abc import Iterable, Sequence
+
+import numpy as np
+import pandas as pd
+
+from .units import ureg
+
+
+class DetectionAnalyzer:
+    """Relate digital trigger windows to simulated population events.
+
+    The analyzer uses the ground-truth event arrival time and population label
+    stored in a :class:`~FlowCyPy.run_record.RunRecord`. An event is considered
+    detected when its arrival time falls within a digital trigger segment.
+
+    This measures trigger capture, not successful peak localization.
+    """
+
+    @staticmethod
+    def _to_seconds(values, unit=None) -> np.ndarray:
+        """Convert quantities or numeric values to seconds."""
+        if hasattr(values, "pint"):
+            return np.asarray(values.pint.to("second").magnitude, dtype=float)
+
+        if hasattr(values, "to") and hasattr(values, "magnitude"):
+            return np.asarray(values.to("second").magnitude, dtype=float)
+
+        raw_values = list(values) if hasattr(values, "__iter__") else [values]
+        seconds = []
+        for value in raw_values:
+            if hasattr(value, "to") and hasattr(value, "magnitude"):
+                seconds.append(value.to("second").magnitude)
+            elif unit is not None:
+                unit_value = ureg(unit) if isinstance(unit, str) else unit
+                seconds.append((value * unit_value).to("second").magnitude)
+            else:
+                seconds.append(value)
+        return np.asarray(seconds, dtype=float)
+
+    @staticmethod
+    def _event_dataframe(run_record) -> pd.DataFrame:
+        """Return the simulated event table with population labels exposed."""
+        return (
+            run_record.event_collection
+            .get_concatenated_dataframe()
+            .reset_index()
+        )
+
+    def annotate(self, run_record) -> pd.DataFrame:
+        """Annotate events with ``Detected`` and ``TriggerID`` columns.
+
+        Events without a matching trigger segment are retained and marked
+        ``Detected=False``. Runs without any digital triggers are supported.
+
+        An event is detected when its simulated arrival time satisfies
+        ``segment_start <= event_time <= segment_stop`` for a digital trigger
+        segment. If an event falls into more than one segment, the first
+        matching segment in the digital table is assigned.
+        """
+        events = self._event_dataframe(run_record).copy()
+        events["Detected"] = False
+        events["TriggerID"] = pd.Series(
+            pd.NA, index=events.index, dtype="Int64"
+        )
+
+        digital = run_record.signal.digital
+        if digital is None or "Time" not in events or len(events) == 0:
+            return events
+
+        digital_table = digital.reset_index()
+        segment_column = (
+            "SegmentID" if "SegmentID" in digital_table else "segment_id"
+        )
+        if segment_column not in digital_table:
+            return events
+
+        digital_unit = digital.attrs.get("units", {}).get("Time", "second")
+        digital_table["_time_s"] = self._to_seconds(
+            digital_table["Time"], unit=digital_unit
+        )
+        event_times = self._to_seconds(events["Time"])
+        detected = np.zeros(len(events), dtype=bool)
+        trigger_ids = np.full(len(events), -1, dtype=int)
+
+        for segment_id, segment in digital_table.groupby(segment_column):
+            start = segment["_time_s"].min()
+            stop = segment["_time_s"].max()
+            matches = (
+                (event_times >= start)
+                & (event_times <= stop)
+                & ~detected
+            )
+            detected[matches] = True
+            trigger_ids[matches] = int(segment_id)
+
+        events["Detected"] = detected
+        events.loc[detected, "TriggerID"] = trigger_ids[detected]
+        return events
+
+    def summary(
+        self,
+        run_records: Sequence,
+        population_names: Iterable[str] | None = None,
+        condition_names: Sequence[str] | None = None,
+    ) -> pd.DataFrame:
+        """Return simulated counts, detected counts, and efficiencies.
+
+        ``SimulatedEvents`` counts events of the selected population in the
+        event collection after the SEC cutoff. ``DetectedEvents`` counts those
+        events whose arrival times overlap a digital trigger segment.
+        ``DetectionEfficiency`` is calculated as:
+
+        ``DetectedEvents / SimulatedEvents``
+        """
+        if condition_names is None:
+            condition_names = [
+                f"Run {index}" for index in range(len(run_records))
+            ]
+        if len(condition_names) != len(run_records):
+            raise ValueError("condition_names must match run_records.")
+
+        rows = []
+        for condition, run_record in zip(condition_names, run_records):
+            events = self.annotate(run_record)
+            available = sorted(events["Population"].dropna().unique())
+            selected = list(population_names) if population_names else available
+            for population in selected:
+                statistics = run_record.detection_statistics(population)
+                rows.append({"Condition": condition, **statistics})
+        return pd.DataFrame(rows)
+
+    def coincidence_statistics(self, run_record) -> dict:
+        """Summarize multiple simulated events sharing one trigger segment.
+
+        A segment is coincident when at least two events are assigned to it by
+        :meth:`annotate`. Population-combination counts distinguish, for
+        example, EV--EV from EV--LP coincidences.
+        """
+        events = self.annotate(run_record)
+        detected = events[
+            events["Detected"] & events["TriggerID"].notna()
+        ]
+
+        if detected.empty:
+            return {
+                "TriggerSegments": 0,
+                "DetectedEvents": 0,
+                "CoincidentSegments": 0,
+                "CoincidenceRate": np.nan,
+                "PopulationCombinations": {},
+            }
+
+        by_segment = detected.groupby("TriggerID", dropna=True)
+        segment_sizes = by_segment.size()
+        coincident_segments = segment_sizes[segment_sizes >= 2]
+        combinations = {}
+
+        for _, segment in by_segment:
+            if len(segment) < 2:
+                continue
+            populations = "+".join(sorted(segment["Population"].astype(str)))
+            combinations[populations] = combinations.get(populations, 0) + 1
+
+        trigger_segments = len(segment_sizes)
+        return {
+            "TriggerSegments": trigger_segments,
+            "DetectedEvents": len(detected),
+            "CoincidentSegments": len(coincident_segments),
+            "CoincidenceRate": (
+                len(coincident_segments) / trigger_segments
+                if trigger_segments else np.nan
+            ),
+            "PopulationCombinations": combinations,
+        }

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,31 @@
+# Initialize the shared unit registry before loading native processing modules.
+import FlowCyPy.units as _  # noqa: F401
+
+from . import discriminator, 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,28 @@
+
+from pathlib import Path
+
+import FlowCyPy
+
+__all__ = ["doc_css_path", "doc_path", "logo_path", "project_path", "root_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"
+
+# -