FlowCyPy 0.12.0__cp312-cp312-win_amd64.whl

FlowCyPy/__init__.py

@@ -0,0 +1,18 @@
+try:
+    from ._version import version as __version__  # noqa: F401
+
+except ImportError:
+    __version__ = "0.0.0"
+
+from PyMieSim.experiment.detector import CoherentMode
+from PyMieSim.experiment.scatterer import Sphere
+from PyMieSim.experiment.source import Gaussian, PlaneWave
+from PyMieSim.experiment import Setup
+from .cytometer import FlowCytometer
+from .scatterer_collection import ScattererCollection, CouplingModel
+from .population import Population
+from .detector import Detector
+from .flow_cell import FlowCell
+from .source import GaussianBeam
+from .noises import NoiseSetting
+from .signal_digitizer import SignalDigitizer

FlowCyPy/_version.py

@@ -0,0 +1,21 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = ["__version__", "__version_tuple__", "version", "version_tuple"]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+else:
+    VERSION_TUPLE = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+
+__version__ = version = '0.12.0'
+__version_tuple__ = version_tuple = (0, 12, 0)

FlowCyPy/acquisition.py

@@ -0,0 +1,182 @@
+from typing import List
+import warnings
+import pandas as pd
+from FlowCyPy import units
+from FlowCyPy import dataframe_subclass
+from FlowCyPy.triggered_acquisition import TriggeredAcquisitions
+from FlowCyPy.binary import triggering_system
+import pint_pandas
+
+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.analog = detector_dataframe
+        self.scatterer = scatterer_dataframe
+        self.run_time = run_time
+
+    @property
+    def n_detectors(self) -> int:
+        return len(self.detector_names)
+
+    @property
+    def detector_names(self) -> List[str]:
+        return self.analog.index.get_level_values('Detector').unique()
+
+    @property
+    def signal_digitizer(self) -> object:
+        return self.cytometer.signal_digitizer
+
+    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.
+        """
+        # Ensure the trigger detector exists
+        if trigger_detector_name not in self.detector_names:
+            raise ValueError(f"Detector '{trigger_detector_name}' not found in dataset.")
+
+        signal_length = pre_buffer + post_buffer
+
+        # Convert threshold to plain numeric value
+        threshold_value = threshold.to(self.analog['Signal'].pint.units).magnitude
+
+        # Prepare detector-specific signal & time mappings for C++ function
+        signal_units = self.analog.xs(self.detector_names[0])['Signal'].pint.units
+        time_units = self.analog.xs(self.detector_names[0])['Time'].pint.units
+
+        signal_map = {det: self.analog.xs(det)['Signal'].pint.to(signal_units).pint.magnitude.to_numpy(copy=False) for det in self.detector_names}
+        time_map = {det: self.analog.xs(det)['Time'].pint.to(time_units).pint.magnitude.to_numpy(copy=False) for det in self.detector_names}
+
+        # Call the C++ function for fast triggering detection
+        times, signals, detectors, segment_ids = triggering_system.run(
+            signal_map=signal_map,
+            time_map=time_map,
+            trigger_detector_name=trigger_detector_name,
+            threshold=threshold_value,
+            pre_buffer=pre_buffer,
+            post_buffer=post_buffer,
+            max_triggers=max_triggers or -1
+        )
+
+        # Convert back to PintArray (restore units)
+        times = pint_pandas.PintArray(times, time_units)
+        signals = pint_pandas.PintArray(signals, signal_units)
+
+        # If no triggers are found, warn the user and return None
+        if len(times) == 0:
+            warnings.warn(
+                f"No signal met the trigger criteria. Try adjusting the threshold. "
+                f"Signal min-max: {self.analog['Signal'].min().to_compact()}, {self.analog['Signal'].max().to_compact()}",
+                UserWarning
+            )
+            return None
+
+        # Convert NumPy arrays to Pandas DataFrame
+        triggered_signal = pd.DataFrame({
+            "Time": times,
+            "Signal": signals,
+            "Detector": detectors,
+            "SegmentID": segment_ids
+        }).set_index(['Detector', 'SegmentID'])
+
+        # Create a specialized DataFrame class
+        triggered_signal = dataframe_subclass.TriggeredAnalogAcquisitionDataFrame(triggered_signal)
+
+        # Copy metadata attributes
+        triggered_signal.attrs['bit_depth'] = self.analog.attrs.get('bit_depth', None)
+        triggered_signal.attrs['saturation_levels'] = self.analog.attrs.get('saturation_levels', None)
+        triggered_signal.attrs['scatterer_dataframe'] = self.analog.attrs.get('scatterer_dataframe', None)
+        triggered_signal.attrs['threshold'] = {'detector': trigger_detector_name, 'value': threshold}
+
+        # Wrap inside a TriggeredAcquisitions object
+        triggered_acquisition = TriggeredAcquisitions(parent=self, dataframe=triggered_signal)
+        triggered_acquisition.scatterer = self.scatterer
+        triggered_acquisition.signal_length = signal_length
+
+        return triggered_acquisition
+
+
+    @property
+    def digital(self) -> pd.DataFrame:
+        dataframe = dataframe_subclass.DigitizedAcquisitionDataFrame(
+            index=self.analog.index,
+            data=dict(Time=self.analog.Time)
+        )
+
+        dataframe.attrs['saturation_levels'] = dict()
+        dataframe.attrs['scatterer_dataframe'] = self.analog.attrs.get('scatterer_dataframe', None)
+
+        for detector_name, group in self.analog.groupby('Detector'):
+            digitized_signal, _ = self.signal_digitizer.capture_signal(signal=group['Signal'])
+
+            dataframe.attrs['saturation_levels'][detector_name] = [0, self.signal_digitizer.bit_depth]
+
+            dataframe.loc[detector_name, 'Signal'] = pint_pandas.PintArray(digitized_signal, units.bit_bins)
+
+        return dataframe

FlowCyPy/circuits.py

@@ -0,0 +1,125 @@
+from abc import ABC, abstractmethod
+import numpy as np
+from FlowCyPy.binary import filtering
+from FlowCyPy.helper import validate_units
+from FlowCyPy import units
+
+class SignalProcessor(ABC):
+    """
+    Abstract base class for signal processing operations.
+    """
+    @abstractmethod
+    def apply(self, signal: np.ndarray) -> None:
+        """
+        Applies a signal processing transformation **in-place**.
+
+        Parameters
+        ----------
+        signal : np.ndarray
+            The signal to be modified in-place.
+        """
+        pass
+
+class BaselineRestorator(SignalProcessor):
+    """
+    Applies a baseline restoration filter by subtracting the minimum value over a given window size.
+
+    Parameters
+    ----------
+    window_size : int
+        Number of past samples to consider for the minimum value.
+        If set to -1, it acts as if the window is infinite.
+    """
+    def __init__(self, window_size: int):
+        self.window_size = window_size
+
+    def apply(self, signal: np.ndarray, sampling_rate: units.Quantity, **kwargs) -> np.ndarray:
+        """
+        Applies baseline restoration in-place.
+
+        Parameters
+        ----------
+        signal : np.ndarray
+            The signal to be modified in-place.
+        """
+        window_size_bin = int((self.window_size * sampling_rate).to('').magnitude)
+        filtering.apply_baseline_restoration(signal=signal, window_size=window_size_bin)
+
+        return signal
+
+
+class BesselLowPass(SignalProcessor):
+    """
+    Applies a Bessel low-pass filter to smooth the signal.
+
+    Parameters
+    ----------
+    cutoff : float
+        The cutoff frequency for the filter.
+    order : int
+        The order of the filter.
+    gain : float
+        The gain applied after filtering.
+    """
+    @validate_units(cutoff=units.hertz)
+    def __init__(self, cutoff: units.Quantity, order: int, gain: float):
+        self.cutoff = cutoff
+        self.order = order
+        self.gain = gain
+
+    def apply(self, signal: np.ndarray, sampling_rate: units.Quantity, **kwargs) -> None:
+        """
+        Applies Bessel low-pass filtering in-place.
+
+        Parameters
+        ----------
+        signal : np.ndarray
+            The signal to be modified in-place.
+        """
+        filtering.apply_bessel_lowpass_filter(
+            signal=signal,
+            sampling_rate=sampling_rate.to('hertz').magnitude,
+            cutoff=self.cutoff.to('hertz').magnitude,
+            order=self.order,
+            gain=self.gain
+        )
+
+        return signal
+
+class ButterworthlLowPass(SignalProcessor):
+    """
+    Applies a Bessel low-pass filter to smooth the signal.
+
+    Parameters
+    ----------
+    cutoff : float
+        The cutoff frequency for the filter.
+    order : int
+        The order of the filter.
+    gain : float
+        The gain applied after filtering.
+    """
+    @validate_units(cutoff=units.hertz)
+    def __init__(self, cutoff: units.Quantity, order: int, gain: float):
+        self.cutoff = cutoff
+        self.order = order
+        self.gain = gain
+
+    def apply(self, signal: np.ndarray, sampling_rate: units.Quantity, **kwargs) -> None:
+        """
+        Applies Bessel low-pass filtering in-place.
+
+        Parameters
+        ----------
+        signal : np.ndarray
+            The signal to be modified in-place.
+        """
+        filtering.apply_butterworth_lowpass_filter(
+            signal=signal,
+            sampling_rate=sampling_rate.to('hertz').magnitude,
+            cutoff=self.cutoff.to('hertz').magnitude,
+            order=self.order,
+            gain=self.gain
+        )
+
+        return signal

FlowCyPy/classifier.py

@@ -0,0 +1,182 @@
+from sklearn.cluster import KMeans
+from sklearn.cluster import DBSCAN
+from sklearn.mixture import GaussianMixture
+import pandas as pd
+from FlowCyPy.dataframe_subclass import ClassifierDataFrame
+
+
+class BaseClassifier:
+    def filter_dataframe(self, dataframe: pd.DataFrame, features: list, detectors: list = None) -> object:
+        """
+        Filter the DataFrame based on the selected features and detectors.
+
+        Parameters
+        ----------
+        features : list
+            List of features to use for filtering. Options include 'Heights', 'Widths', 'Areas'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+
+        Returns
+        -------
+        DataFrame
+            A filtered DataFrame containing only the selected detectors and features.
+
+        Raises
+        ------
+        ValueError
+            If no matching features are found for the given detectors and features.
+        """
+        # Determine detectors to use
+
+        if detectors is None:
+            detectors = dataframe.columns.get_level_values(1).unique().tolist()
+
+        return dataframe.loc[:, (features, detectors)]
+
+
+class KmeansClassifier(BaseClassifier):
+    def __init__(self, number_of_cluster: int) -> None:
+        """
+        Initialize the Classifier.
+
+        Parameters
+        ----------
+        dataframe : DataFrame
+            The input dataframe with multi-index columns.
+        """
+        self.number_of_cluster = number_of_cluster
+
+    def run(self, dataframe: pd.DataFrame, features: list = ['Height'], detectors: list = None, random_state: int = 42) -> pd.DataFrame:
+        """
+        Run KMeans clustering on the selected features and detectors.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            The input DataFrame with multi-index (e.g., by 'Detector').
+        features : list
+            List of features to use for clustering. Options include 'Height', 'Width', 'Area'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+        random_state : int, optional
+            Random state for KMeans, by default 42.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with clustering labels added.
+        """
+        # Filter the DataFrame
+        sub_dataframe = self.filter_dataframe(dataframe=dataframe, features=features, detectors=detectors)
+
+        # Ensure data is dequantified if it uses Pint quantities
+        if hasattr(sub_dataframe, 'pint'):
+            sub_dataframe = sub_dataframe.pint.dequantify().droplevel('unit', axis=1)
+
+        # Run KMeans
+        kmeans = KMeans(n_clusters=self.number_of_cluster, random_state=random_state)
+        labels = kmeans.fit_predict(sub_dataframe)
+
+        dataframe['Label'] = labels
+
+        return ClassifierDataFrame(dataframe)
+
+class GaussianMixtureClassifier(BaseClassifier):
+    def __init__(self, number_of_components: int) -> None:
+        """
+        Initialize the Gaussian Mixture Classifier.
+
+        Parameters
+        ----------
+        number_of_components : int
+            Number of Gaussian components (clusters) to use for the model.
+        """
+        self.number_of_components = number_of_components
+
+    def run(self, dataframe: pd.DataFrame, features: list = ['Height'], detectors: list = None, random_state: int = 42) -> pd.DataFrame:
+        """
+        Run Gaussian Mixture Model (GMM) clustering on the selected features and detectors.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            The input DataFrame with multi-index (e.g., by 'Detector').
+        features : list
+            List of features to use for clustering. Options include 'Height', 'Width', 'Area'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+        random_state : int, optional
+            Random state for reproducibility, by default 42.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with clustering labels added.
+        """
+        # Filter the DataFrame
+        sub_dataframe = self.filter_dataframe(dataframe=dataframe, features=features, detectors=detectors)
+
+        # Ensure data is dequantified if it uses Pint quantities
+        if hasattr(sub_dataframe, 'pint'):
+            sub_dataframe = sub_dataframe.pint.dequantify().droplevel('unit', axis=1)
+
+        # Run Gaussian Mixture Model
+        gmm = GaussianMixture(n_components=self.number_of_components, random_state=random_state)
+        labels = gmm.fit_predict(sub_dataframe)
+
+        # Add labels to the original DataFrame
+        dataframe['Label'] = labels
+
+        return ClassifierDataFrame(dataframe)
+
+class DBSCANClassifier(BaseClassifier):
+    def __init__(self, epsilon: float = 0.5, min_samples: int = 5) -> None:
+        """
+        Initialize the DBSCAN Classifier.
+
+        Parameters
+        ----------
+        epsilon : float, optional
+            The maximum distance between two samples for them to be considered as neighbors.
+            Default is 0.5.
+        min_samples : int, optional
+            The number of samples in a neighborhood for a point to be considered a core point.
+            Default is 5.
+        """
+        self.epsilon = epsilon
+        self.min_samples = min_samples
+
+    def run(self, dataframe: pd.DataFrame, features: list = ['Height'], detectors: list = None) -> pd.DataFrame:
+        """
+        Run DBSCAN clustering on the selected features and detectors.
+
+        Parameters
+        ----------
+        dataframe : pd.DataFrame
+            The input DataFrame with multi-index (e.g., by 'Detector').
+        features : list
+            List of features to use for clustering. Options include 'Height', 'Width', 'Area'.
+        detectors : list, optional
+            List of detectors to use. If None, use all detectors.
+
+        Returns
+        -------
+        pd.DataFrame
+            DataFrame with clustering labels added. Noise points are labeled as -1.
+        """
+        # Filter the DataFrame
+        sub_dataframe = self.filter_dataframe(dataframe=dataframe, features=features, detectors=detectors)
+
+        # Ensure data is dequantified if it uses Pint quantities
+        if hasattr(sub_dataframe, 'pint'):
+            sub_dataframe = sub_dataframe.pint.dequantify().droplevel('unit', axis=1)
+
+        # Run DBSCAN
+        dbscan = DBSCAN(eps=self.epsilon, min_samples=self.min_samples)
+        labels = dbscan.fit_predict(sub_dataframe)
+
+        # Add labels to the original DataFrame
+        dataframe['Label'] = labels
+
+        return ClassifierDataFrame(dataframe)

FlowCyPy/coupling_mechanism/__init__.py

@@ -0,0 +1,4 @@
+from . import uniform
+from . import rayleigh
+from . import mie
+from . import empirical

FlowCyPy/coupling_mechanism/empirical.py

@@ -0,0 +1,47 @@
+import numpy as np
+from FlowCyPy import ScattererCollection, Detector
+from FlowCyPy.source import BaseBeam
+from FlowCyPy.units import watt, meter
+
+
+def compute_detected_signal(source: BaseBeam, detector: Detector, scatterer: ScattererCollection, granularity: float = 1.0, A: float = 1.5, n: float = 2.0) -> float:
+    """
+    Empirical model for scattering intensity based on particle size, granularity, and detector angle.
+
+    This function models forward scatter (FSC) as proportional to the particle's size squared and
+    side scatter (SSC) as proportional to the granularity and modulated by angular dependence
+    (sin^n(theta)). Granularity is a dimensionless measure of the particle's internal complexity or
+    surface irregularities:
+
+    - A default value of 1.0 is used for moderate granularity (e.g., typical white blood cells).
+    - Granularity values < 1.0 represent smoother particles with less internal complexity (e.g., bacteria).
+    - Granularity values > 1.0 represent particles with higher internal complexity or surface irregularities (e.g., granulocytes).
+
+    Parameters
+    ----------
+    detector : Detector
+        The detector object containing theta_angle (in radians).
+    particle_size : float
+        The size of the particle (in meters).
+    granularity : float, optional
+        A measure of the particle's internal complexity or surface irregularities (dimensionless).
+        Default is 1.0.
+    A : float, optional
+        Empirical scaling factor for angular dependence. Default is 1.5.
+    n : float, optional
+        Power of sine function for angular dependence. Default is 2.0.
+
+    Returns
+    -------
+    float
+        The detected scattering intensity for the given particle and detector.
+    """
+    size_list = scatterer.dataframe['Size'].pint.to(meter).values.numpy_data
+
+    # Forward scatter is proportional to size^2
+    fsc_intensity = size_list**2
+
+    # Side scatter is proportional to granularity and modulated by angular dependence
+    ssc_intensity = granularity * (1 + A * np.sin(np.radians(detector.phi_angle))**n) * np.ones_like(size_list)
+
+    return fsc_intensity * watt if detector.phi_angle < np.radians(10) else ssc_intensity * watt