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

fucciphase/fucci_phase.py

@@ -1,3 +1,4 @@
+import logging
 from pathlib import Path
 
 import pandas as pd
@@ -7,6 +8,8 @@ from .phase import generate_cycle_phases
 from .sensor import FUCCISensor
 from .utils import normalize_channels, split_trackmate_tracks
 
+logger = logging.getLogger(__name__)
+
 
 def process_dataframe(
     df: pd.DataFrame,
@@ -91,6 +94,25 @@ def process_dataframe(
     if len(channels) != sensor.fluorophores:
         raise ValueError(f"Need to provide {sensor.fluorophores} channel names.")
 
+    # validate DataFrame is not empty
+    if df.empty:
+        raise ValueError("Input DataFrame is empty.")
+
+    # validate that required channel columns exist
+    missing_channels = [ch for ch in channels if ch not in df.columns]
+    if missing_channels:
+        raise ValueError(
+            f"Missing channel columns in DataFrame: {missing_channels}. "
+            f"Available columns: {list(df.columns)}"
+        )
+
+    # validate that FRAME column exists (required for processing)
+    if "FRAME" not in df.columns:
+        raise ValueError(
+            "Missing required 'FRAME' column in DataFrame. "
+            f"Available columns: {list(df.columns)}"
+        )
+
     # optionally split TrackMate subtracks and re-label them as unique tracks
     if generate_unique_tracks:
         if "TRACK_ID" in df.columns:
@@ -98,8 +120,10 @@ def process_dataframe(
             # perform all operation on unique tracks
             track_id_name = "UNIQUE_TRACK_ID"
         else:
-            print("Warning: unique tracks can only be prepared for TrackMate files.")
-            print("The tracks have not been updated.")
+            logger.warning(
+                "Unique tracks can only be prepared for TrackMate files. "
+                "The tracks have not been updated."
+            )
 
     # normalize the channels
     normalize_channels(

fucciphase/io.py

@@ -27,7 +27,7 @@ def read_trackmate_xml(xml_path: Path | str) -> tuple[pd.DataFrame, TrackMateXML
     # convert the spots to a dataframe
     df = trackmate.to_pandas()
     # sort by frame number to have increasing time
-    df.sort_values(by="FRAME")
+    df = df.sort_values(by="FRAME")
 
     return df, trackmate
 
@@ -61,10 +61,7 @@ def read_trackmate_csv(csv_path: Path | str) -> pd.DataFrame:
     df = pd.read_csv(csv_path, encoding="unicode_escape", skiprows=[1, 2, 3])
 
     # sanity check: trackmate must have at least two channels
-    if (
-        "MEAN_INTENSITY_CH1" not in df.columns
-        and "MEAN_INTENSITY_CH2" not in df.columns
-    ):
+    if "MEAN_INTENSITY_CH1" not in df.columns or "MEAN_INTENSITY_CH2" not in df.columns:
         raise ValueError("Trackmate must have at least two channels.")
 
     # return dataframe with converted types (object -> string)

fucciphase/main_cli.py

@@ -1,5 +1,6 @@
 import argparse
 import json
+import logging
 from pathlib import Path
 
 import pandas as pd
@@ -9,12 +10,10 @@ from fucciphase.napari import add_trackmate_data_to_viewer
 from fucciphase.phase import estimate_percentage_by_subsequence_alignment
 from fucciphase.sensor import FUCCISASensor, get_fuccisa_default_sensor
 
-try:
-    import napari
-except ImportError as err:
-    raise ImportError("Install napari.") from err
+logger = logging.getLogger(__name__)
 
 
+# ruff: noqa: C901
 def main_cli() -> None:
     """Fucciphase CLI: Command-line entry point for FUCCIphase.
 
@@ -40,6 +39,11 @@ def main_cli() -> None:
     not return a value. It will raise a ``ValueError`` if the tracking
     file does not have an XML or CSV extension.
     """
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(levelname)s - %(name)s - %(message)s",
+    )
+
     parser = argparse.ArgumentParser(
         prog="fucciphase",
         description="FUCCIphase tool to estimate cell cycle phases and percentages.",
@@ -81,9 +85,8 @@ def main_cli() -> None:
     )
     parser.add_argument(
         "--generate_unique_tracks",
-        type=bool,
+        action="store_true",
         help="Split subtracks (TrackMate specific)",
-        default=False,
     )
 
     args = parser.parse_args()
@@ -92,17 +95,39 @@ def main_cli() -> None:
     output_dir.mkdir(exist_ok=True)
 
     # ---------------- 2. Load and adapt the reference cell-cycle trace ----------------
-    reference_df = pd.read_csv(args.reference_file)
+    try:
+        reference_df = pd.read_csv(args.reference_file)
+    except FileNotFoundError:
+        raise FileNotFoundError(
+            f"Reference file not found: {args.reference_file}"
+        ) from None
+    except pd.errors.EmptyDataError:
+        raise ValueError(f"Reference file is empty: {args.reference_file}") from None
+    except pd.errors.ParserError as e:
+        raise ValueError(
+            f"Failed to parse reference file {args.reference_file}: {e}"
+        ) from None
+
     # The reference file is expected to contain 'cyan' and 'magenta' columns;
     # they are renamed here to match the actual channel names in the data.
     reference_df.rename(
         columns={"cyan": args.cyan_channel, "magenta": args.magenta_channel},
         inplace=True,
     )
+
     # ---------------- 3. Build the sensor model ----------------
     if args.sensor_file is not None:
-        with open(args.sensor_file) as fp:
-            sensor_properties = json.load(fp)
+        try:
+            with open(args.sensor_file) as fp:
+                sensor_properties = json.load(fp)
+        except FileNotFoundError:
+            raise FileNotFoundError(
+                f"Sensor file not found: {args.sensor_file}"
+            ) from None
+        except json.JSONDecodeError as e:
+            raise ValueError(
+                f"Invalid JSON in sensor file {args.sensor_file}: {e}"
+            ) from None
         sensor = FUCCISASensor(**sensor_properties)
     else:
         sensor = get_fuccisa_default_sensor()
@@ -120,7 +145,18 @@ def main_cli() -> None:
         )
     elif args.tracking_file.endswith(".csv"):
         # CSV: read the table and then run the processing pipeline on it
-        df = pd.read_csv(args.tracking_file)
+        try:
+            df = pd.read_csv(args.tracking_file)
+        except FileNotFoundError:
+            raise FileNotFoundError(
+                f"Tracking file not found: {args.tracking_file}"
+            ) from None
+        except pd.errors.EmptyDataError:
+            raise ValueError(f"Tracking file is empty: {args.tracking_file}") from None
+        except pd.errors.ParserError as e:
+            raise ValueError(
+                f"Failed to parse tracking file {args.tracking_file}: {e}"
+            ) from None
         process_dataframe(
             df,
             channels=[args.cyan_channel, args.magenta_channel],
@@ -166,6 +202,16 @@ def main_visualization() -> None:
     console script and does not return a value.
 
     """
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(levelname)s - %(name)s - %(message)s",
+    )
+
+    try:
+        import napari
+    except ImportError as err:
+        raise ImportError("Install napari.") from err
+
     parser = argparse.ArgumentParser(
         prog="fucciphase-napari",
         description="FUCCIphase napari script to launch visualization.",
@@ -211,24 +257,24 @@ def main_visualization() -> None:
 
     # Try to read the video using AICSImage; fall back to bioio if needed
     AICSIMAGE = False
-    BIOIMAGE = False
     try:
         from aicsimageio import AICSImage
 
         AICSIMAGE = True
-    except ImportError as err:
-        from bioio import BioImage
-
-        BIOIMAGE = True
-        import bioio_ome_tiff
-
-        if not BIOIMAGE:
+    except ImportError:
+        try:
+            import bioio_ome_tiff
+            from bioio import BioImage
+        except ImportError as err:
             raise ImportError(
-                "Please install AICSImage or bioio to read videos"
+                "Please install aicsimageio or bioio to read videos. "
+                "Install with: pip install aicsimageio "
+                "or pip install bioio bioio-ome-tiff"
             ) from err
+
     if AICSIMAGE:
         image = AICSImage(args.video)
-    elif BIOIMAGE:
+    else:
         image = BioImage(args.video, reader=bioio_ome_tiff.Reader)
 
     # Determine spatial scale; fall back to unit scale or user-provided pixel size
@@ -237,12 +283,24 @@ def main_visualization() -> None:
         if args.pixel_size is not None:
             scale = (args.pixel_size, args.pixel_size)
         else:
-            print("WARNING: No pixel sizes found, using unit scale")
+            logger.warning("No pixel sizes found in image metadata, using unit scale")
             scale = (1.0, 1.0)
     cyan = image.get_image_dask_data("TYX", C=args.cyan_channel)
     magenta = image.get_image_dask_data("TYX", C=args.magenta_channel)
     masks = image.get_image_dask_data("TYX", C=args.segmask_channel)
-    track_df = pd.read_csv(args.fucciphase_file)
+
+    try:
+        track_df = pd.read_csv(args.fucciphase_file)
+    except FileNotFoundError:
+        raise FileNotFoundError(
+            f"FUCCIphase file not found: {args.fucciphase_file}"
+        ) from None
+    except pd.errors.EmptyDataError:
+        raise ValueError(f"FUCCIphase file is empty: {args.fucciphase_file}") from None
+    except pd.errors.ParserError as e:
+        raise ValueError(
+            f"Failed to parse FUCCIphase file {args.fucciphase_file}: {e}"
+        ) from None
 
     viewer = napari.Viewer()
 
@@ -257,7 +315,3 @@ def main_visualization() -> None:
         textkwargs={"size": 14},
     )
     napari.run()
-
-
-if __name__ == "__main__":
-    main_cli()

fucciphase/napari/tracks_to_napari.py

@@ -104,12 +104,13 @@ def pandas_df_to_napari_tracks(
     track_data = track_df[
         [unique_track_id_name, frame_id_name, position_y_name, position_x_name]
     ].to_numpy()
-    if track_df[feature_name].min() < 0 or track_df[feature_name].max() > 100.0:
-        raise ValueError(
-            "Make sure that the features are between 0 and 1, "
-            "otherwise the colormapping does not work well"
-        )
+
     features = None
     if feature_name is not None:
+        if track_df[feature_name].min() < 0 or track_df[feature_name].max() > 100.0:
+            raise ValueError(
+                "Make sure that the features are between 0 and 1, "
+                "otherwise the colormapping does not work well"
+            )
         features = {feature_name: track_df[feature_name].to_numpy()}
     viewer.add_tracks(track_data, features=features, colormaps_dict=colormaps_dict)

fucciphase/phase.py

@@ -1,11 +1,13 @@
+import logging
 from enum import Enum
+from typing import Literal
 
 import dtaidistance.preprocessing
 import numpy as np
 import pandas as pd
 from dtaidistance.dtw import warping_amount
 from dtaidistance.subsequence.dtw import subsequence_alignment
-from scipy import interpolate, stats
+from scipy import interpolate, signal, stats
 
 from .sensor import FUCCISensor
 from .utils import (
@@ -15,6 +17,11 @@ from .utils import (
     get_time_distortion_coefficient,
 )
 
+logger = logging.getLogger(__name__)
+
+# Type alias for signal processing mode
+SignalMode = Literal["signal", "derivative", "both"]
+
 
 class NewColumns(str, Enum):
     """Columns generated by the analysis.
@@ -336,6 +343,144 @@ def estimate_cell_phase_from_background(
     df[NewColumns.discrete_phase_bg()] = pd.Series(phase_names, dtype=str)  # add as str
 
 
+def _process_channel(
+    series: np.ndarray,
+    signal_mode: SignalMode,
+    smooth: float,
+    channel_name: str = "",
+    signal_smooth: int = 0,
+) -> list[np.ndarray]:
+    """Process a single channel according to the signal mode.
+
+    Parameters
+    ----------
+    series : np.ndarray
+        The input signal array.
+    signal_mode : SignalMode
+        Processing mode: "signal", "derivative", or "both".
+    smooth : float
+        Smoothing factor for differencing (removes high frequencies).
+    channel_name : str, optional
+        Channel name for warning messages.
+    signal_smooth : int, optional
+        Window size for signal smoothing (Savitzky-Golay filter with polyorder=3).
+        0 means no smoothing. Must be > 3 if used.
+        Only applies when signal_mode is "signal" or "both".
+
+    Returns
+    -------
+    list[np.ndarray]
+        List of processed arrays. Length 1 for "signal" or "derivative",
+        length 2 for "both" (signal first, then derivative).
+    """
+    results = []
+
+    if signal_mode in ("signal", "both"):
+        smoothed_signal = series.copy()
+        if signal_smooth > 3:
+            smoothed_signal = signal.savgol_filter(
+                series, window_length=signal_smooth, polyorder=3, mode="nearest"
+            )
+        elif signal_smooth > 0:
+            logger.warning(
+                "signal_smooth=%d is too small (must be > 3), skipping smoothing",
+                signal_smooth,
+            )
+        results.append(smoothed_signal)
+
+    if signal_mode in ("derivative", "both"):
+        try:
+            diff = dtaidistance.preprocessing.differencing(series, smooth=smooth)
+        except ValueError:
+            if channel_name:
+                logger.warning(
+                    "Smoothing failed for channel %s, continuing without smoothing",
+                    channel_name,
+                )
+            diff = dtaidistance.preprocessing.differencing(series)
+        results.append(diff)
+
+    return results
+
+
+def _compute_both_mode_scale_factor(processed_series: list[np.ndarray]) -> float:
+    """Compute scale factor to balance signal and derivative contributions.
+
+    In "both" mode, signals and derivatives may have different magnitudes.
+    This function computes a scale factor to apply to signals so they
+    contribute equally to the DTW distance.
+
+    Parameters
+    ----------
+    processed_series : list[np.ndarray]
+        List of processed arrays in order:
+        [signal_ch1, deriv_ch1, signal_ch2, deriv_ch2, ...]
+
+    Returns
+    -------
+    float
+        Scale factor to multiply signals by. Returns 1.0 if derivatives have zero std.
+    """
+    # In "both" mode, signals are at even indices, derivatives at odd indices
+    signals = [processed_series[i] for i in range(0, len(processed_series), 2)]
+    derivatives = [processed_series[i] for i in range(1, len(processed_series), 2)]
+
+    signal_std = np.mean([np.std(s) for s in signals])
+    deriv_std = np.mean([np.std(d) for d in derivatives])
+
+    if signal_std == 0:
+        return 1.0
+    return deriv_std / signal_std  # type: ignore[no-any-return]
+
+
+def _apply_both_mode_scaling(
+    processed_series: list[np.ndarray], scale_factor: float
+) -> list[np.ndarray]:
+    """Apply scale factor to signal features in "both" mode.
+
+    Parameters
+    ----------
+    processed_series : list[np.ndarray]
+        List of processed arrays in order:
+        [signal_ch1, deriv_ch1, signal_ch2, deriv_ch2, ...]
+    scale_factor : float
+        Scale factor to multiply signals by.
+
+    Returns
+    -------
+    list[np.ndarray]
+        Scaled processed series with signals multiplied by scale_factor.
+    """
+    scaled = []
+    for i, arr in enumerate(processed_series):
+        if i % 2 == 0:  # Signal (even index)
+            scaled.append(arr * scale_factor)
+        else:  # Derivative (odd index)
+            scaled.append(arr)
+    return scaled
+
+
+def _compute_output_length_offset(signal_mode: SignalMode) -> int:
+    """Return the offset to add to query length for output array size.
+
+    When using derivatives, the output is 1 element shorter, so we need
+    to add 1 to get back to the original track length.
+
+    Parameters
+    ----------
+    signal_mode : SignalMode
+        The signal processing mode.
+
+    Returns
+    -------
+    int
+        Offset to add: 1 if derivative is used, 0 otherwise.
+    """
+    if signal_mode in ("derivative", "both"):
+        return 1
+    return 0
+
+
 # flake8: noqa: C901
 def estimate_percentage_by_subsequence_alignment(
     df: pd.DataFrame,
@@ -347,7 +492,10 @@ def estimate_percentage_by_subsequence_alignment(
     track_id_name: str = "TRACK_ID",
     minimum_track_length: int = 10,
     use_zscore_norm: bool = True,
-    use_derivative: bool = True,
+    signal_mode: SignalMode = "derivative",
+    signal_weight: float = 1.0,
+    signal_smooth: int = 0,
+    use_derivative: bool | None = None,
 ) -> None:
     """Use subsequence alignment to estimate percentage.
 
@@ -362,7 +510,7 @@ def estimate_percentage_by_subsequence_alignment(
     reference_data: pd.DataFrame
         Containing reference intensities over time
     smooth: float
-        Smoothing factor, see dtaidistance documentation
+        Smoothing factor for derivative (removes high frequencies, 0-0.5)
     penalty: float
         Penalty for DTW algorithm, enforces diagonal warping path
     track_id_name: str
@@ -373,10 +521,34 @@ def estimate_percentage_by_subsequence_alignment(
         Use z-score normalization before differencing curves
         Probably not needed if intensities of reference and measured
         curve are similar
-    use_derivative: bool
-        Take derivative to perform alignment independent of intensity
-        baseline (in default mode also after normalization)
+    signal_mode: SignalMode
+        Signal processing mode:
+        - "signal": use raw signal only
+        - "derivative": use derivative only (default, for baseline independence)
+        - "both": use both signal and derivative as features
+    signal_weight: float
+        Weight for signal relative to derivative in "both" mode.
+        Default 1.0 means equal contribution. Values > 1.0 weight signal
+        higher, values < 1.0 weight derivative higher. Ignored for other modes.
+    signal_smooth: int
+        Window size for signal smoothing (Savitzky-Golay filter, polyorder=3).
+        0 means no smoothing. Must be > 3 if used.
+        Only applies in "signal" or "both" modes.
+    use_derivative: bool | None
+        Deprecated. Use signal_mode instead. If provided, overrides signal_mode
+        for backward compatibility (True -> "derivative", False -> "signal").
     """
+    # Handle backward compatibility with use_derivative parameter
+    if use_derivative is not None:
+        import warnings
+
+        warnings.warn(
+            "use_derivative is deprecated, use signal_mode instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        signal_mode = "derivative" if use_derivative else "signal"
+
     if "time" not in reference_data:
         raise ValueError("Need to provide time column in reference_data.")
     if "percentage" not in reference_data:
@@ -398,33 +570,48 @@ def estimate_percentage_by_subsequence_alignment(
 
     num_time = int(time_scale[-1] / dt)
     new_time_scale = np.linspace(0, dt * num_time, num=num_time + 1)
-    assert np.isclose(dt, new_time_scale[1] - new_time_scale[0])
+    actual_dt = new_time_scale[1] - new_time_scale[0]
+    if not np.isclose(dt, actual_dt):
+        raise ValueError(
+            f"Time scale mismatch: requested dt={dt}, but computed dt={actual_dt}. "
+            "Check that the reference data time scale is compatible with "
+            "the requested timestep."
+        )
 
     # reference curve in time scale of provided track
     percentage_ref = f_percentage(new_time_scale)
 
-    series_diff = []
+    processed_series = []
     for channel in channels:
         series = interpolation_functions[channel](new_time_scale)
         if use_zscore_norm:
             series = stats.zscore(series)
-        # if all values are the same, we zero to not numerical issues
+        # if all values are the same, we zero to avoid numerical issues
         if np.all(np.isnan(series)):
-            series = 0.0
-
-        if use_derivative:
-            try:
-                diff_ch = dtaidistance.preprocessing.differencing(series, smooth=smooth)
-            except ValueError:
-                print(
-                    "WARNING: The smoothing failed, continue without smoothing"
-                    f" for channel {channel}"
-                )
-            diff_ch = dtaidistance.preprocessing.differencing(series)
-        else:
-            diff_ch = series
-        series_diff.append(diff_ch)
-    series = np.array(series_diff)
+            series = np.zeros_like(series)
+
+        channel_features = _process_channel(
+            series, signal_mode, smooth, channel, signal_smooth
+        )
+        processed_series.extend(channel_features)
+
+    # For "both" mode, trim signal features to match derivative length and scale
+    both_mode_scale_factor = 1.0
+    if signal_mode == "both":
+        min_len = min(len(s) for s in processed_series)
+        processed_series = [s[-min_len:] for s in processed_series]
+        # Also trim the percentage reference to match
+        percentage_ref = percentage_ref[-min_len:]
+        # Compute and apply scaling to balance signal and derivative contributions
+        # signal_weight > 1.0 weights signal higher relative to derivative
+        both_mode_scale_factor = (
+            _compute_both_mode_scale_factor(processed_series) * signal_weight
+        )
+        processed_series = _apply_both_mode_scaling(
+            processed_series, both_mode_scale_factor
+        )
+
+    series = np.array(processed_series)
     series = np.swapaxes(series, 0, 1)
 
     df.loc[:, NewColumns.cell_cycle_dtw()] = np.nan
@@ -444,37 +631,48 @@ def estimate_percentage_by_subsequence_alignment(
         # find percentages if track is long enough
         queries = track_df[channels].to_numpy()
 
-        queries_diff = []
+        processed_queries = []
         for idx in range(len(channels)):
+            query_series = queries[:, idx].copy()
             if use_zscore_norm:
-                queries[:, idx] = stats.zscore(queries[:, idx])
-            # if all values are the same, we zero to not numerical issues
-            if np.all(np.isnan(queries[:, idx])):
-                queries[:, idx] = 0.0
-            if use_derivative:
-                diff_ch = dtaidistance.preprocessing.differencing(
-                    queries[:, idx], smooth=smooth
-                )
-            else:
-                diff_ch = queries[:, idx]
-            queries_diff.append(diff_ch)
+                query_series = stats.zscore(query_series)
+            # if all values are the same, we zero to avoid numerical issues
+            if np.all(np.isnan(query_series)):
+                query_series = np.zeros_like(query_series)
 
-        query = np.array(queries_diff)
+            channel_features = _process_channel(
+                query_series, signal_mode, smooth, signal_smooth=signal_smooth
+            )
+            processed_queries.extend(channel_features)
+
+        # For "both" mode, trim signal features to match derivative length and scale
+        if signal_mode == "both":
+            min_len = min(len(q) for q in processed_queries)
+            processed_queries = [q[-min_len:] for q in processed_queries]
+            # Apply same scale factor as reference to ensure consistent weighting
+            processed_queries = _apply_both_mode_scaling(
+                processed_queries, both_mode_scale_factor
+            )
+
+        query = np.array(processed_queries)
         query = np.swapaxes(query, 0, 1)
 
         sa = subsequence_alignment(query, series, penalty=penalty)
         best_match = sa.best_match()
-        if use_derivative:
-            new_percentage = np.zeros(query.shape[0] + 1)
-        else:
-            new_percentage = np.zeros(query.shape[0])
-        for p in best_match.path:
-            new_percentage[p[0]] = percentage_ref[p[1]]
-        if p[1] + 1 < len(percentage_ref):
-            last_percentage = p[1] + 1
+        length_offset = _compute_output_length_offset(signal_mode)
+        new_percentage = np.zeros(query.shape[0] + length_offset)
+
+        # Handle empty path case
+        if len(best_match.path) == 0:
+            new_percentage[:] = np.nan
         else:
-            last_percentage = p[1]
-        new_percentage[-1] = percentage_ref[last_percentage]
+            for p in best_match.path:
+                new_percentage[p[0]] = percentage_ref[p[1]]
+            if p[1] + 1 < len(percentage_ref):
+                last_percentage = p[1] + 1
+            else:
+                last_percentage = p[1]
+            new_percentage[-1] = percentage_ref[last_percentage]
         # save estimated cell cycle percentages
         df.loc[df[track_id_name] == track_id, NewColumns.cell_cycle_dtw()] = (
             new_percentage[:]
@@ -484,21 +682,33 @@ def estimate_percentage_by_subsequence_alignment(
             best_match.value
         )
 
-        _, distortion_score, _, _ = get_time_distortion_coefficient(best_match.path)
-        # save DTW distortion
-        df.loc[df[track_id_name] == track_id, NewColumns.dtw_distortion()] = (
-            distortion_score
-        )
-        df.loc[df[track_id_name] == track_id, NewColumns.dtw_distortion_norm()] = (
-            distortion_score / len(track_df)
-        )
+        # Handle empty path case for DTW metrics
+        if len(best_match.path) == 0:
+            df.loc[df[track_id_name] == track_id, NewColumns.dtw_distortion()] = np.nan
+            df.loc[df[track_id_name] == track_id, NewColumns.dtw_distortion_norm()] = (
+                np.nan
+            )
+            df.loc[df[track_id_name] == track_id, NewColumns.dtw_warping_amount()] = (
+                np.nan
+            )
+            df.loc[
+                df[track_id_name] == track_id, NewColumns.rel_dtw_warping_amount()
+            ] = np.nan
+        else:
+            _, distortion_score, _, _ = get_time_distortion_coefficient(best_match.path)
+            # save DTW distortion
+            df.loc[df[track_id_name] == track_id, NewColumns.dtw_distortion()] = (
+                distortion_score
+            )
+            df.loc[df[track_id_name] == track_id, NewColumns.dtw_distortion_norm()] = (
+                distortion_score / len(track_df)
+            )
 
-        # save DTW warping amount
-        df.loc[df[track_id_name] == track_id, NewColumns.dtw_warping_amount()] = (
-            warping_amount(best_match.path)
-        )
+            # save DTW warping amount
+            df.loc[df[track_id_name] == track_id, NewColumns.dtw_warping_amount()] = (
+                warping_amount(best_match.path)
+            )
 
-        # save DTW warping amount
-        df.loc[df[track_id_name] == track_id, NewColumns.rel_dtw_warping_amount()] = (
-            warping_amount(best_match.path) / len(track_df)
-        )
+            df.loc[
+                df[track_id_name] == track_id, NewColumns.rel_dtw_warping_amount()
+            ] = warping_amount(best_match.path) / len(track_df)

fucciphase/plot.py

@@ -1,3 +1,4 @@
+import logging
 from itertools import cycle
 
 import numpy as np
@@ -11,6 +12,8 @@ from scipy import interpolate
 from .phase import NewColumns
 from .utils import get_norm_channel_name
 
+logger = logging.getLogger(__name__)
+
 
 def set_phase_colors(
     df: pd.DataFrame, colordict: dict, phase_column: str = "DISCRETE_PHASE_MAX"
@@ -569,7 +572,7 @@ def get_percentage_color(percentage: float) -> tuple:
     cmap_name = "cool"
     cmap = colormaps.get(cmap_name)
     if np.isnan(percentage):
-        print("WARNING: NaN value detected, plot will be transparent")
+        logger.warning("NaN percentage value detected, plot will be transparent")
         rgba_value = (0, 0, 0, 0)
     else:
         rgba_value = cmap(percentage / 100.0)

fucciphase/sensor.py

@@ -1,3 +1,4 @@
+import logging
 from abc import ABC, abstractmethod
 from typing import Union
 
@@ -5,6 +6,8 @@ import numpy as np
 import pandas as pd
 from scipy import optimize
 
+logger = logging.getLogger(__name__)
+
 
 def logistic(
     x: float | np.ndarray, center: float, sigma: float, sign: float = 1.0
@@ -273,8 +276,8 @@ 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)
 
@@ -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":

fucciphase/tracking_utilities.py

@@ -29,7 +29,13 @@ def get_feature_value_at_frame(
         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])
 
 

fucciphase/utils/normalize.py

@@ -35,21 +35,44 @@ def get_avg_channel_name(channel: str) -> str:
     return f"{channel}_AVG"
 
 
-def norm(vector: pd.Series | np.ndarray) -> 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
@@ -148,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)
@@ -186,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/track_postprocessing.py

@@ -1,3 +1,5 @@
+import logging
+
 import matplotlib.pyplot as plt
 import numpy as np
 import pandas as pd
@@ -5,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,
@@ -91,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
@@ -382,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"

fucciphase/utils/trackmate.py

@@ -55,9 +55,26 @@ class TrackMateXML:
         ----------
         xml_path : Union[str, Path]
             Path to the xml file.
+
+        Raises
+        ------
+        FileNotFoundError
+            If the XML file does not exist.
+        ValueError
+            If the XML file is malformed or not a valid TrackMate file.
         """
         # parse tree
-        self._tree: et.ElementTree[et.Element[str]] = et.parse(xml_path)
+        xml_path = Path(xml_path)
+        if not xml_path.exists():
+            raise FileNotFoundError(f"TrackMate XML file not found: {xml_path}")
+
+        try:
+            self._tree: et.ElementTree[et.Element[str]] = et.parse(xml_path)
+        except et.ParseError as e:
+            raise ValueError(
+                f"Failed to parse TrackMate XML file {xml_path}: {e}"
+            ) from None
+
         self._root: et.Element | Any = self._tree.getroot()
 
         # placeholders

{fucciphase-0.0.3.dist-info → fucciphase-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fucciphase
-Version: 0.0.3
+Version: 0.0.4
 Summary: Cell cycle analysis plugin.
 Project-URL: homepage, https://github.com/nobias-ht/fucciphase
 Project-URL: repository, https://github.com/nobias-ht/fucciphase
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Requires-Dist: dtaidistance
 Requires-Dist: lineagetree<1.5.0
 Requires-Dist: matplotlib

fucciphase-0.0.4.dist-info/RECORD

@@ -0,0 +1,25 @@
+fucciphase/__init__.py,sha256=HkyHcSzLlTlEIz7E3bvuINGBqfnIL0s6oPU0EE_pQCs,545
+fucciphase/__main__.py,sha256=lXUDkaeNRAZep5O7dNLj9RY4EclpPolruAll0FFC_jo,298
+fucciphase/fucci_phase.py,sha256=34EmEaG_jEGvRMBocPRYfBYXSJpko3_nYUgP013Bkjo,8990
+fucciphase/io.py,sha256=5a8Qre5KCT1haoqsB8FELyPKM7hzPM9kcEBGclokSPA,2018
+fucciphase/main_cli.py,sha256=870EiTIxck_vHczeZ0Go9Ia42d9UTgWtHoNfm0Q9BJ0,11036
+fucciphase/phase.py,sha256=wxBJoglCtnLTpZwJ2j1kUeKZMb3y3pqeKakjMSIn1bw,25450
+fucciphase/plot.py,sha256=0bLCJBdfR-I7_qNDurY4iJyeV8D0GqBTvHZO4NSNTlk,24212
+fucciphase/py.typed,sha256=esB4cHc6c07uVkGtqf8at7ttEnprwRxwk8obY8Qumq4,187
+fucciphase/sensor.py,sha256=XVshjhe6ix8FO5xmICLF7ovBCf_JcEkD328tU40-dj0,15172
+fucciphase/tracking_utilities.py,sha256=dJ0q903_aF7bJyARU7wPeRjX6r7b-sHWJVOyXucpMcI,4825
+fucciphase/napari/__init__.py,sha256=At9Shk6HfDf6obtQaM0yKG4NOZVO6YxD2-J1M2ZGm7w,198
+fucciphase/napari/tracks_to_napari.py,sha256=ITqm_aw1uRG-RIfuxoC-zJLCDmrxjduWbiWC69xGzMM,4060
+fucciphase/utils/__init__.py,sha256=YwgK2COtG44QJaXHVPYKu2-Ifm6GIG1ahykvJ4pr-MM,1408
+fucciphase/utils/checks.py,sha256=o4mMGJMIE5wlaf0jtblnTD4JGTfjc5W7ZS4tYDIPlLo,625
+fucciphase/utils/dtw.py,sha256=6RJ5wZ8jDFKSVmcYajsdTJ4tfe3E-wKROEA2rWyGRN4,1638
+fucciphase/utils/normalize.py,sha256=EyVDeMJrDu02XfSwt0jIUecAlTN9v9BAS2KdU5wKk_c,7173
+fucciphase/utils/phase_fit.py,sha256=tiZ7rVkPvFokf7ghhGfkcdr1udjptUU4HmKu53EL3LQ,1835
+fucciphase/utils/simulator.py,sha256=fV-Pj6APms3QbYmiD9TjEYYkTqkIWk0uKDLCpz36HmA,2323
+fucciphase/utils/track_postprocessing.py,sha256=AOm4N4WACzKymX7vz74HWeAIQx556OQ5IS6uHZHgvHw,14500
+fucciphase/utils/trackmate.py,sha256=NeP8vCQEAGiKwz2O0kDmmvJtkxHN6LBtDwkAHsZJrvg,11131
+fucciphase-0.0.4.dist-info/METADATA,sha256=JNqZF53wGiKLnWceUHEYXj1sim9p8TgftwNoRrnWHrk,9019
+fucciphase-0.0.4.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+fucciphase-0.0.4.dist-info/entry_points.txt,sha256=B77Cm5QnxeQz6DEfqD6n7zDw48-HrlepWPwLbdVITMY,119
+fucciphase-0.0.4.dist-info/licenses/LICENSE,sha256=pQGrOGpOTwikEzkZ8Zc9XLQwbaZ85TMJP-GaWCNZciw,1554
+fucciphase-0.0.4.dist-info/RECORD,,

fucciphase-0.0.3.dist-info/RECORD

@@ -1,25 +0,0 @@
-fucciphase/__init__.py,sha256=HkyHcSzLlTlEIz7E3bvuINGBqfnIL0s6oPU0EE_pQCs,545
-fucciphase/__main__.py,sha256=lXUDkaeNRAZep5O7dNLj9RY4EclpPolruAll0FFC_jo,298
-fucciphase/fucci_phase.py,sha256=aR50chW5JAs-56R2vezINnMX_QkNT1nwGgqYLVreDVQ,8237
-fucciphase/io.py,sha256=oleF2KmW5uE_cV2PQx5bTka1Aw69kLIO-200ZQpuiAQ,2038
-fucciphase/main_cli.py,sha256=3wh32o91BV8J4309CxhN5tW--MOYgFId8eQWkCjdXg8,8958
-fucciphase/phase.py,sha256=uZNMK7Odd07kNh8SbmsrZpTolEGdRBGE0o2sGbocZhw,17684
-fucciphase/plot.py,sha256=E04VF7ejAUb8uC1pVRGxw7sS9A9_uaO51h6bVvu1aWc,24148
-fucciphase/py.typed,sha256=esB4cHc6c07uVkGtqf8at7ttEnprwRxwk8obY8Qumq4,187
-fucciphase/sensor.py,sha256=LSIVC0MfJncMjovUriAiFRTaEmEnClbjnsxqIgId6FQ,14714
-fucciphase/tracking_utilities.py,sha256=vnjCFGS2vArnCuxBlw7852eN2Xhd-FIo63bVWkHV0Lo,4548
-fucciphase/napari/__init__.py,sha256=At9Shk6HfDf6obtQaM0yKG4NOZVO6YxD2-J1M2ZGm7w,198
-fucciphase/napari/tracks_to_napari.py,sha256=_Dknd1wwXj9VJzo3y8Ry6lgJni9VokfZWVq_z98RlfE,4039
-fucciphase/utils/__init__.py,sha256=YwgK2COtG44QJaXHVPYKu2-Ifm6GIG1ahykvJ4pr-MM,1408
-fucciphase/utils/checks.py,sha256=o4mMGJMIE5wlaf0jtblnTD4JGTfjc5W7ZS4tYDIPlLo,625
-fucciphase/utils/dtw.py,sha256=6RJ5wZ8jDFKSVmcYajsdTJ4tfe3E-wKROEA2rWyGRN4,1638
-fucciphase/utils/normalize.py,sha256=xaZ_1Mgw6fd3RouuYkfwRGKr4DimSwmVq-ghRcTxFpc,5964
-fucciphase/utils/phase_fit.py,sha256=Ht_dEyuLYonv6is9qQ-Xd95pQR7IR-8C8mv0ckDcp4E,1743
-fucciphase/utils/simulator.py,sha256=fV-Pj6APms3QbYmiD9TjEYYkTqkIWk0uKDLCpz36HmA,2323
-fucciphase/utils/track_postprocessing.py,sha256=lv7TLBaGF4lOqlJUsl80rt1Igue2lM7WfmxIZXKwk3E,14388
-fucciphase/utils/trackmate.py,sha256=rbgARawfefSmvaRjfzmYF_XWqUPDZnBQCgU1s9Ev_00,10612
-fucciphase-0.0.3.dist-info/METADATA,sha256=YeQuzOiDo64ltvCliaWgk6H_OJJ1aCQnYufl4U1cSvQ,9018
-fucciphase-0.0.3.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-fucciphase-0.0.3.dist-info/entry_points.txt,sha256=B77Cm5QnxeQz6DEfqD6n7zDw48-HrlepWPwLbdVITMY,119
-fucciphase-0.0.3.dist-info/licenses/LICENSE,sha256=pQGrOGpOTwikEzkZ8Zc9XLQwbaZ85TMJP-GaWCNZciw,1554
-fucciphase-0.0.3.dist-info/RECORD,,