fucciphase 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

fucciphase/sensor.py

@@ -1,14 +1,17 @@
+import logging
 from abc import ABC, abstractmethod
-from typing import List, Union
+from typing import Union
 
 import numpy as np
 import pandas as pd
 from scipy import optimize
 
+logger = logging.getLogger(__name__)
+
 
 def logistic(
-    x: Union[float, np.ndarray], center: float, sigma: float, sign: float = 1.0
-) -> Union[float, np.ndarray]:
+    x: float | np.ndarray, center: float, sigma: float, sign: float = 1.0
+) -> float | np.ndarray:
     """Logistic function."""
     tiny = 1.0e-15
     arg = sign * (x - center) / max(tiny, sigma)
@@ -16,21 +19,21 @@ def logistic(
 
 
 def accumulation_function(
-    x: Union[float, np.ndarray],
+    x: float | np.ndarray,
     center: float,
     sigma: float,
     offset_intensity: float = 0,
-) -> Union[float, np.ndarray]:
+) -> float | np.ndarray:
     """Function to describe accumulation of sensor."""
     return 1.0 - logistic(x, center, sigma) - offset_intensity
 
 
 def degradation_function(
-    x: Union[float, np.ndarray],
+    x: float | np.ndarray,
     center: float,
     sigma: float,
     offset_intensity: float = 0,
-) -> Union[float, np.ndarray]:
+) -> float | np.ndarray:
     """Function to describe degradation of sensor."""
     return 1.0 - logistic(x, center, sigma, sign=-1.0) - offset_intensity
 
@@ -41,9 +44,9 @@ class FUCCISensor(ABC):
     @abstractmethod
     def __init__(
         self,
-        phase_percentages: List[float],
-        center: List[float],
-        sigma: List[float],
+        phase_percentages: list[float],
+        center: list[float],
+        sigma: list[float],
     ) -> None:
         pass
 
@@ -55,17 +58,17 @@ class FUCCISensor(ABC):
 
     @property
     @abstractmethod
-    def phases(self) -> List[str]:
+    def phases(self) -> list[str]:
         """Function to hard-code the supported phases of a sensor."""
         pass
 
     @property
-    def phase_percentages(self) -> List[float]:
+    def phase_percentages(self) -> list[float]:
         """Percentage of individual phases."""
         return self._phase_percentages
 
     @phase_percentages.setter
-    def phase_percentages(self, values: List[float]) -> None:
+    def phase_percentages(self, values: list[float]) -> None:
         if len(values) != len(self.phases):
             raise ValueError("Pass percentage for each phase.")
 
@@ -76,25 +79,25 @@ class FUCCISensor(ABC):
         self._phase_percentages = values
 
     @abstractmethod
-    def get_phase(self, phase_markers: Union[List[bool], "pd.Series[bool]"]) -> str:
+    def get_phase(self, phase_markers: Union[list[bool], "pd.Series[bool]"]) -> str:
         """Get the discrete phase based on phase markers.
 
         Notes
         -----
-        Discrete phase refers to, for example, G1 or S phase.
+        The discrete phase refers to, for example, G1 or S phase.
         The phase_markers must match the number of used fluorophores.
         """
         pass
 
     @abstractmethod
     def get_estimated_cycle_percentage(
-        self, phase: str, intensities: List[float]
+        self, phase: str, intensities: list[float]
     ) -> float:
         """Estimate percentage based on sensor intensities."""
         pass
 
     def set_accumulation_and_degradation_parameters(
-        self, center: List[float], sigma: List[float]
+        self, center: list[float], sigma: list[float]
     ) -> None:
         """Pass list of functions for logistic functions.
 
@@ -114,8 +117,8 @@ class FUCCISensor(ABC):
 
     @abstractmethod
     def get_expected_intensities(
-        self, percentage: Union[float, np.ndarray]
-    ) -> List[Union[float, np.ndarray]]:
+        self, percentage: float | np.ndarray
+    ) -> list[float | np.ndarray]:
         """Return value of calibrated curves."""
         pass
 
@@ -124,7 +127,7 @@ class FUCCISASensor(FUCCISensor):
     """FUCCI(SA) sensor."""
 
     def __init__(
-        self, phase_percentages: List[float], center: List[float], sigma: List[float]
+        self, phase_percentages: list[float], center: list[float], sigma: list[float]
     ) -> None:
         self.phase_percentages = phase_percentages
         self.set_accumulation_and_degradation_parameters(center, sigma)
@@ -135,11 +138,11 @@ class FUCCISASensor(FUCCISensor):
         return 2
 
     @property
-    def phases(self) -> List[str]:
+    def phases(self) -> list[str]:
         """Function to hard-code the supported phases of a sensor."""
         return ["G1", "G1/S", "S/G2/M"]
 
-    def get_phase(self, phase_markers: Union[List[bool], "pd.Series[bool]"]) -> str:
+    def get_phase(self, phase_markers: Union[list[bool], "pd.Series[bool]"]) -> str:
         """Return the discrete phase based channel ON / OFF data for the
         FUCCI(SA) sensor.
         """
@@ -273,13 +276,13 @@ class FUCCISASensor(FUCCISensor):
                 )
             )
         except ValueError:
-            print(
-                "WARNING: could not infer percentage in SG2M phase, using average phase"
+            logger.warning(
+                "Could not infer percentage in SG2M phase, using average phase value"
             )
             return g1s_perc + 0.5 * (100.0 - g1s_perc - g1_perc)
 
     def get_estimated_cycle_percentage(
-        self, phase: str, intensities: List[float]
+        self, phase: str, intensities: list[float]
     ) -> float:
         """Estimate a cell cycle percentage based on intensities.
 
@@ -289,9 +292,20 @@ class FUCCISASensor(FUCCISensor):
             Name of phase
         intensities: List[float]
             List of channel intensities for all fluorophores
+
+        Raises
+        ------
+        ValueError
+            If the phase is not defined for this sensor or if the intensities
+            list does not have the expected number of elements.
         """
         if phase not in self.phases:
             raise ValueError(f"Phase {phase} is not defined for this sensor.")
+        if len(intensities) < self.fluorophores:
+            raise ValueError(
+                f"Expected {self.fluorophores} intensity values, "
+                f"but got {len(intensities)}."
+            )
         if phase == "G1":
             return self._find_g1_percentage(intensities[0])
         if phase == "G1/S":
@@ -300,8 +314,8 @@ class FUCCISASensor(FUCCISensor):
             return self._find_sg2m_percentage(intensities[1])
 
     def get_expected_intensities(
-        self, percentage: Union[float, np.ndarray]
-    ) -> List[Union[float, np.ndarray]]:
+        self, percentage: float | np.ndarray
+    ) -> list[float | np.ndarray]:
         """Return value of calibrated curves."""
         g1_acc = accumulation_function(
             percentage, self._center_values[0], self._sigma_values[0]
@@ -332,7 +346,7 @@ class PIPFUCCISensor(FUCCISensor):
     """PIP-FUCCI sensor."""
 
     def __init__(
-        self, phase_percentages: List[float], center: List[float], sigma: List[float]
+        self, phase_percentages: list[float], center: list[float], sigma: list[float]
     ) -> None:
         self.phase_percentages = phase_percentages
         self.set_accumulation_and_degradation_parameters(center, sigma)
@@ -343,11 +357,11 @@ class PIPFUCCISensor(FUCCISensor):
         return 2
 
     @property
-    def phases(self) -> List[str]:
+    def phases(self) -> list[str]:
         """Function to hard-code the supported phases of a sensor."""
         return ["G1", "S", "G2/M"]
 
-    def get_phase(self, phase_markers: Union[List[bool], "pd.Series[bool]"]) -> str:
+    def get_phase(self, phase_markers: Union[list[bool], "pd.Series[bool]"]) -> str:
         """Return the discrete phase based channel ON / OFF data for the
         FUCCI(SA) sensor.
         """
@@ -414,7 +428,7 @@ class PIPFUCCISensor(FUCCISensor):
         raise NotImplementedError("Percentage estimate not yet implemented!")
 
     def get_estimated_cycle_percentage(
-        self, phase: str, intensities: List[float]
+        self, phase: str, intensities: list[float]
     ) -> float:
         """Estimate a cell cycle percentage based on intensities.
 
@@ -437,8 +451,8 @@ class PIPFUCCISensor(FUCCISensor):
             return self._find_g2m_percentage(intensities[1])
 
     def get_expected_intensities(
-        self, percentage: Union[float, np.ndarray]
-    ) -> List[Union[float, np.ndarray]]:
+        self, percentage: float | np.ndarray
+    ) -> list[float | np.ndarray]:
         """Return value of calibrated curves."""
         raise NotImplementedError("Intensity estimate not yet implemented!")
 

fucciphase/tracking_utilities.py

@@ -4,9 +4,38 @@ import pandas as pd
 def get_feature_value_at_frame(
     labels: pd.DataFrame, label_name: str, label: int, feature: str
 ) -> float:
-    """Helper function to get value of feature."""
+    """
+    Helper function to get the value of a feature for a given label.
+
+    Parameters
+    ----------
+    labels : pandas.DataFrame
+        Dataframe containing at least the label and feature columns.
+    label_name : str
+        Column name containing label identifiers.
+    label : int
+        Label value to select.
+    feature : str
+        Column name of the feature whose value should be returned.
+
+    Returns
+    -------
+    float
+        The feature value corresponding to the specified label.
+
+    Raises
+    ------
+    ValueError
+        If zero or multiple rows match the requested label.
+    """
     value = labels[labels[label_name] == label, feature].to_numpy()
-    assert len(value) == 1
+    if len(value) == 0:
+        raise ValueError(f"No rows match label '{label}' in column '{label_name}'.")
+    if len(value) > 1:
+        raise ValueError(
+            f"Multiple rows ({len(value)}) match label '{label}' "
+            f"in column '{label_name}'. Expected exactly one match."
+        )
     return float(value[0])
 
 
@@ -18,21 +47,53 @@ def prepare_penalty_df(
     label_name: str = "LABEL",
     weight: float = 1.0,
 ) -> pd.DataFrame:
-    """Prepare a DF with penalties for tracking.
+    """Prepare a dataframe with penalties for tracking.
+
+    This function is intended to construct a cost / penalty matrix for
+    linking detections between consecutive frames, inspired by the
+    formulations used in LapTrack and TrackMate.
 
     Notes
     -----
     See more details here:
-    https://laptrack.readthedocs.io/en/stable/examples/custom_metric.html
+    - https://laptrack.readthedocs.io/en/stable/examples/custom_metric.html
+    - https://imagej.net/plugins/trackmate/trackers/lap-trackers#calculating-linking-costs
 
-    The penalty formulation is similar to TrackMate,
-    see
-    https://imagej.net/plugins/trackmate/trackers/lap-trackers#calculating-linking-costs
-    The penalty is computed as:
+    The intended penalty formulation is:
     P = 1 + sum(feature_penalties)
-    Each feature penalty is:
+    with each feature penalty of the form:
     p = 3 * weight * abs(f1 - f2) / (f1 + f2)
 
+    **Current status:** this function is not yet stably implemented and will
+    raise ``NotImplementedError`` if called. The prototype implementation
+    below is kept for future development.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Dataframe containing at least frame, label and feature columns.
+    feature_1 : str
+        Name of the first feature to use in the penalty.
+    feature_2 : str
+        Name of the second feature to use in the penalty.
+    frame_name : str, optional
+        Column name for frame indices. Default is ``"FRAME"``.
+    label_name : str, optional
+        Column name for object labels. Default is ``"LABEL"``.
+    weight : float, optional
+        Global scaling factor for feature penalties. Default is 1.0.
+
+    Returns
+    -------
+    pandas.DataFrame
+        Prototype would return a dataframe indexed by (frame, label1, label2)
+        with a ``penalty`` column.
+
+    Raises
+    ------
+    NotImplementedError
+        This function is currently not stable and is intentionally disabled.
+
     """
     raise NotImplementedError("This function is not yet stably implemented.")
 

fucciphase/utils/__init__.py

@@ -1,4 +1,17 @@
-"""Convenience functions for fucciphase."""
+"""
+Convenience functions for fucciphase - Utility submodule for FUCCIphase.
+
+This package collects helper functions used throughout FUCCIphase, including:
+- TrackMate XML parsing and rewriting
+- Channel normalization
+- Track splitting and postprocessing
+- Motility and lineage visualizations
+- Synthetic data generation
+- DTW time-distortion utilities
+
+Everything listed in ``__all__`` is considered part of the public FUCCIphase API.
+
+"""
 
 __all__ = [
     "TrackMateXML",

fucciphase/utils/checks.py

@@ -1,13 +1,10 @@
-from typing import List
-
-
-def check_channels(n_fluorophores: int, channels: List[str]) -> None:
+def check_channels(n_fluorophores: int, channels: list[str]) -> None:
     """Check number of channels."""
     if len(channels) != n_fluorophores:
         raise ValueError(f"Need to provide {n_fluorophores} channel names.")
 
 
-def check_thresholds(n_fluorophores: int, thresholds: List[float]) -> None:
+def check_thresholds(n_fluorophores: int, thresholds: list[float]) -> None:
     """Check correct format and range of thresholds."""
     if len(thresholds) != n_fluorophores:
         raise ValueError("Provide one threshold per channel.")

fucciphase/utils/dtw.py

@@ -1,10 +1,8 @@
-from typing import List, Union
-
 import numpy as np
 
 
 def get_time_distortion_coefficient(
-    path: Union[np.ndarray, List[List[float]]],
+    path: np.ndarray | list[list[float]],
 ) -> tuple[np.ndarray, float, int, int]:
     """Compute distortion coefficient from warping path.
 
@@ -20,7 +18,7 @@ def get_time_distortion_coefficient(
     lmbd = np.zeros(len(path) - 1)
     alpha = 0
     beta = 0
-    p: Union[np.ndarray, List[float]]
+    p: np.ndarray | list[float]
     for idx, p in enumerate(path):
         # first index is skipped
         if idx == 0:

fucciphase/utils/normalize.py

@@ -1,5 +1,3 @@
-from typing import List, Optional, Tuple, Union
-
 import numpy as np
 import pandas as pd
 from scipy import signal
@@ -37,21 +35,44 @@ def get_avg_channel_name(channel: str) -> str:
     return f"{channel}_AVG"
 
 
-def norm(vector: Union[pd.Series, np.ndarray]) -> Union[pd.Series, np.ndarray]:
+def norm(
+    vector: pd.Series | np.ndarray,
+    max_ch: float | None = None,
+    min_ch: float | None = None,
+) -> pd.Series | np.ndarray:
     """Normalize a vector by subtracting the min and dividing by (max - min).
 
     Parameters
     ----------
     vector : Union[pd.Series, np.ndarray]
         Vector to normalize.
+    max_ch: Optional[float]
+        Optional value for the maximum used in normalization
+    min_ch: Optional[float]
+        Optional value for the minimum used in normalization
 
     Returns
     -------
     Union[pd.Series, np.ndarray]
         Normalized vector.
+
+    Raises
+    ------
+    ValueError
+        If max_ch equals min_ch (constant signal), which would cause division by zero.
     """
-    max_ch = vector.max()
-    min_ch = vector.min()
+    if max_ch is None:
+        max_ch = vector.max()
+    if min_ch is None:
+        min_ch = vector.min()
+
+    # Check for division by zero (constant signal)
+    if np.isclose(max_ch, min_ch):
+        raise ValueError(
+            f"Cannot normalize: max ({max_ch}) equals min ({min_ch}). "
+            "The signal appears to be constant."
+        )
+
     norm_ch = np.round(
         (vector - min_ch) / (max_ch - min_ch),
         2,  # number of decimals
@@ -63,13 +84,13 @@ def norm(vector: Union[pd.Series, np.ndarray]) -> Union[pd.Series, np.ndarray]:
 # flake8: noqa: C901
 def normalize_channels(
     df: pd.DataFrame,
-    channels: Union[str, List[str]],
+    channels: str | list[str],
     use_moving_average: bool = True,
     moving_average_window: int = 7,
-    manual_min: Optional[List[float]] = None,
-    manual_max: Optional[List[float]] = None,
+    manual_min: list[float] | None = None,
+    manual_max: list[float] | None = None,
     track_id_name: str = "TRACK_ID",
-) -> List[str]:
+) -> list[str]:
     """Normalize channels, add in place the resulting columns to the
     dataframe, and return the new columns' name.
 
@@ -150,14 +171,22 @@ def normalize_channels(
                 df.loc[index, avg_channel] = ma
 
     # normalize channels
-    for channel in channels:
+    for idx, channel in enumerate(channels):
         # moving average creates a new column with an own name
         if use_moving_average:
             avg_channel = get_avg_channel_name(channel)
         else:
             avg_channel = channel
         # normalize channel
-        norm_ch = norm(df[avg_channel])
+        # default: compute max and min per channel
+        max_ch = None
+        min_ch = None
+        # if manually specified limits, overwrite
+        if manual_max is not None:
+            max_ch = manual_max[idx]
+        if manual_min is not None:
+            min_ch = manual_min[idx]
+        norm_ch = norm(df[avg_channel], max_ch=max_ch, min_ch=min_ch)
 
         # add the new column
         new_column = get_norm_channel_name(channel)
@@ -173,7 +202,7 @@ def smooth_track(
     channel: str,
     track_id_name: str,
     moving_average_window: int = 7,
-) -> Tuple[pd.Index, np.ndarray]:
+) -> tuple[pd.Index, np.ndarray]:
     """Smooth intensity in one channel for a single track.
 
     Parameters
@@ -188,10 +217,15 @@ def smooth_track(
         Name of column with track IDs
     moving_average_window : int
         Size of the window used for the moving average, default 7.
+        Must be greater than 3.
     """
     # get the track
     track: pd.DataFrame = df[df[track_id_name] == track_ID]
 
+    # hard-coded polyorder is 3, window length must be longer
+    if moving_average_window <= 3:
+        raise ValueError("Use moving_average_window of at least 4.")
+
     # compute the moving average
     ma = signal.savgol_filter(
         track[channel],

fucciphase/utils/phase_fit.py

@@ -1,7 +1,11 @@
+import logging
+
 import numpy as np
 import pandas as pd
 from monotonic_derivative import ensure_monotonic_derivative
 
+logger = logging.getLogger(__name__)
+
 
 def fit_percentages(frames: np.ndarray, percentages: np.ndarray) -> np.ndarray:
     """Fit estimated percentages to function with non-negative derivative."""
@@ -12,7 +16,7 @@ def fit_percentages(frames: np.ndarray, percentages: np.ndarray) -> np.ndarray:
         force_negative_derivative=False,
     )
     # clip to range (0, 100)
-    return np.clip(best_fit, 0.0, 100.0)
+    return np.clip(best_fit, 0.0, 100.0)  # type: ignore[no-any-return]
 
 
 def postprocess_estimated_percentages(
@@ -31,17 +35,17 @@ def postprocess_estimated_percentages(
         frames = track["FRAME"]
         percentages = track[percentage_column]
         if np.all(np.isnan(percentages)):
-            print("WARNING: No percentages to postprocess")
+            logger.warning("No percentages to postprocess")
             return
         try:
             restored_percentages = fit_percentages(frames, percentages)
         except ValueError:
-            print(f"Error in track {index}")
-            print(
-                "Make sure that the spots belong to a unique track,"
-                " i.e., not more than one spot per frame per track."
+            logger.error(
+                "Error in track %s. Make sure that the spots belong to a unique track, "
+                "i.e., not more than one spot per frame per track.\n%s",
+                index,
+                track,
             )
-            print(track)
         df.loc[df[track_id_name] == index, postprocessed_percentage_column] = (
             restored_percentages
         )

fucciphase/utils/simulator.py

@@ -47,7 +47,7 @@ def simulate_single_track(track_id: float = 42, mean: float = 0.5) -> pd.DataFra
     pd.DataFrame
         Dataframe mocking a Trackmate single track import.
     """
-    # example data
+    # examples data
     phase_percentages = [33.3, 33.3, 33.3]
     center = [20.0, 55.0, 70.0, 95.0]
     sigma = [5.0, 5.0, 10.0, 1.0]

fucciphase/utils/track_postprocessing.py

@@ -1,4 +1,4 @@
-from typing import List, Optional
+import logging
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -7,6 +7,8 @@ from LineageTree import lineageTree
 from matplotlib import colormaps
 from scipy import signal
 
+logger = logging.getLogger(__name__)
+
 
 def split_track(
     track: pd.DataFrame,
@@ -93,10 +95,13 @@ def split_all_tracks(
     """
     if track_id_name not in track_df.columns:
         raise ValueError(f"{track_id_name} column is missing.")
-    highest_track_idx = track_df[track_id_name].max()
-    highest_track_idx_counter = highest_track_idx
+
+    # Use unique() to handle non-contiguous track IDs correctly
+    track_ids = track_df[track_id_name].unique()
+    highest_track_idx_counter = track_df[track_id_name].max()
+
     # go through all tracks and split if needed
-    for track_idx in range(highest_track_idx):
+    for track_idx in track_ids:
         track = track_df.loc[track_df[track_id_name] == track_idx]
         if len(track) < minimum_track_length:
             continue
@@ -157,7 +162,7 @@ def compute_motility_parameters(
 
 
 def compute_displacements(
-    centroids_x: np.ndarray, centroids_y: np.ndarray, centroids_z: Optional[np.ndarray]
+    centroids_x: np.ndarray, centroids_y: np.ndarray, centroids_z: np.ndarray | None
 ) -> np.ndarray:
     """Compute displacement w.r.t origin."""
     N = len(centroids_x)
@@ -180,7 +185,7 @@ def compute_displacements(
 
 
 def compute_velocities(
-    centroids_x: np.ndarray, centroids_y: np.ndarray, centroids_z: Optional[np.ndarray]
+    centroids_x: np.ndarray, centroids_y: np.ndarray, centroids_z: np.ndarray | None
 ) -> np.ndarray:
     """Compute velocity."""
     N = len(centroids_x)
@@ -205,7 +210,7 @@ def compute_velocities(
 
 
 def compute_MSD(
-    centroids_x: np.ndarray, centroids_y: np.ndarray, centroids_z: Optional[np.ndarray]
+    centroids_x: np.ndarray, centroids_y: np.ndarray, centroids_z: np.ndarray | None
 ) -> np.ndarray:
     """Compute mean-squared distance.
 
@@ -357,9 +362,9 @@ def split_trackmate_tracks(
 def export_lineage_tree_to_svg(
     df: pd.DataFrame,
     trackmate_file: str,
-    node_color_column: Optional[str] = None,
-    stroke_width: Optional[float] = None,
-) -> List[str]:
+    node_color_column: str | None = None,
+    stroke_width: float | None = None,
+) -> list[str]:
     """Write a lineage tree colored by FUCCI phases.
 
     Parameters
@@ -384,7 +389,7 @@ def export_lineage_tree_to_svg(
     This function currently only supports
     the standard FUCCISA sensor.
     """
-    print("Warning: make sure that you updated the spot names using TrackMate actions!")
+    logger.warning("Make sure that you updated the spot names using TrackMate actions!")
     # initialise lineage tree
     lt = lineageTree(trackmate_file, file_type="TrackMate")
     cmap_name = "cool"