fucciphase 0.0.2__py3-none-any.whl → 0.0.4__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,5 @@
+import logging
 from pathlib import Path
-from typing import List, Optional, Union
 
 import pandas as pd
 
@@ -8,23 +8,33 @@ 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,
-    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,42 +48,82 @@ 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.")
 
+    # 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:
             split_trackmate_tracks(df, label_id_name=label_id_name)
             # 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(
@@ -86,7 +136,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 +147,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 +183,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 +230,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)
@@ -27,40 +27,41 @@ def read_trackmate_xml(xml_path: Union[Path, str]) -> Tuple[pd.DataFrame, TrackM
     # 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
 
 
-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])
 
     # 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,7 @@
 import argparse
 import json
+import logging
+from pathlib import Path
 
 import pandas as pd
 
@@ -8,19 +10,47 @@ 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."""
+    """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.
+    """
+    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.",
         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",
@@ -55,36 +85,78 @@ 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()
+    # 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 ----------------
+    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
 
-    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)
+        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()
 
+    # ---------------- 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"):
-        df = pd.read_csv(args.tracking_file)
+        # CSV: read the table and then run the processing pipeline on it
+        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],
@@ -95,6 +167,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 +177,41 @@ 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.
+
+    """
+    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.",
@@ -142,44 +243,64 @@ 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:
         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
     scale = (image.physical_pixel_sizes.Y, image.physical_pixel_sizes.X)
     if None in scale:
         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()
 
@@ -194,7 +315,3 @@ def main_visualization() -> None:
         textkwargs={"size": 14},
     )
     napari.run()
-
-
-if __name__ == "__main__":
-    main_cli()