FlowCyPy 0.7.4__tar.gz → 0.8.1__tar.gz

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

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

flowcypy-0.8.1/FlowCyPy/acquisition.py

@@ -0,0 +1,188 @@
+import warnings
+import pandas as pd
+import numpy as np
+from FlowCyPy import units
+from FlowCyPy.triggered_acquisition import TriggeredAcquisitions
+from FlowCyPy.dataframe_subclass import TriggeredAcquisitionDataFrame
+
+
+class Acquisition:
+    """
+    Represents a flow cytometry experiment, including runtime, dataframes, logging, and visualization.
+
+    Attributes
+    ----------
+    run_time : units.second
+        Total runtime of the experiment.
+    scatterer_dataframe : pd.DataFrame
+        DataFrame containing scatterer data, indexed by population and time.
+    detector_dataframe : pd.DataFrame
+        DataFrame containing detector signal data, indexed by detector and time.
+    """
+
+    def __init__(self, run_time: units.second, cytometer: object, scatterer_dataframe: pd.DataFrame, detector_dataframe: pd.DataFrame):
+        """
+        Initializes the Experiment instance.
+
+        Parameters
+        ----------
+        run_time : Quantity
+            Total runtime of the experiment.
+        scatterer_dataframe : pd.DataFrame
+            DataFrame with scatterer data.
+        detector_dataframe : pd.DataFrame
+            DataFrame with detector signal data.
+        """
+        self.cytometer = cytometer
+        self.signal = detector_dataframe
+        self.scatterer = scatterer_dataframe
+        self.run_time = run_time
+
+    @property
+    def n_detectors(self) -> int:
+        return len(self.signal.index.get_level_values('Detector').unique())
+
+    def _get_trigger_indices(
+        self,
+        threshold: units.Quantity,
+        trigger_detector_name: str = None,
+        pre_buffer: int = 64,
+        post_buffer: int = 64
+    ) -> tuple[np.ndarray, np.ndarray]:
+        """
+        Calculate start and end indices for triggered segments, ensuring no retriggering
+        occurs during an active buffer period.
+
+        Parameters
+        ----------
+        threshold : units.Quantity
+            The threshold value for triggering.
+        trigger_detector_name : str, optional
+            The name of the detector to use for the triggering signal.
+        pre_buffer : int, optional
+            Number of samples to include before the trigger point.
+        post_buffer : int, optional
+            Number of samples to include after the trigger point.
+
+        Returns
+        -------
+        tuple[np.ndarray, np.ndarray]
+            The start and end indices of non-overlapping triggered segments.
+
+        Raises
+        ------
+        ValueError
+            If the specified detector is not found in the data.
+        """
+        if trigger_detector_name not in self.signal.index.get_level_values('Detector').unique():
+            raise ValueError(f"Detector '{trigger_detector_name}' not found.")
+
+        signal = self.signal.xs(trigger_detector_name)['Signal']
+        trigger_signal = signal > threshold.to(signal.pint.units)
+
+        crossings = np.where(np.diff(trigger_signal.astype(int)) == 1)[0]
+        start_indices = np.clip(crossings - pre_buffer, 0, len(trigger_signal) - 1)
+        end_indices = np.clip(crossings + post_buffer, 0, len(trigger_signal) - 1)
+
+        # Suppress retriggering within an active buffer period
+        suppressed_start_indices = []
+        suppressed_end_indices = []
+
+        last_end = -1
+        for start, end in zip(start_indices, end_indices):
+            if start > last_end:  # Ensure no overlap with the last active buffer
+                suppressed_start_indices.append(start)
+                suppressed_end_indices.append(end)
+                last_end = end  # Update the end of the current active buffer
+
+        return np.array(suppressed_start_indices), np.array(suppressed_end_indices)
+
+    def run_triggering(self,
+            threshold: units.Quantity,
+            trigger_detector_name: str,
+            pre_buffer: int = 64,
+            post_buffer: int = 64,
+            max_triggers: int = None) -> TriggeredAcquisitions:
+        """
+        Execute triggered acquisition analysis for signal data.
+
+        This method identifies segments of signal data based on a triggering threshold
+        and specified detector. It extracts segments of interest from the signal,
+        including a pre-trigger buffer and post-trigger buffer.
+
+        Parameters
+        ----------
+        threshold : units.Quantity
+            The threshold value for triggering. Only signal values exceeding this threshold
+            will be considered as trigger events.
+        trigger_detector_name : str
+            The name of the detector used for triggering. This determines which detector's
+            signal is analyzed for trigger events.
+        pre_buffer : int, optional
+            The number of points to include before the trigger point in each segment.
+            Default is 64.
+        post_buffer : int, optional
+            The number of points to include after the trigger point in each segment.
+            Default is 64.
+        max_triggers : int, optional
+            The maximum number of triggers to process. If None, all triggers will be processed.
+            Default is None.
+
+        Raises
+        ------
+        ValueError
+            If the specified `trigger_detector_name` is not found in the dataset.
+
+        Warnings
+        --------
+        UserWarning
+            If no triggers are detected for the specified threshold, the method raises a warning
+            indicating that no signals met the criteria.
+
+        Notes
+        -----
+        - The peak detection function `self.detect_peaks` is automatically called at the end of this method to analyze triggered segments.
+        """
+        self.threshold = threshold
+        self.trigger_detector_name = trigger_detector_name
+        start_indices, end_indices = self._get_trigger_indices(
+            threshold, trigger_detector_name, pre_buffer, post_buffer
+        )
+
+        if max_triggers is not None:
+            start_indices = start_indices[:max_triggers]
+            end_indices = end_indices[:max_triggers]
+
+        segments = []
+        for detector_name in self.signal.index.get_level_values('Detector').unique():
+            detector_data = self.signal.xs(detector_name)
+            time, digitized, signal = detector_data['Time'], detector_data['DigitizedSignal'],  detector_data['Signal']
+
+
+            for idx, (start, end) in enumerate(zip(start_indices, end_indices)):
+
+                segment = pd.DataFrame({
+                    'Time': time[start:end + 1],
+                    'DigitizedSignal': digitized[start:end + 1],
+                    'Signal': signal[start:end + 1],
+                    'Detector': detector_name,
+                    'SegmentID': idx
+                })
+                segments.append(segment)
+
+        if len(segments) !=0:
+            triggered_signal = TriggeredAcquisitionDataFrame(pd.concat(segments).set_index(['Detector', 'SegmentID']))
+            triggered_signal.attrs['bit_depth'] = self.signal.attrs['bit_depth']
+            triggered_signal.attrs['saturation_levels'] = self.signal.attrs['saturation_levels']
+            triggered_signal.attrs['scatterer_dataframe'] = self.signal.attrs['scatterer_dataframe']
+
+            triggered_acquisition = TriggeredAcquisitions(parent=self, dataframe=triggered_signal)
+            triggered_acquisition.scatterer = self.scatterer
+
+            return triggered_acquisition
+        else:
+            warnings.warn(
+                f"No signal were triggered during the run time, try changing the threshold. Signal min-max value is: {self.signal['Signal'].min().to_compact()}, {self.signal['Signal'].max().to_compact()}",
+                UserWarning
+            )
+

{flowcypy-0.7.4 → flowcypy-0.8.1}/FlowCyPy/classifier.py

@@ -2,7 +2,7 @@ from sklearn.cluster import KMeans
 from sklearn.cluster import DBSCAN
 from sklearn.mixture import GaussianMixture
 import pandas as pd
-from typing import Dict, Tuple
+from FlowCyPy.dataframe_subclass import ClassifierDataFrame
 
 
 class BaseClassifier:
@@ -80,7 +80,7 @@ class KmeansClassifier(BaseClassifier):
 
         dataframe['Label'] = labels
 
-        return labels
+        return ClassifierDataFrame(dataframe)
 
 class GaussianMixtureClassifier(BaseClassifier):
     def __init__(self, number_of_components: int) -> None:
@@ -128,7 +128,7 @@ class GaussianMixtureClassifier(BaseClassifier):
         # Add labels to the original DataFrame
         dataframe['Label'] = labels
 
-        return labels
+        return ClassifierDataFrame(dataframe)
 
 class DBSCANClassifier(BaseClassifier):
     def __init__(self, epsilon: float = 0.5, min_samples: int = 5) -> None:
@@ -179,4 +179,4 @@ class DBSCANClassifier(BaseClassifier):
         # Add labels to the original DataFrame
         dataframe['Label'] = labels
 
-        return labels
+        return ClassifierDataFrame(dataframe)

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

@@ -8,12 +8,13 @@ import pandas as pd
 from pint_pandas import PintArray
 
 from FlowCyPy import units
-from FlowCyPy.units import Quantity, milliwatt
+from FlowCyPy.units import milliwatt
 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
+from FlowCyPy.dataframe_subclass import ContinuousAcquisitionDataFrame
 
 
 # Set up logging configuration
@@ -41,7 +42,7 @@ class FlowCytometer:
     coupling_mechanism : str, optional
         The scattering mechanism used to couple the signal from the particles to the detectors.
         Supported mechanisms include: 'mie' (default): Mie scattering, 'rayleigh': Rayleigh scattering, 'uniform': Uniform signal coupling, 'empirical': Empirical data-driven coupling
-    background_power : Quantity, optional
+    background_power : units.watt, optional
         The background optical power added to the detector signal. Defaults to 0 milliwatts.
 
     Attributes
@@ -56,7 +57,7 @@ class FlowCytometer:
         The detectors used to collect and process signals from the scatterers.
     coupling_mechanism : str
         The selected mechanism for signal coupling.
-    background_power : Quantity
+    background_power : units.watt
         The optical background power added to the detector signals.
 
     Raises
@@ -72,7 +73,7 @@ class FlowCytometer:
             signal_digitizer: SignalDigitizer,
             detectors: List[Detector],
             coupling_mechanism: Optional[str] = 'mie',
-            background_power: Optional[Quantity] = 0 * milliwatt):
+            background_power: Optional[units.watt] = 0 * milliwatt):
 
         self.scatterer_collection = scatterer_collection
         self.flow_cell = flow_cell
@@ -185,7 +186,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: units.second) -> None:
         """
         Initializes the raw signal for each detector based on the source and flow cell configuration.
 
@@ -206,12 +207,14 @@ class FlowCytometer:
 
             dataframes.append(dataframe)
 
-        self.dataframe = pd.concat(dataframes, keys=[d.name for d in self.detectors])
+        dataframe = pd.concat(dataframes, keys=[d.name for d in self.detectors])
 
-        self.dataframe.index.names = ["Detector", "Index"]
+        dataframe.index.names = ["Detector", "Index"]
+
+        return dataframe
 
     @validate_units(run_time=units.second)
-    def get_acquisition(self, run_time: Quantity) -> None:
+    def get_acquisition(self, run_time: units.second) -> None:
         """
         Simulates the generation of optical signal pulses for each particle event.
 
@@ -233,7 +236,7 @@ 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)
+        signal_dataframe = self._initialize_signal(run_time=run_time)
 
         scatterer_dataframe = self.flow_cell._generate_event_dataframe(self.scatterer_collection.populations, run_time=run_time)
 
@@ -251,7 +254,7 @@ class FlowCytometer:
         for detector in self.detectors:
             _coupling_power = scatterer_dataframe[detector.name].values
 
-            detector_signal = self.dataframe.xs(detector.name)['Signal']
+            detector_signal = signal_dataframe.xs(detector.name)['Signal']
 
             # Generate noise components
             detector._add_thermal_noise_to_raw_signal(signal=detector_signal)
@@ -259,7 +262,7 @@ class FlowCytometer:
             detector._add_dark_current_noise_to_raw_signal(signal=detector_signal)
 
             # Broadcast the time array to the shape of (number of signals, len(detector.time))
-            time = self.dataframe.xs(detector.name)['Time'].pint.magnitude
+            time = signal_dataframe.xs(detector.name)['Time'].pint.magnitude
 
             time_grid = np.expand_dims(time, axis=0) * units.second
             centers = np.expand_dims(_centers, axis=1) * units.second
@@ -280,15 +283,20 @@ class FlowCytometer:
 
             digitized_signal = detector.capture_signal(signal=detector_signal)
 
-            self.dataframe.loc[detector.name, 'Signal'] = PintArray(detector_signal, detector_signal.pint.units)
+            signal_dataframe.loc[detector.name, 'Signal'] = PintArray(detector_signal, detector_signal.pint.units)
+
+            signal_dataframe.loc[detector.name, 'DigitizedSignal'] = PintArray(digitized_signal, units.bit_bins)
 
-            self.dataframe.loc[detector.name, 'DigitizedSignal'] = PintArray(digitized_signal, units.bit_bins)
+        signal_dataframe = ContinuousAcquisitionDataFrame(signal_dataframe)
+        signal_dataframe.attrs['bit_depth'] = self.signal_digitizer._bit_depth
+        signal_dataframe.attrs['saturation_levels'] = {d.name: d._saturation_levels for d in self.detectors}
+        signal_dataframe.attrs['scatterer_dataframe'] = scatterer_dataframe
 
         experiment = Acquisition(
             cytometer=self,
             run_time=run_time,
             scatterer_dataframe=scatterer_dataframe,
-            detector_dataframe=self.dataframe
+            detector_dataframe=signal_dataframe
         )
 
         return experiment