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

fucciphase/__init__.py

@@ -1,4 +1,10 @@
-"""Cell cycle analysis plugin."""
+"""
+FUCCIphase: Analysis tools for cell-cycle estimation from FUCCI imaging.
+
+This module exposes the main public API of the package, including the
+core processing functions and the package version.
+
+"""
 
 from importlib.metadata import PackageNotFoundError, version
 

fucciphase/__main__.py

@@ -0,0 +1,12 @@
+"""
+Module entry point for ``python -m fucciphase``.
+
+This thin wrapper forwards execution to :func:`fucciphase.main_cli.main_cli`,
+which implements the command-line interface used by the ``fucciphase``
+console script.
+"""
+
+from .main_cli import main_cli
+
+if __name__ == "__main__":
+    main_cli()

fucciphase/fucci_phase.py

@@ -1,5 +1,4 @@
 from pathlib import Path
-from typing import List, Optional, Union
 
 import pandas as pd
 
@@ -11,20 +10,28 @@ from .utils import normalize_channels, split_trackmate_tracks
 
 def process_dataframe(
     df: pd.DataFrame,
-    channels: List[str],
+    channels: list[str],
     sensor: FUCCISensor,
-    thresholds: List[float],
+    thresholds: list[float],
     use_moving_average: bool = True,
     window_size: 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,
     generate_unique_tracks: bool = False,
     track_id_name: str = "TRACK_ID",
     label_id_name: str = "name",
     estimate_percentage: bool = True,
 ) -> None:
-    """Process a pd.DataFrame by computing the cell cycle percentage from two FUCCI
-    cycle reporter channels in place.
+    """Apply the FUCCIphase analysis pipeline to an existing dataframe.
+
+    This function assumes that tracking and fluorescence information are
+    already available in a pandas DataFrame with the expected column
+    structure. It performs the same core steps as ``process_trackmate``,
+    but skips the TrackMate file I/O and starts directly from tabular data.
+
+    Use this when your tracking pipeline already provides a dataframe, or
+    when you have manually assembled the input table and still want to use
+    FUCCIphase for cell-cycle analysis and visualization.
 
     The dataframe must contain ID and TRACK_ID features.
 
@@ -38,34 +45,53 @@ def process_dataframe(
     Parameters
     ----------
     df : pandas.DataFrame
-        Dataframe
+        Input dataframe containing tracking and intensity features.
+
     channels: List[str]
-        Names of channels holding FUCCI information
+         Names of columns holding FUCCI fluorescence information.
+
     sensor : FUCCISensor
-        FUCCI sensor with phase specifics
+        FUCCI sensor with phase-specific parameters.
+
     thresholds: List[float]
-        Thresholds to separate phases
+        Thresholds used to separate cell-cycle phases.
+
     use_moving_average : bool, optional
-        Use moving average before normalization, by default True
+        If True, apply a moving average before normalization. Default is True.
+
     window_size : int, optional
-        Window size of the moving average, by default 5
+        Window size of the moving average. Default is 7.
+
     manual_min : Optional[List[float]], optional
         Manually determined minimum for each channel, by default None
+
     manual_max : Optional[List[float]], optional
         Manually determined maximum for each channel, by default None
-    estimate_percentage: bool
-        Estimate cell cycle percentage
-    label_id_name: str
-        Give an indentifier for the spot name (needed for unique track ID generation)
+
     generate_unique_tracks: bool
-        Assign unique track IDs to splitted tracks.
-        Requires usage of action in TrackMate.
+        If True, assign unique track IDs to split tracks. This requires
+        using the appropriate action in TrackMate. Default is False.
+
     track_id_name: str
-        Name of column with track IDs
+        Name of the column containing track IDs. Default is ``"TRACK_ID"``.
+
+    label_id_name: str
+        Column name identifying the spot label / name (used for unique
+        track ID generation). Default is ``"name"``.
+
+    estimate_percentage: bool, optional
+        If True, estimate cell-cycle percentage along each track. Default is True.
+
+    Returns
+    -------
+    None
+        The input dataframe is modified in-place. No value is returned.
     """
+    # ensure that the number of provided channels matches the sensor definition
     if len(channels) != sensor.fluorophores:
         raise ValueError(f"Need to provide {sensor.fluorophores} channel names.")
 
+    # optionally split TrackMate subtracks and re-label them as unique tracks
     if generate_unique_tracks:
         if "TRACK_ID" in df.columns:
             split_trackmate_tracks(df, label_id_name=label_id_name)
@@ -86,7 +112,7 @@ def process_dataframe(
         track_id_name=track_id_name,
     )
 
-    # compute the phases
+    # compute the phases (and, optionally, the cycle percentage)
     generate_cycle_phases(
         df,
         sensor=sensor,
@@ -97,20 +123,29 @@ def process_dataframe(
 
 
 def process_trackmate(
-    xml_path: Union[str, Path],
-    channels: List[str],
+    xml_path: str | Path,
+    channels: list[str],
     sensor: FUCCISensor,
-    thresholds: List[float],
+    thresholds: list[float],
     use_moving_average: bool = True,
     window_size: 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,
     generate_unique_tracks: bool = False,
     estimate_percentage: bool = True,
+    output_dir: str | Path | None = None,
 ) -> pd.DataFrame:
-    """Process a trackmate XML file, compute cell cycle percentage from two FUCCI cycle
-    reporter channels, save an updated copy of the XML and return the results in a
-    dataframe.
+    """Run the full FUCCIphase pipeline on a TrackMate export.
+
+    This high-level helper takes tracking data exported from Fiji/TrackMate
+    (typically XML or CSV), converts it into a pandas DataFrame with the
+    expected fucciphase columns, applies basic quality checks and
+    preprocessing, and estimates cell-cycle phase information that can be
+    used for downstream analysis and plotting.
+
+    The returned table is intended to be the main entry point for
+    fucciphase workflows, and is compatible with the plotting and
+    visualization functions provided in this package.
 
     This function applies the following steps:
         - load the XML file and generate a dataframe from the spots and tracks
@@ -124,36 +159,40 @@ def process_trackmate(
     Parameters
     ----------
     xml_path : Union[str, Path]
-        Path to the XML file
-    channels: List[str]
-        Names of channels holding FUCCI information
-    generate_unique_tracks: bool
-        Assign unique track IDs to splitted tracks.
-        Requires usage of action in TrackMate.
+        Path to the TrackMate XML file.
+    channels : List[str]
+        Names of columns holding FUCCI fluorescence information.
     sensor : FUCCISensor
-        FUCCI sensor with phase specifics
-    thresholds: List[float]
-        Thresholds to separate phases
+        FUCCI sensor with phase-specific parameters.
+    thresholds : List[float]
+        Thresholds used to separate cell-cycle phases.
     use_moving_average : bool, optional
-        Use moving average before normalization, by default True
+        If True, apply a moving average before normalization. Default is True.
     window_size : int, optional
-        Window size of the moving average, by default 5
+        Window size of the moving average. Default is 7.
     manual_min : Optional[List[float]], optional
-        Manually determined minimum for each channel, by default None
+        Manually determined minimum for each channel, by default None.
     manual_max : Optional[List[float]], optional
-        Manually determined maximum for each channel, by default None
-    estimate_percentage: bool, optional
-        Estimate cell cycle percentage
+        Manually determined maximum for each channel, by default None.
+    generate_unique_tracks : bool, optional
+        If True, assign unique track IDs to split tracks. This requires
+        using the appropriate action in TrackMate. Default is False.
+    estimate_percentage : bool, optional
+        If True, estimate cell-cycle percentage along each track. Default is True.
+    output_dir : Optional[Union[str, Path]], optional
+        Optional directory where the updated XML should be written. If None,
+        the file is saved next to the input XML.
 
     Returns
     -------
-    pd.DataFrame
-        Dataframe with the cell cycle percentage and the corresponding phases
+    pandas.DataFrame
+        Dataframe with the cell-cycle percentage and the corresponding phases.
+
     """
-    # read the XML
+    # read the XML and extract the dataframe and XML wrapper
     df, tmxml = read_trackmate_xml(xml_path)
 
-    # process the dataframe
+    # process the dataframe in-place (and also get a reference to it)
     process_dataframe(
         df,
         channels,
@@ -167,12 +206,19 @@ def process_trackmate(
         estimate_percentage=estimate_percentage,
     )
 
-    # update the XML
+    # update the XML with the new features
     tmxml.update_features(df)
 
-    # export the xml
+    # export the updated XML next to the original file
     new_name = Path(xml_path).stem + "_processed.xml"
-    new_path = Path(xml_path).parent / new_name
+
+    if output_dir is not None:
+        output_dir = Path(output_dir)
+        output_dir.mkdir(parents=True, exist_ok=True)
+        new_path = output_dir / new_name
+    else:
+        new_path = Path(xml_path).parent / new_name
+
     tmxml.save_xml(new_path)
 
     return df

fucciphase/io.py

@@ -1,25 +1,25 @@
 from pathlib import Path
-from typing import Tuple, Union
 
 import pandas as pd
 
 from .utils import TrackMateXML
 
 
-def read_trackmate_xml(xml_path: Union[Path, str]) -> Tuple[pd.DataFrame, TrackMateXML]:
-    """Read a trackmate exported xml file.
+def read_trackmate_xml(xml_path: Path | str) -> tuple[pd.DataFrame, TrackMateXML]:
+    """Read a TrackMate-exported XML file and return data and XML wrapper.
 
     Parameters
     ----------
     xml_path : Union[Path, str]
-        Path to the xml file.
+        Path to the XML file.
 
     Returns
     -------
     df : pandas.DataFrame
-        Dataframe containing the xml data.
+        Dataframe containing the spot and track data, sorted by FRAME.
     trackmate : TrackMateXML
-        TrackMateXML object.
+        TrackMateXML object wrapping the original XML and allowing
+        feature updates / re-export.
     """
     # read in the xml file
     trackmate = TrackMateXML(xml_path)
@@ -32,27 +32,31 @@ def read_trackmate_xml(xml_path: Union[Path, str]) -> Tuple[pd.DataFrame, TrackM
     return df, trackmate
 
 
-def read_trackmate_csv(csv_path: Union[Path, str]) -> pd.DataFrame:
-    """Read a trackmate exported csv file.
+def read_trackmate_csv(csv_path: Path | str) -> pd.DataFrame:
+    """Read a TrackMate-exported CSV file.
 
     The first three rows (excluding header) of the csv file are skipped as
     they contain duplicate titles of columns and units (Trackmate specific).
 
+    The first three rows (excluding the header) of the CSV file are
+    skipped as they contain duplicate column titles and units
+    (TrackMate-specific).
 
     Parameters
     ----------
-    csv_path : str
-        Path to the csv file.
+    csv_path : Union[Path, str]
+        Path to the CSV file.
 
     Returns
     -------
     df : pandas.DataFrame
-        Dataframe containing the csv data.
+        Dataframe containing the CSV data with converted dtypes.
 
     Raises
     ------
     ValueError
-        If the csv file does not contain at least two channels.
+        If the CSV file does not contain both MEAN_INTENSITY_CH1 and
+        MEAN_INTENSITY_CH2 columns.
     """
     df = pd.read_csv(csv_path, encoding="unicode_escape", skiprows=[1, 2, 3])
 

fucciphase/main_cli.py

@@ -1,5 +1,6 @@
 import argparse
 import json
+from pathlib import Path
 
 import pandas as pd
 
@@ -15,12 +16,37 @@ except ImportError as err:
 
 
 def main_cli() -> None:
-    """Fucciphase CLI."""
+    """Fucciphase CLI: Command-line entry point for FUCCIphase.
+
+    This function is invoked by the ``fucciphase`` console script and
+    implements the standard command-line workflow:
+
+    1. Parse command-line arguments describing:
+       - a TrackMate tracking file (XML or CSV),
+       - a reference cell-cycle trace in CSV format,
+       - an optional FUCCI sensor JSON file,
+       - the acquisition timestep and channel names.
+    2. Load the reference data and rename its fluorescence columns to
+       match the user-specified channel names.
+    3. Load and preprocess the tracking data using either
+       :func:`process_trackmate` (for XML) or
+       :func:`process_dataframe` (for CSV).
+    4. Estimate cell-cycle percentages for each track by subsequence
+       alignment against the reference trace.
+    5. Write the processed table to ``<tracking_file>_processed.csv`` in
+       the same directory as the input file.
+
+    The function is designed to be used from the command line and does
+    not return a value. It will raise a ``ValueError`` if the tracking
+    file does not have an XML or CSV extension.
+    """
     parser = argparse.ArgumentParser(
         prog="fucciphase",
         description="FUCCIphase tool to estimate cell cycle phases and percentages.",
         epilog="Please report bugs and errors on GitHub.",
     )
+
+    # -------------- 1. Parse command-line arguments --------------
     parser.add_argument("tracking_file", type=str, help="TrackMate XML or CSV file")
     parser.add_argument(
         "-ref",
@@ -61,13 +87,19 @@ def main_cli() -> None:
     )
 
     args = parser.parse_args()
+    # Decide where to store outputs (CSV and, for XML input, processed XML)
+    output_dir = Path("outputs")
+    output_dir.mkdir(exist_ok=True)
 
+    # ---------------- 2. Load and adapt the reference cell-cycle trace ----------------
     reference_df = pd.read_csv(args.reference_file)
+    # 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)
@@ -75,15 +107,19 @@ def main_cli() -> None:
     else:
         sensor = get_fuccisa_default_sensor()
 
+    # ---------------- 4. Load and preprocess the tracking data ----------------
     if args.tracking_file.endswith(".xml"):
+        # XML: let process_trackmate handle I/O and preprocessing
         df = process_trackmate(
             args.tracking_file,
             channels=[args.cyan_channel, args.magenta_channel],
             sensor=sensor,
             thresholds=[0.1, 0.1],
             generate_unique_tracks=args.generate_unique_tracks,
+            output_dir=output_dir,
         )
     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)
         process_dataframe(
             df,
@@ -95,6 +131,7 @@ def main_cli() -> None:
     else:
         raise ValueError("Tracking file must be an XML or CSV file.")
 
+    # ---------------- 5. Estimate cell-cycle percentages ----------------
     track_id_name = "UNIQUE_TRACK_ID"
     if not args.generate_unique_tracks:
         track_id_name = "TRACK_ID"
@@ -104,13 +141,31 @@ def main_cli() -> None:
         dt=args.timestep,
         channels=[args.cyan_channel, args.magenta_channel],
         reference_data=reference_df,
-        track_id_name=track_id_name
+        track_id_name=track_id_name,
     )
-    df.to_csv(args.tracking_file + "_processed.csv", index=False)
+    # ---------------- 6. Save results ----------------
+    tracking_path = Path(args.tracking_file)
+    output_csv = output_dir / (tracking_path.stem + "_processed.csv")
+    df.to_csv(output_csv, index=False)
 
 
 def main_visualization() -> None:
-    """Fucciphase visualization."""
+    """Fucciphase visualization.
+
+    Launch a napari-based visualization of FUCCIphase results.
+
+    This command-line entry point loads a processed FUCCIphase CSV file
+    together with the corresponding OME-TIFF time-lapse movie and
+    segmentation masks, then opens an interactive napari viewer showing:
+
+    - cyan and magenta fluorescence channels,
+    - segmentation masks as a labels layer,
+    - tracks and cell-cycle information overlaid on the image.
+
+    The function is intended to be invoked via the ``fucciphase-napari``
+    console script and does not return a value.
+
+    """
     parser = argparse.ArgumentParser(
         prog="fucciphase-napari",
         description="FUCCIphase napari script to launch visualization.",
@@ -142,13 +197,19 @@ def main_visualization() -> None:
         required=True,
     )
     parser.add_argument(
-            "--pixel_size",
-            type=float,
-            help="Pixel size, only used if not in metadata",
-            default=None)
+        "--pixel_size",
+        type=float,
+        help="Pixel size, only used if not in metadata",
+        default=None,
+    )
 
     args = parser.parse_args()
 
+    # Decide where to store outputs (CSV and, for XML input, processed XML)
+    output_dir = Path("outputs")
+    output_dir.mkdir(exist_ok=True)
+
+    # Try to read the video using AICSImage; fall back to bioio if needed
     AICSIMAGE = False
     BIOIMAGE = False
     try:
@@ -169,6 +230,8 @@ def main_visualization() -> None:
         image = AICSImage(args.video)
     elif BIOIMAGE:
         image = BioImage(args.video, reader=bioio_ome_tiff.Reader)
+
+    # Determine spatial scale; fall back to unit scale or user-provided pixel size
     scale = (image.physical_pixel_sizes.Y, image.physical_pixel_sizes.X)
     if None in scale:
         if args.pixel_size is not None:

fucciphase/napari/tracks_to_napari.py

@@ -1,5 +1,3 @@
-from typing import List, Optional
-
 import numpy as np
 import pandas as pd
 
@@ -15,18 +13,18 @@ def add_trackmate_data_to_viewer(
     df: pd.DataFrame,
     viewer: napari.Viewer,
     scale: tuple,
-    image_data: List[np.ndarray],
-    colormaps: List[str],
-    labels: Optional[np.ndarray],
-    cycle_percentage_id: Optional[str] = "CELL_CYCLE_PERC_POST",
+    image_data: list[np.ndarray],
+    colormaps: list[str],
+    labels: np.ndarray | None,
+    cycle_percentage_id: str | None = "CELL_CYCLE_PERC_POST",
     dim: int = 2,
-    textkwargs: Optional[dict] = None,
-    label_id_name: Optional[str] = "MAX_INTENSITY_CH3",
-    track_id_name: Optional[str] = "TRACK_ID",
-    time_id_name: Optional[str] = "POSITION_T",
-    pos_x_id_name: Optional[str] = "POSITION_X",
-    pos_y_id_name: Optional[str] = "POSITION_Y",
-    crop_fov: Optional[List[float]] = None,
+    textkwargs: dict | None = None,
+    label_id_name: str | None = "MAX_INTENSITY_CH3",
+    track_id_name: str | None = "TRACK_ID",
+    time_id_name: str | None = "POSITION_T",
+    pos_x_id_name: str | None = "POSITION_X",
+    pos_y_id_name: str | None = "POSITION_Y",
+    crop_fov: list[float] | None = None,
 ) -> None:
     """Overlay tracking result and video.
 
@@ -73,7 +71,7 @@ def add_trackmate_data_to_viewer(
         labels_layer = viewer.add_labels(new_labels, scale=scale)
         labels_layer.contour = 10
 
-    for image, colormap in zip(image_data, colormaps):
+    for image, colormap in zip(image_data, colormaps, strict=True):
         viewer.add_image(image, blending="additive", colormap=colormap, scale=scale)
     # TODO implement cropping, filter points in / outside range
     # crop_fov =
@@ -95,8 +93,8 @@ def pandas_df_to_napari_tracks(
     frame_id_name: str,
     position_x_name: str,
     position_y_name: str,
-    feature_name: Optional[str] = None,
-    colormaps_dict: Optional[dict] = None,
+    feature_name: str | None = None,
+    colormaps_dict: dict | None = None,
 ) -> None:
     """Add tracks to Napari track layer.
     Splitting and merging are not yet implemented.