fucciphase 0.0.1__py3-none-any.whl

fucciphase/__init__.py

@@ -0,0 +1,12 @@
+"""Cell cycle analysis plugin."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("fucciphase")
+except PackageNotFoundError:
+    __version__ = "uninstalled"
+__all__ = ["__version__", "logistic", "process_dataframe", "process_trackmate"]
+
+from .fucci_phase import process_dataframe, process_trackmate
+from .sensor import logistic

fucciphase/fucci_phase.py

@@ -0,0 +1,178 @@
+from pathlib import Path
+from typing import List, Optional, Union
+
+import pandas as pd
+
+from .io import read_trackmate_xml
+from .phase import generate_cycle_phases
+from .sensor import FUCCISensor
+from .utils import normalize_channels, split_trackmate_tracks
+
+
+def process_dataframe(
+    df: pd.DataFrame,
+    channels: List[str],
+    sensor: FUCCISensor,
+    thresholds: List[float],
+    use_moving_average: bool = True,
+    window_size: int = 7,
+    manual_min: Optional[List[float]] = None,
+    manual_max: Optional[List[float]] = 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.
+
+    The dataframe must contain ID and TRACK_ID features.
+
+    This function applies the following steps:
+        - if `use_moving_average` is True, apply a Savitzky-Golay filter to each track
+          and each channel
+        - if `manual_min` and `manual_max` are None, normalize the channels globally.
+          Otherwise, use them to normalize each channel.
+        - compute the cell cycle phases and their estimated percentage
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Dataframe
+    channels: List[str]
+        Names of channels holding FUCCI information
+    sensor : FUCCISensor
+        FUCCI sensor with phase specifics
+    thresholds: List[float]
+        Thresholds to separate phases
+    use_moving_average : bool, optional
+        Use moving average before normalization, by default True
+    window_size : int, optional
+        Window size of the moving average, by default 5
+    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.
+    track_id_name: str
+        Name of column with track IDs
+    """
+    if len(channels) != sensor.fluorophores:
+        raise ValueError(f"Need to provide {sensor.fluorophores} channel names.")
+
+    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.")
+
+    # normalize the channels
+    normalize_channels(
+        df,
+        channels,
+        use_moving_average=use_moving_average,
+        moving_average_window=window_size,
+        manual_min=manual_min,
+        manual_max=manual_max,
+        track_id_name=track_id_name,
+    )
+
+    # compute the phases
+    generate_cycle_phases(
+        df,
+        sensor=sensor,
+        channels=channels,
+        thresholds=thresholds,
+        estimate_percentage=estimate_percentage,
+    )
+
+
+def process_trackmate(
+    xml_path: Union[str, Path],
+    channels: List[str],
+    sensor: FUCCISensor,
+    thresholds: List[float],
+    use_moving_average: bool = True,
+    window_size: int = 7,
+    manual_min: Optional[List[float]] = None,
+    manual_max: Optional[List[float]] = None,
+    generate_unique_tracks: bool = False,
+    estimate_percentage: bool = True,
+) -> 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.
+
+    This function applies the following steps:
+        - load the XML file and generate a dataframe from the spots and tracks
+        - if `use_moving_average` is True, apply a Savitzky-Golay filter to each track
+          and each channel
+        - if `manual_min` and `manual_max` are None, normalize the channels globally.
+          Otherwise, use them to normalize each channel.
+        - compute the cell cycle percentage
+        - save an updated XML copy with the new features
+
+    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.
+    sensor : FUCCISensor
+        FUCCI sensor with phase specifics
+    thresholds: List[float]
+        Thresholds to separate phases
+    use_moving_average : bool, optional
+        Use moving average before normalization, by default True
+    window_size : int, optional
+        Window size of the moving average, by default 5
+    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, optional
+        Estimate cell cycle percentage
+
+    Returns
+    -------
+    pd.DataFrame
+        Dataframe with the cell cycle percentage and the corresponding phases
+    """
+    # read the XML
+    df, tmxml = read_trackmate_xml(xml_path)
+
+    # process the dataframe
+    process_dataframe(
+        df,
+        channels,
+        sensor,
+        thresholds,
+        use_moving_average=use_moving_average,
+        window_size=window_size,
+        manual_min=manual_min,
+        manual_max=manual_max,
+        generate_unique_tracks=generate_unique_tracks,
+        estimate_percentage=estimate_percentage,
+    )
+
+    # update the XML
+    tmxml.update_features(df)
+
+    # export the xml
+    new_name = Path(xml_path).stem + "_processed.xml"
+    new_path = Path(xml_path).parent / new_name
+    tmxml.save_xml(new_path)
+
+    return df

fucciphase/io.py

@@ -0,0 +1,67 @@
+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.
+
+    Parameters
+    ----------
+    xml_path : Union[Path, str]
+        Path to the xml file.
+
+    Returns
+    -------
+    df : pandas.DataFrame
+        Dataframe containing the xml data.
+    trackmate : TrackMateXML
+        TrackMateXML object.
+    """
+    # read in the xml file
+    trackmate = TrackMateXML(xml_path)
+
+    # convert the spots to a dataframe
+    df = trackmate.to_pandas()
+    # sort by frame number to have increasing time
+    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.
+
+    The first three rows (excluding header) of the csv file are skipped as
+    they contain duplicate titles of columns and units (Trackmate specific).
+
+
+    Parameters
+    ----------
+    csv_path : str
+        Path to the csv file.
+
+    Returns
+    -------
+    df : pandas.DataFrame
+        Dataframe containing the csv data.
+
+    Raises
+    ------
+    ValueError
+        If the csv file does not contain at least two channels.
+    """
+    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
+    ):
+        raise ValueError("Trackmate must have at least two channels.")
+
+    # return dataframe with converted types (object -> string)
+    return df.convert_dtypes()

fucciphase/napari/__init__.py

@@ -0,0 +1,5 @@
+"""Napari convenience functions."""
+
+from .tracks_to_napari import add_trackmate_data_to_viewer, pandas_df_to_napari_tracks
+
+__all__ = ["add_trackmate_data_to_viewer", "pandas_df_to_napari_tracks"]

fucciphase/napari/tracks_to_napari.py

@@ -0,0 +1,117 @@
+from typing import List, Optional
+
+import numpy as np
+import pandas as pd
+
+HAS_NAPARI = True
+try:
+    import napari
+except ImportError:
+    HAS_NAPARI = False
+    pass
+
+
+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",
+    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,
+) -> None:
+    """Overlay tracking result and video.
+
+    df: pd.DataFrame
+        TrackMate result processed by fucciphase
+    viewer: napari.Viewer
+        Viewer instance
+    scale: tuple
+        Pixel sizes as tuple of size dim
+    image_data: np.ndarray
+        List of image arrays
+    colormaps: List[str]
+        List of colormaps for each image channel
+    labels: Optional[np.ndarray]
+        Segmentation masks
+    textkwargs: dict
+        Dictionary to pass options to text in napari
+    crop_fov: List[List[float], List[float]]
+        Crop the masks and points
+    """
+    if textkwargs is None:
+        textkwargs = {}
+    if not HAS_NAPARI:
+        raise ImportError("Please install napari")
+    if dim != 2:
+        raise NotImplementedError("Workflow currently only implemented for 2D frames.")
+    # make sure it is sorted
+    napari_val_df = df.sort_values(time_id_name)
+    # extract points
+    points = napari_val_df[[time_id_name, pos_y_id_name, pos_x_id_name]].to_numpy()
+    # extract percentages at points
+    # TODO insert checks
+    percentage_values = napari_val_df[cycle_percentage_id].to_numpy()
+    if labels is not None:
+        new_labels = np.zeros(shape=labels.shape, dtype=labels.dtype)
+        # add labels to each frame
+        for i in range(round(df[time_id_name].max()) + 1):
+            subdf = df[np.isclose(df[time_id_name], i)]
+            label_ids = subdf[label_id_name]
+            track_ids = subdf[track_id_name]
+            for idx, label_id in enumerate(label_ids):
+                # add 1 because TRACK_ID 0 would be background
+                new_labels[i][np.isclose(labels[i], label_id)] = track_ids.iloc[idx] + 1
+        labels_layer = viewer.add_labels(new_labels, scale=scale)
+        labels_layer.contour = 10
+
+    for image, colormap in zip(image_data, colormaps):
+        viewer.add_image(image, blending="additive", colormap=colormap, scale=scale)
+    # TODO implement cropping, filter points in / outside range
+    # crop_fov =
+    viewer.add_points(
+        points,
+        features={"percentage": np.round(percentage_values, 1)},
+        text={"string": "{percentage}%", "color": "white", **textkwargs},
+        size=0.01,
+    )
+    viewer.scale_bar.visible = True
+    viewer.scale_bar.unit = "um"
+    return
+
+
+def pandas_df_to_napari_tracks(
+    df: pd.DataFrame,
+    viewer: napari.Viewer,
+    unique_track_id_name: str,
+    frame_id_name: str,
+    position_x_name: str,
+    position_y_name: str,
+    feature_name: Optional[str] = None,
+    colormaps_dict: Optional[dict] = None,
+) -> None:
+    """Add tracks to Napari track layer.
+    Splitting and merging are not yet implemented.
+    """
+    # filter for valid tracks only
+    track_df = df[df[unique_track_id_name] > 0]
+    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:
+        features = {feature_name: track_df[feature_name].to_numpy()}
+    viewer.add_tracks(track_data, features=features, colormaps_dict=colormaps_dict)