FlowCyPy 0.8.0__tar.gz → 0.8.1__tar.gz

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

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

{flowcypy-0.8.0 → flowcypy-0.8.1}/FlowCyPy/acquisition.py

@@ -1,21 +1,10 @@
-import logging
 import warnings
-from typing import Optional, Union, List
-from MPSPlots.styles import mps
 import pandas as pd
 import numpy as np
 from FlowCyPy import units
-import matplotlib.pyplot as plt
-import seaborn as sns
-from tabulate import tabulate
-from FlowCyPy import helper
 from FlowCyPy.triggered_acquisition import TriggeredAcquisitions
 from FlowCyPy.dataframe_subclass import TriggeredAcquisitionDataFrame
 
-class DataAccessor:
-    def __init__(self, outer):
-        self._outer = outer
-
 
 class Acquisition:
     """
@@ -45,8 +34,6 @@ class Acquisition:
             DataFrame with detector signal data.
         """
         self.cytometer = cytometer
-        self.logger = self.LoggerInterface(self)
-
         self.signal = detector_dataframe
         self.scatterer = scatterer_dataframe
         self.run_time = run_time
@@ -189,174 +176,13 @@ class Acquisition:
             triggered_signal.attrs['saturation_levels'] = self.signal.attrs['saturation_levels']
             triggered_signal.attrs['scatterer_dataframe'] = self.signal.attrs['scatterer_dataframe']
 
-            return TriggeredAcquisitions(parent=self, dataframe=triggered_signal)
+            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
             )
 
-    class LoggerInterface:
-        """
-        A nested class for logging statistical information about the experiment.
-
-        Methods
-        -------
-        scatterer()
-            Logs statistics about the scatterer populations.
-        detector()
-            Logs statistics about the detector signals.
-        """
-
-        def __init__(self, experiment: object):
-            self.experiment = experiment
-
-        def scatterer(self, table_format: str = "grid") -> None:
-            """
-            Logs detailed information about scatterer populations.
-
-            Parameters
-            ----------
-            table_format : str, optional
-                The format for the table display (default: 'grid').
-                Options include 'plain', 'github', 'grid', 'fancy_grid', etc.
-
-            Returns
-            -------
-            None
-                Logs scatterer population information, including refractive index, size, particle count,
-                number of events, and time statistics.
-            """
-            logging.info("\n=== Scatterer Population Properties ===")
-
-            # Collect general population data
-            general_table_data = [
-                self._get_population_properties(population)
-                for population in self.experiment.scatterer.groupby("Population")
-            ]
-            general_headers = [
-                "Name",
-                "Refractive Index",
-                "Medium Refractive Index",
-                "Size",
-                "Particle Count",
-                "Number of Events",
-                "Min Time Between Events",
-                "Avg Time Between Events",
-            ]
-
-            formatted_general_table = tabulate(
-                general_table_data, headers=general_headers, tablefmt=table_format, floatfmt=".4f"
-            )
-            logging.info("\n" + formatted_general_table)
-
-        def _get_population_properties(self, population_group: tuple) -> List[Union[str, float]]:
-            """
-            Extracts key properties of a scatterer population for the general properties table.
-
-            Parameters
-            ----------
-            population_group : tuple
-                A tuple containing the population name and its corresponding DataFrame.
-
-            Returns
-            -------
-            list
-                List of scatterer properties: [name, refractive index, medium refractive index, size,
-                particle count, number of events, min time between events, avg time between events].
-            """
-            population_name, population_df = population_group
-
-            name = population_name
-            refractive_index = f"{population_df['RefractiveIndex'].mean():~P}"
-            medium_refractive_index = f"{self.experiment.run_time:~P}"  # Replace with actual medium refractive index if stored elsewhere
-            size = f"{population_df['Size'].mean():~P}"
-            particle_count = len(population_df)
-            num_events = particle_count
-
-            min_delta_position = population_df["Time"].diff().abs().min()
-            avg_delta_position = population_df["Time"].diff().mean()
-
-            return [
-                name,
-                refractive_index,
-                medium_refractive_index,
-                size,
-                particle_count,
-                num_events,
-                min_delta_position,
-                avg_delta_position,
-            ]
-
-        def detector(self, table_format: str = "grid", include_totals: bool = True) -> None:
-            """
-            Logs statistics about detector signals.
-
-            Parameters
-            ----------
-            table_format : str, optional
-                The format for the table display (default: 'grid').
-                Options include 'plain', 'github', 'grid', 'fancy_grid', etc.
-            include_totals : bool, optional
-                If True, logs the total number of events across all detectors (default: True).
-
-            Returns
-            -------
-            None
-                Logs details about detector signals, including event counts,
-                timing statistics, and mean event rates.
-            """
-            logging.info("\n=== Detector Signal Statistics ===")
-
-            # Compute statistics for each detector
-            df = self.experiment.signal
-            table_data = [
-                self._get_detector_stats(detector_name, df.xs(detector_name, level="Detector"))
-                for detector_name in df.index.levels[0]
-            ]
-            headers = [
-                "Detector",
-                "Number of Acquisition",
-                "First Event Time",
-                "Last Event Time",
-                "Time Between Events",
-            ]
-
-            formatted_table = tabulate(table_data, headers=headers, tablefmt=table_format, floatfmt=".3f")
-            logging.info("\n" + formatted_table)
-
-            if include_totals:
-                total_events = sum(stat[1] for stat in table_data)
-                logging.info(f"\nTotal number of events detected across all detectors: {total_events}")
-
-        def _get_detector_stats(self, detector_name: str, group: pd.DataFrame) -> list:
-            """
-            Computes statistics for a detector.
-
-            Parameters
-            ----------
-            detector_name : str
-                Name of the detector.
-            group : pd.DataFrame
-                DataFrame containing the detector data.
-
-            Returns
-            -------
-            list
-                List of computed statistics: [detector_name, num_events, first_event_time,
-                last_event_time, avg_time_between_events, min_time_between_events, mean_event_rate].
-            """
-            num_acquisition = len(group["Time"])
-            first_event_time = group["Time"].min()
-            last_event_time = group["Time"].max()
-
-            time_diffs = group["Time"].diff().dropna()
-            time_between_events = time_diffs.mean()
-
-            return [
-                detector_name,
-                num_acquisition,
-                first_event_time,
-                last_event_time,
-                time_between_events,
-            ]

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

@@ -8,7 +8,7 @@ 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

{flowcypy-0.8.0 → flowcypy-0.8.1}/FlowCyPy/dataframe_subclass.py

@@ -5,6 +5,8 @@ import seaborn as sns
 from FlowCyPy import helper
 from MPSPlots.styles import mps
 from FlowCyPy import units
+import logging
+from tabulate import tabulate
 
 class ScattererDataFrame(pd.DataFrame):
     """
@@ -59,6 +61,83 @@ class ScattererDataFrame(pd.DataFrame):
 
         return grid
 
+    def log(self, table_format: str = "grid") -> None:
+        """
+        Logs detailed information about scatterer populations.
+
+        Parameters
+        ----------
+        table_format : str, optional
+            The format for the table display (default: 'grid').
+            Options include 'plain', 'github', 'grid', 'fancy_grid', etc.
+
+        Returns
+        -------
+        None
+            Logs scatterer population information, including refractive index, size, particle count,
+            number of events, and time statistics.
+        """
+        logging.info("\n=== Scatterer Population Properties ===")
+
+        # Collect general population data
+        general_table_data = [
+            self._get_population_properties(population)
+            for population in self.groupby("Population")
+        ]
+        general_headers = [
+            "Name",
+            "Refractive Index",
+            "Medium Refractive Index",
+            "Size",
+            "Particle Count",
+            "Number of Events",
+            "Min Time Between Events",
+            "Avg Time Between Events",
+        ]
+
+        formatted_general_table = tabulate(
+            general_table_data, headers=general_headers, tablefmt=table_format, floatfmt=".4f"
+        )
+        logging.info("\n" + formatted_general_table)
+
+    def _get_population_properties(self, population_group: tuple) -> List[Union[str, float]]:
+        """
+        Extracts key properties of a scatterer population for the general properties table.
+
+        Parameters
+        ----------
+        population_group : tuple
+            A tuple containing the population name and its corresponding DataFrame.
+
+        Returns
+        -------
+        list
+            List of scatterer properties: [name, refractive index, medium refractive index, size,
+            particle count, number of events, min time between events, avg time between events].
+        """
+        population_name, population_df = population_group
+
+        name = population_name
+        refractive_index = f"{population_df['RefractiveIndex'].mean():~P}"
+        medium_refractive_index = f"{self.attrs['run_time']:~P}"  # Replace with actual medium refractive index if stored elsewhere
+        size = f"{population_df['Size'].mean():~P}"
+        particle_count = len(population_df)
+        num_events = particle_count
+
+        min_delta_position = population_df["Time"].diff().abs().min()
+        avg_delta_position = population_df["Time"].diff().mean()
+
+        return [
+            name,
+            refractive_index,
+            medium_refractive_index,
+            size,
+            particle_count,
+            num_events,
+            min_delta_position,
+            avg_delta_position,
+        ]
+
 class ContinuousAcquisitionDataFrame(pd.DataFrame):
     """
     A subclass of pandas DataFrame with a custom plot method.
@@ -213,6 +292,85 @@ class TriggeredAcquisitionDataFrame(pd.DataFrame):
         if show:
             plt.show()
 
+    def log(self, table_format: str = "grid", include_totals: bool = True) -> None:
+        """
+        Logs statistics about detector signals.
+
+        Parameters
+        ----------
+        table_format : str, optional
+            The format for the table display (default: 'grid').
+            Options include 'plain', 'github', 'grid', 'fancy_grid', etc.
+        include_totals : bool, optional
+            If True, logs the total number of events across all detectors (default: True).
+
+        Returns
+        -------
+        None
+            Logs details about detector signals, including event counts,
+            timing statistics, and mean event rates.
+        """
+        logging.info("\n=== Detector Signal Statistics ===")
+
+        # Compute statistics for each detector
+        if self.empty:
+            logging.warning("No data available for detectors.")
+            return
+
+        table_data = [
+            self._get_detector_stats(detector_name, self.xs(detector_name, level="Detector"))
+            for detector_name in self.index.get_level_values("Detector").unique()
+        ]
+        headers = [
+            "Detector",
+            "Number of Acquisition",
+            "First Event Time",
+            "Last Event Time",
+            "Time Between Events",
+        ]
+
+        formatted_table = tabulate(table_data, headers=headers, tablefmt=table_format, floatfmt=".3f")
+        logging.info("\n" + formatted_table)
+
+        if include_totals:
+            total_events = sum(stat[1] for stat in table_data)
+            logging.info(f"\nTotal number of events detected across all detectors: {total_events}")
+
+    def _get_detector_stats(self, detector_name: str, group: pd.DataFrame) -> list:
+        """
+        Computes statistics for a detector.
+
+        Parameters
+        ----------
+        detector_name : str
+            Name of the detector.
+        group : pd.DataFrame
+            DataFrame containing the detector data.
+
+        Returns
+        -------
+        list
+            List of computed statistics: [detector_name, num_events, first_event_time,
+            last_event_time, avg_time_between_events].
+        """
+        if group.empty:
+            return [detector_name, 0, None, None, None]
+
+        num_acquisition = len(group["Time"])
+        first_event_time = group["Time"].min()
+        last_event_time = group["Time"].max()
+
+        time_diffs = group["Time"].diff().dropna()
+        time_between_events = time_diffs.mean() if not time_diffs.empty else None
+
+        return [
+            detector_name,
+            num_acquisition,
+            first_event_time,
+            last_event_time,
+            time_between_events,
+        ]
+
 
 class ClassifierDataFrame(pd.DataFrame):
     """

{flowcypy-0.8.0 → flowcypy-0.8.1}/FlowCyPy/flow_cell.py

@@ -111,7 +111,10 @@ class FlowCell:
             if self.event_scheme.lower() == 'uniform-random':
                 numpy.random.shuffle(evenly_spaced_times.magnitude)
             event_dataframe['Time'] = PintArray(evenly_spaced_times.to(units.second).magnitude, units.second)
-        return ScattererDataFrame(event_dataframe)
+
+        scatterer_dataframe = ScattererDataFrame(event_dataframe)
+        scatterer_dataframe.attrs['run_time'] = run_time
+        return scatterer_dataframe
 
     def _generate_poisson_events(self, run_time: Quantity, population: Population) -> pd.DataFrame:
         """

{flowcypy-0.8.0 → flowcypy-0.8.1}/FlowCyPy/helper.py

@@ -33,6 +33,9 @@ def validate_units(**expected_units):
                 if arg_name in bound_args.arguments:
                     value = bound_args.arguments[arg_name]
 
+                    if value is None:
+                        continue
+
                     # 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)}")

flowcypy-0.8.1/FlowCyPy/triggered_acquisition.py

@@ -0,0 +1,200 @@
+import pandas as pd
+from FlowCyPy import units
+from scipy.signal import find_peaks
+from FlowCyPy.utils import bessel_lowpass_filter, dc_highpass_filter
+from FlowCyPy.dataframe_subclass import PeakDataFrame
+from FlowCyPy.helper import validate_units
+import pint_pandas
+
+class TriggeredAcquisitions:
+    """
+    A class for handling and processing triggered acquisition data,
+    including peak detection and signal filtering.
+    """
+
+    def __init__(self, parent, dataframe: pd.DataFrame):
+        """
+        Initializes the TriggeredAcquisitions instance.
+
+        Parameters
+        ----------
+        parent : object
+            Parent object containing cytometer and detector metadata.
+        dataframe : pd.DataFrame
+            Dataframe containing the acquired signals.
+        """
+        self.signal = dataframe
+        self.parent = parent
+
+        self.detect_peaks()
+
+    def get_detector(self, name: str):
+        """
+        Retrieves a detector instance by name.
+
+        Parameters
+        ----------
+        name : str
+            Name of the detector to retrieve.
+
+        Returns
+        -------
+        object or None
+            Detector object if found, otherwise None.
+        """
+        for detector in self.parent.cytometer.detectors:
+            if detector.name == name:
+                return detector
+
+    def detect_peaks(self, multi_peak_strategy: str = 'max') -> None:
+        """
+        Detects peaks for each segment and stores results in a DataFrame.
+
+        Parameters
+        ----------
+        multi_peak_strategy : str, optional
+            Strategy for handling multiple peaks in a segment. Options are:
+            - 'max': Take the maximum peak in the segment.
+            - 'mean': Take the average of the peaks in the segment.
+            - 'sum': Sum all peaks in the segment.
+            - 'discard': Remove entries with multiple peaks.
+            - 'keep': Keep all peaks without aggregation.
+            Default is 'max'.
+        """
+        if multi_peak_strategy not in {'max', 'mean', 'sum', 'discard', 'keep'}:
+            raise ValueError("Invalid multi_peak_strategy. Choose from 'max', 'mean', 'sum', 'discard', 'keep'.")
+
+        def process_segment(segment):
+            signal = segment['DigitizedSignal'].values
+            time = segment['Time'].values
+            peaks, properties = find_peaks(signal, width=1)
+
+            return pd.DataFrame({
+                "SegmentID": segment.name[1],
+                "Detector": segment.name[0],
+                "Height": signal[peaks],
+                "Time": time[peaks],
+                **{k: v for k, v in properties.items()}
+            })
+
+        # Process peaks for each group
+        results = self.signal.groupby(level=['Detector', 'SegmentID']).apply(process_segment)
+        results = results.reset_index(drop=True)
+
+        # Process multi-peak strategies
+        _temp = results.reset_index()[['Detector', 'SegmentID', 'Height']].pint.dequantify().droplevel('unit', axis=1)
+
+        self.peaks = (
+            results.reset_index()
+            .loc[_temp.groupby(['Detector', 'SegmentID'])['Height'].idxmax()]
+            .set_index(['Detector', 'SegmentID'])
+        )
+
+        return PeakDataFrame(self.peaks)
+
+    def _apply_lowpass_filter(self, cutoff_freq: units.Quantity, order: int = 4) -> None:
+        """
+        Applies a Bessel low-pass filter to the signal data in-place.
+
+        Parameters
+        ----------
+        cutoff_freq : units.Quantity
+            The cutoff frequency for the low-pass filter (must have frequency units).
+        order : int, optional
+            The order of the Bessel filter, default is 4.
+
+        Raises
+        ------
+        ValueError
+            If cutoff frequency is missing or exceeds Nyquist frequency.
+        TypeError
+            If signal data is not stored as a PintArray.
+        """
+        if cutoff_freq is None:
+            raise ValueError("Cutoff frequency must be specified for low-pass filtering.")
+
+        # Get sampling frequency and ensure it's in Hertz
+        fs = self.parent.cytometer.signal_digitizer.sampling_freq.to("hertz")
+        nyquist_freq = fs / 2
+
+        # Validate cutoff frequency
+        if cutoff_freq.to("hertz") >= nyquist_freq:
+            raise ValueError(f"Cutoff frequency ({cutoff_freq}) must be below the Nyquist frequency ({nyquist_freq}).")
+
+        # Ensure the signal column is a PintArray
+        if not isinstance(self.signal["DigitizedSignal"].array, pint_pandas.PintArray):
+            raise TypeError("Expected 'DigitizedSignal' to be a PintArray, but got a different type.")
+
+        # Iterate through each detector-segment pair and apply filtering
+        for (detector, segment_id), segment_data in self.signal.groupby(level=['Detector', 'SegmentID']):
+            filtered_values = bessel_lowpass_filter(
+                signal=segment_data["DigitizedSignal"].pint.quantity.magnitude,
+                cutoff=cutoff_freq,
+                sampling_rate=fs,
+                order=order
+            )
+
+            # Ensure values remain as a PintArray and keep original units
+            self.signal.loc[(detector, segment_id), "DigitizedSignal"] = filtered_values.astype(int)
+
+    def _apply_highpass_filter(self, cutoff_freq: units.Quantity, order: int = 4) -> None:
+        """
+        Applies a DC high-pass filter to the signal data in-place.
+
+        Parameters
+        ----------
+        cutoff_freq : units.Quantity
+            The cutoff frequency for the high-pass filter (must have frequency units).
+        order : int, optional
+            The order of the high-pass filter, default is 4.
+
+        Raises
+        ------
+        ValueError
+            If cutoff frequency is missing or exceeds Nyquist frequency.
+        TypeError
+            If signal data is not stored as a PintArray.
+        """
+        if cutoff_freq is None:
+            raise ValueError("Cutoff frequency must be specified for high-pass filtering.")
+
+        # Get sampling frequency and ensure it's in Hertz
+        fs = self.parent.cytometer.signal_digitizer.sampling_freq.to("hertz")
+        nyquist_freq = fs / 2
+
+        # Validate cutoff frequency
+        if cutoff_freq.to("hertz") >= nyquist_freq:
+            raise ValueError(f"Cutoff frequency ({cutoff_freq}) must be below the Nyquist frequency ({nyquist_freq}).")
+
+        # Ensure the signal column is a PintArray
+        if not isinstance(self.signal["DigitizedSignal"].array, pint_pandas.PintArray):
+            raise TypeError("Expected 'DigitizedSignal' to be a PintArray, but got a different type.")
+
+        # Iterate through each detector-segment pair and apply filtering
+        for (detector, segment_id), segment_data in self.signal.groupby(level=['Detector', 'SegmentID']):
+            filtered_values = dc_highpass_filter(
+                signal=segment_data["DigitizedSignal"].pint.quantity.magnitude,
+                cutoff=cutoff_freq,
+                sampling_rate=fs,
+                order=order
+            )
+
+            # Ensure values remain as a PintArray and keep original units
+            self.signal.loc[(detector, segment_id), "DigitizedSignal"] = filtered_values.astype(int)
+
+    @validate_units(low_cutoff=units.hertz, high_cutoff=units.hertz)
+    def apply_filters(self, low_cutoff: units.Quantity = None, high_cutoff: units.Quantity = None) -> None:
+        """
+        Applies low-pass and/or high-pass filters to the signal data in-place.
+
+        Parameters
+        ----------
+        low_cutoff : units.Quantity, optional
+            The cutoff frequency for the low-pass filter. If None, no low-pass filtering is applied.
+        high_cutoff : units.Quantity, optional
+            The cutoff frequency for the high-pass filter. If None, no high-pass filtering is applied.
+        """
+        if low_cutoff is not None:
+            self._apply_lowpass_filter(low_cutoff)
+        if high_cutoff is not None:
+            self._apply_highpass_filter(high_cutoff)