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

fucciphase/plot.py

@@ -1,5 +1,4 @@
 from itertools import cycle
-from typing import List, Optional
 
 import numpy as np
 import pandas as pd
@@ -16,7 +15,27 @@ from .utils import get_norm_channel_name
 def set_phase_colors(
     df: pd.DataFrame, colordict: dict, phase_column: str = "DISCRETE_PHASE_MAX"
 ) -> None:
-    """Label each phase by fixed color."""
+    """Label each phase by fixed color.
+
+    This function adds a ``COLOR`` column to the dataframe by mapping each
+    entry in ``phase_column`` to a color specified in ``colordict``.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Dataframe containing at least ``phase_column``.
+    colordict : dict
+        Mapping from phase label (str) to a valid matplotlib color.
+    phase_column : str, optional
+        Name of the column containing phase labels. Default is
+        ``"DISCRETE_PHASE_MAX"``.
+
+    Raises
+    ------
+    ValueError
+        If not all phase labels present in the dataframe have a color
+        entry in ``colordict``.
+    """
     phases = df[phase_column].unique()
     if not all(phase in colordict for phase in phases):
         raise ValueError(f"Provide a color for every phase in: {phases}")
@@ -32,10 +51,39 @@ def plot_feature(
     feature_name: str,
     interpolate_time: bool = False,
     track_id_name: str = "TRACK_ID",
-    ylim: Optional[tuple] = None,
-    yticks: Optional[list] = None,
+    ylim: tuple | None = None,
+    yticks: list | None = None,
 ) -> Figure:
-    """Plot features of individual tracks in one plot."""
+    """Plot features of individual tracks in one plot.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Dataframe containing the feature and time columns.
+    time_column : str
+        Name of the column containing time or frame indices.
+    feature_name : str
+        Name of the feature column to plot.
+    interpolate_time : bool, optional
+        Currently unused; kept for API compatibility. Default is False.
+    track_id_name : str, optional
+        Name of the column containing track IDs. Default is ``"TRACK_ID"``.
+    ylim : tuple, optional
+        y-axis limits as ``(ymin, ymax)``.
+    yticks : list, optional
+        Explicit y-tick locations.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure containing the plot.
+
+    Raises
+    ------
+    ValueError
+        If the feature or time columns are not found.
+
+    """
     if feature_name not in df:
         raise ValueError(f"(Feature {feature_name} not in provided DataFrame.")
     if time_column not in df:
@@ -63,20 +111,57 @@ def plot_feature_stacked(
     feature_name: str,
     interpolate_time: bool = False,
     track_id_name: str = "TRACK_ID",
-    ylim: Optional[tuple] = None,
-    yticks: Optional[list] = None,
+    ylim: tuple | None = None,
+    yticks: list | None = None,
     interpolation_steps: int = 1000,
-    figsize: Optional[tuple] = None,
-    selected_tracks: Optional[List[int]] = None,
+    figsize: tuple | None = None,
+    selected_tracks: list[int] | None = None,
 ) -> Figure:
     """Stack features of individual tracks.
 
+    Each selected track is plotted in its own horizontal panel. If
+    ``interpolate_time`` is True, an additional panel at the bottom shows
+    the mean interpolated feature across all tracks.
 
     Notes
     -----
-    If `selected_tracks` are chosen, the averaging
-    is still performed on all tracks.
-    Few selected tracks are stacked to enhance visibility.
+    If ``selected_tracks`` are chosen, the averaging is still performed on
+    all tracks. The selected subset is only used for stacked visualization.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Dataframe containing the feature, time and COLOR columns.
+    time_column : str
+        Name of the column containing time or frame indices.
+    feature_name : str
+        Name of the feature column to plot.
+    interpolate_time : bool, optional
+        If True, add an extra panel showing the average interpolated
+        feature over time. Default is False.
+    track_id_name : str, optional
+        Name of the column containing track IDs. Default is ``"TRACK_ID"``.
+    ylim : tuple, optional
+        y-axis limits as ``(ymin, ymax)``.
+    yticks : list, optional
+        Explicit y-tick locations.
+    interpolation_steps : int, optional
+        Number of time points used for interpolation. Default is 1000.
+    figsize : tuple, optional
+        Figure size passed to ``plt.subplots``.
+    selected_tracks : list of int, optional
+        Subset of track IDs to plot in stacked panels.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        The figure containing the stacked plots.
+
+    Raises
+    ------
+    ValueError
+        If required columns are missing or ``selected_tracks`` contains
+        IDs not present in the dataframe.
     """
     if feature_name not in df:
         raise ValueError(f"(Feature {feature_name} not in provided DataFrame.")
@@ -156,7 +241,27 @@ def plot_raw_intensities(
     time_label: str = "Frame #",
     **plot_kwargs: bool,
 ) -> None:
-    """Plot intensities of two-channel sensor."""
+    """Plot intensities of two-channel sensor over time.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Dataframe containing intensity and time columns.
+    channel1 : str
+        Name of the first intensity column.
+    channel2 : str
+        Name of the second intensity column.
+    color1 : str, optional
+        Color used for ``channel1``. Default is ``"cyan"``.
+    color2 : str, optional
+        Color used for ``channel2``. Default is ``"magenta"``.
+    time_column : str, optional
+        Name of the time/frame column. Default is ``"FRAME"``.
+    time_label : str, optional
+        Label used for the x-axis. Default is ``"Frame #"``.
+    plot_kwargs : dict
+        Additional keyword arguments passed to ``matplotlib.pyplot.plot``.
+    """
     ch1_intensity = df[channel1]
     ch2_intensity = df[channel2]
 
@@ -188,7 +293,27 @@ def plot_normalized_intensities(
     time_label: str = "Frame #",
     **plot_kwargs: bool,
 ) -> None:
-    """Plot normalised intensities of two-channel sensor."""
+    """Plot normalised intensities of two-channel sensor.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Dataframe containing normalized intensity and time columns.
+    channel1 : str
+        Name of the first channel (pre-normalization).
+    channel2 : str
+        Name of the second channel (pre-normalization).
+    color1 : str, optional
+        Color used for ``channel1``. Default is ``"cyan"``.
+    color2 : str, optional
+        Color used for ``channel2``. Default is ``"magenta"``.
+    time_column : str, optional
+        Name of the time/frame column. Default is ``"FRAME"``.
+    time_label : str, optional
+        Label used for the x-axis. Default is ``"Frame #"``.
+    plot_kwargs : dict
+        Additional keyword arguments passed to ``matplotlib.pyplot.plot``.
+    """
     ch1_intensity = df[get_norm_channel_name(channel1)]
     ch2_intensity = df[get_norm_channel_name(channel2)]
 
@@ -200,30 +325,28 @@ def plot_normalized_intensities(
 
 
 def plot_phase(df: pd.DataFrame, channel1: str, channel2: str) -> None:
-    """Plot the two channels and vertical lines
-    corresponding to the change of phase.
+    """Plot discrete cell-cycle phase-related signals over time.
 
-    The dataframe must be preprocessed with one of the available phase
-    computation function and must contain the following columns:
+    Plot the two normalized channels and the unique intensity curve over
+    frame number. The dataframe must already contain:
 
-        - normalised channels (channel1 + "_NORM", etc)
-        - cell cycle percentage
-        - FRAME
+        - normalized channels (e.g. ``channel + "_NORM"``),
+        - the cell cycle percentage column,
+        - the ``FRAME`` column.
 
     Parameters
     ----------
-    df : pd.DataFrame
-        Dataframe
+    df : pandas.DataFrame
+        Input dataframe.
     channel1 : str
-        First channel
+        First channel name (pre-normalization).
     channel2 : str
-        Second channel
+        Second channel name (pre-normalization).
 
     Raises
     ------
     ValueError
-        If the dataframe does not contain the FRAME, CELL_CYCLE_PERC and normalised
-        columns.
+        If the dataframe does not contain the required columns.
     """
     # check if the FRAME column is present
     if "FRAME" not in df.columns:
@@ -248,33 +371,49 @@ def plot_phase(df: pd.DataFrame, channel1: str, channel2: str) -> None:
 def plot_dtw_query_vs_reference(
     reference_df: pd.DataFrame,
     df: pd.DataFrame,
-    channels: List[str],
+    channels: list[str],
     ref_percentage_column: str = "percentage",
     est_percentage_column: str = "CELL_CYCLE_PERC_DTW",
-    ground_truth: Optional[pd.DataFrame] = None,
-    colors: Optional[List[str]] = None,
+    ground_truth: pd.DataFrame | None = None,
+    colors: list[str] | None = None,
     **plot_kwargs: bool,
 ) -> None:
-    """Plot query and alignment to reference curve.
+    """
+    Plot query curves and their alignment to a reference cell-cycle curve.
+
+    For each channel, this function plots:
+
+    - the query intensity as a function of estimated percentage,
+    - the reference intensity as a function of reference percentage,
+    - the reference curve re-sampled at the query percentages (match).
+
+    Optionally, ground truth curves can be overlaid.
 
     Parameters
     ----------
-    reference_df: pd.DataFrame
-        DataFrame with reference curve data
-    df: pd.DataFrame
-        DataFrame used for query
-    channels: List[str]
-        Name of the channels
-    ref_percentage_column: str
-        Name of column with percentages of reference curve
-    est_percentage_column: str
-        Name of column with estimated percentages
-    ground_truth: pd.DataFrame
-        DataFrame with ground truth data, needs to be named as reference_df
-    colors: List[str]
-        Colors for plot
-    plot_kwargs: dict
-        Kwargs to be passed to matplotlib
+    reference_df : pandas.DataFrame
+        Dataframe with the reference curve (percentage vs intensity).
+    df : pandas.DataFrame
+        Dataframe used as query (estimated percentage vs intensity).
+    channels : list of str
+        Names of the channels to plot.
+    ref_percentage_column : str, optional
+        Column name for reference percentages. Default is ``"percentage"``.
+    est_percentage_column : str, optional
+        Column name for estimated percentages in the query dataframe.
+        Default is ``"CELL_CYCLE_PERC_DTW"``.
+    ground_truth : pandas.DataFrame, optional
+        Dataframe containing ground truth intensities, with the same
+        column names as ``reference_df``.
+    colors : list of str, optional
+        Colors to use for each channel in the reference plots.
+    plot_kwargs : dict
+        Additional keyword arguments passed to ``matplotlib.pyplot.plot``.
+
+    Raises
+    ------
+    ValueError
+        If required columns are missing in the reference or query dataframes.
     """
     for channel in channels:
         if channel not in reference_df.columns:
@@ -293,7 +432,7 @@ def plot_dtw_query_vs_reference(
             "Percentage column not found in reference DataFrame"
             f", available options {reference_df.columns}"
         )
-    fig, ax = plt.subplots(1, len(channels))
+    _, ax = plt.subplots(1, len(channels))
     for idx, channel in enumerate(channels):
         ax[idx].plot(
             df[est_percentage_column], df[channel], label="Query", **plot_kwargs
@@ -333,36 +472,41 @@ def plot_dtw_query_vs_reference(
 def plot_query_vs_reference_in_time(
     reference_df: pd.DataFrame,
     df: pd.DataFrame,
-    channels: List[str],
+    channels: list[str],
     ref_time_column: str = "time",
     query_time_column: str = "time",
-    colors: Optional[List[str]] = None,
-    channel_titles: Optional[List[str]] = None,
-    fig_title: Optional[str] = None,
+    colors: list[str] | None = None,
+    channel_titles: list[str] | None = None,
+    fig_title: str | None = None,
     **plot_kwargs: bool,
 ) -> None:
-    """Plot query and alignment to reference curve.
+    """
+    Plot query and reference curves as a function of time.
+
+    For each channel, this function overlays the query intensity and the
+    reference intensity over time. This is useful to visually compare
+    dynamics in the original time domain.
 
     Parameters
     ----------
-    reference_df: pd.DataFrame
-        DataFrame with reference curve data
-    df: pd.DataFrame
-        DataFrame used for query
-    channels: List[str]
-        Name of the channels
-    ref_time_column: str
-        Name of column with times of reference curve
-    query_time_column: str
-        Name of column with times in query
-    colors: List[str]
-        Colors for plot
-    plot_kwargs: dict
-        Kwargs to be passed to matplotlib
-    channel_titles: Optional[List]
-        titles for each channel
-    fig_title: Optional[str]
-        Figure title
+    reference_df : pandas.DataFrame
+        Dataframe with reference curve data (time vs intensity).
+    df : pandas.DataFrame
+        Dataframe with query data (time vs intensity).
+    channels : list of str
+        Names of the channels to plot.
+    ref_time_column : str, optional
+        Column name for reference time values. Default is ``"time"``.
+    query_time_column : str, optional
+        Column name for query time values. Default is ``"time"``.
+    colors : list of str, optional
+        Colors to use for the reference curves.
+    plot_kwargs : dict
+        Additional keyword arguments passed to ``matplotlib.pyplot.plot``.
+    channel_titles : list, optional
+        Per-channel titles to display above each subplot.
+    fig_title : str, optional
+        Overall figure title.
     """
     for channel in channels:
         if channel not in reference_df.columns:
@@ -438,13 +582,14 @@ def plot_cell_trajectory(
     min_track_length: int = 30,
     centroid0_name: str = "centroid-0",
     centroid1_name: str = "centroid-1",
-    phase_column: Optional[str] = None,
-    percentage_column: Optional[str] = None,
+    phase_column: str | None = None,
+    percentage_column: str | None = None,
     coloring_mode: str = "phase",
-    line_cycle: Optional[list] = None,
+    line_cycle: list | None = None,
     **kwargs: int,
 ) -> None:
-    """Plot cell migration trajectories with phase or percentage-based coloring.
+    """
+    Plot cell migration trajectories with phase- or percentage-based coloring.
 
     Parameters
     ----------
@@ -453,27 +598,31 @@ def plot_cell_trajectory(
     track_id_name : str
         Column name containing unique track identifiers.
     min_track_length : int, optional
-        Minimum number of timepoints required to include a track, default is 30.
+        Minimum number of timepoints required to include a track.
+        Default is 30.
     centroid0_name : str, optional
-        Column name for x-coordinate of cell centroid, default is "centroid-0".
+        Column name for x-coordinate of the cell centroid.
     centroid1_name : str, optional
-        Column name for y-coordinate of cell centroid, default is "centroid-1".
+        Column name for y-coordinate of the cell centroid.
     phase_column : str, optional
-        Column name containing cell cycle phase information, default is None.
+        Column name containing cell-cycle phase information. Required if
+        ``coloring_mode == "phase"``.
     percentage_column : str, optional
-        Column name containing percentage values for coloring, default is None.
+        Column name containing percentage values for coloring. Required if
+        ``coloring_mode == "percentage"``.
     coloring_mode : str, optional
-        Color tracks by cell cycle phase (`phase`) or by percentage (`percentage`)
-    line_cycle: list
-        Cycle through the list, can help with visualization
-    kwargs: dict, optional
-        Kwargs are directly passed to the LineCollection, use it to adjust
-        the linestyle for example
+        Color tracks by cell-cycle phase (``"phase"``) or by percentage
+        (``"percentage"``). Default is ``"phase"``.
+    line_cycle : list, optional
+        List of linestyles to cycle through for successive tracks.
+    kwargs : dict, optional
+        Additional keyword arguments passed to
+        ``matplotlib.collections.LineCollection``.
 
     Notes
     -----
-    Phase or percentage columns need to be provided for the respective coloring.
-    If not, an error will be raised.
+    Phase or percentage columns need to be provided for the respective
+    coloring mode. If not, an error will be raised.
 
     """
     # inital checks
@@ -540,7 +689,7 @@ def plot_cell_trajectory(
                 **kwargs,
             )
         )
-    fig, ax = plt.subplots()
+    _, ax = plt.subplots()
     for line_collection in line_collections:
         ax.add_collection(line_collection)
     ax.margins(0.05)

fucciphase/sensor.py

@@ -1,5 +1,5 @@
 from abc import ABC, abstractmethod
-from typing import List, Union
+from typing import Union
 
 import numpy as np
 import pandas as pd
@@ -7,8 +7,8 @@ from scipy import optimize
 
 
 def logistic(
-    x: Union[float, np.ndarray], center: float, sigma: float, sign: float = 1.0
-) -> Union[float, np.ndarray]:
+    x: float | np.ndarray, center: float, sigma: float, sign: float = 1.0
+) -> float | np.ndarray:
     """Logistic function."""
     tiny = 1.0e-15
     arg = sign * (x - center) / max(tiny, sigma)
@@ -16,21 +16,21 @@ def logistic(
 
 
 def accumulation_function(
-    x: Union[float, np.ndarray],
+    x: float | np.ndarray,
     center: float,
     sigma: float,
     offset_intensity: float = 0,
-) -> Union[float, np.ndarray]:
+) -> float | np.ndarray:
     """Function to describe accumulation of sensor."""
     return 1.0 - logistic(x, center, sigma) - offset_intensity
 
 
 def degradation_function(
-    x: Union[float, np.ndarray],
+    x: float | np.ndarray,
     center: float,
     sigma: float,
     offset_intensity: float = 0,
-) -> Union[float, np.ndarray]:
+) -> float | np.ndarray:
     """Function to describe degradation of sensor."""
     return 1.0 - logistic(x, center, sigma, sign=-1.0) - offset_intensity
 
@@ -41,9 +41,9 @@ class FUCCISensor(ABC):
     @abstractmethod
     def __init__(
         self,
-        phase_percentages: List[float],
-        center: List[float],
-        sigma: List[float],
+        phase_percentages: list[float],
+        center: list[float],
+        sigma: list[float],
     ) -> None:
         pass
 
@@ -55,17 +55,17 @@ class FUCCISensor(ABC):
 
     @property
     @abstractmethod
-    def phases(self) -> List[str]:
+    def phases(self) -> list[str]:
         """Function to hard-code the supported phases of a sensor."""
         pass
 
     @property
-    def phase_percentages(self) -> List[float]:
+    def phase_percentages(self) -> list[float]:
         """Percentage of individual phases."""
         return self._phase_percentages
 
     @phase_percentages.setter
-    def phase_percentages(self, values: List[float]) -> None:
+    def phase_percentages(self, values: list[float]) -> None:
         if len(values) != len(self.phases):
             raise ValueError("Pass percentage for each phase.")
 
@@ -76,25 +76,25 @@ class FUCCISensor(ABC):
         self._phase_percentages = values
 
     @abstractmethod
-    def get_phase(self, phase_markers: Union[List[bool], "pd.Series[bool]"]) -> str:
+    def get_phase(self, phase_markers: Union[list[bool], "pd.Series[bool]"]) -> str:
         """Get the discrete phase based on phase markers.
 
         Notes
         -----
-        Discrete phase refers to, for example, G1 or S phase.
+        The discrete phase refers to, for example, G1 or S phase.
         The phase_markers must match the number of used fluorophores.
         """
         pass
 
     @abstractmethod
     def get_estimated_cycle_percentage(
-        self, phase: str, intensities: List[float]
+        self, phase: str, intensities: list[float]
     ) -> float:
         """Estimate percentage based on sensor intensities."""
         pass
 
     def set_accumulation_and_degradation_parameters(
-        self, center: List[float], sigma: List[float]
+        self, center: list[float], sigma: list[float]
     ) -> None:
         """Pass list of functions for logistic functions.
 
@@ -114,8 +114,8 @@ class FUCCISensor(ABC):
 
     @abstractmethod
     def get_expected_intensities(
-        self, percentage: Union[float, np.ndarray]
-    ) -> List[Union[float, np.ndarray]]:
+        self, percentage: float | np.ndarray
+    ) -> list[float | np.ndarray]:
         """Return value of calibrated curves."""
         pass
 
@@ -124,7 +124,7 @@ class FUCCISASensor(FUCCISensor):
     """FUCCI(SA) sensor."""
 
     def __init__(
-        self, phase_percentages: List[float], center: List[float], sigma: List[float]
+        self, phase_percentages: list[float], center: list[float], sigma: list[float]
     ) -> None:
         self.phase_percentages = phase_percentages
         self.set_accumulation_and_degradation_parameters(center, sigma)
@@ -135,11 +135,11 @@ class FUCCISASensor(FUCCISensor):
         return 2
 
     @property
-    def phases(self) -> List[str]:
+    def phases(self) -> list[str]:
         """Function to hard-code the supported phases of a sensor."""
         return ["G1", "G1/S", "S/G2/M"]
 
-    def get_phase(self, phase_markers: Union[List[bool], "pd.Series[bool]"]) -> str:
+    def get_phase(self, phase_markers: Union[list[bool], "pd.Series[bool]"]) -> str:
         """Return the discrete phase based channel ON / OFF data for the
         FUCCI(SA) sensor.
         """
@@ -279,7 +279,7 @@ class FUCCISASensor(FUCCISensor):
             return g1s_perc + 0.5 * (100.0 - g1s_perc - g1_perc)
 
     def get_estimated_cycle_percentage(
-        self, phase: str, intensities: List[float]
+        self, phase: str, intensities: list[float]
     ) -> float:
         """Estimate a cell cycle percentage based on intensities.
 
@@ -300,8 +300,8 @@ class FUCCISASensor(FUCCISensor):
             return self._find_sg2m_percentage(intensities[1])
 
     def get_expected_intensities(
-        self, percentage: Union[float, np.ndarray]
-    ) -> List[Union[float, np.ndarray]]:
+        self, percentage: float | np.ndarray
+    ) -> list[float | np.ndarray]:
         """Return value of calibrated curves."""
         g1_acc = accumulation_function(
             percentage, self._center_values[0], self._sigma_values[0]
@@ -332,7 +332,7 @@ class PIPFUCCISensor(FUCCISensor):
     """PIP-FUCCI sensor."""
 
     def __init__(
-        self, phase_percentages: List[float], center: List[float], sigma: List[float]
+        self, phase_percentages: list[float], center: list[float], sigma: list[float]
     ) -> None:
         self.phase_percentages = phase_percentages
         self.set_accumulation_and_degradation_parameters(center, sigma)
@@ -343,11 +343,11 @@ class PIPFUCCISensor(FUCCISensor):
         return 2
 
     @property
-    def phases(self) -> List[str]:
+    def phases(self) -> list[str]:
         """Function to hard-code the supported phases of a sensor."""
         return ["G1", "S", "G2/M"]
 
-    def get_phase(self, phase_markers: Union[List[bool], "pd.Series[bool]"]) -> str:
+    def get_phase(self, phase_markers: Union[list[bool], "pd.Series[bool]"]) -> str:
         """Return the discrete phase based channel ON / OFF data for the
         FUCCI(SA) sensor.
         """
@@ -414,7 +414,7 @@ class PIPFUCCISensor(FUCCISensor):
         raise NotImplementedError("Percentage estimate not yet implemented!")
 
     def get_estimated_cycle_percentage(
-        self, phase: str, intensities: List[float]
+        self, phase: str, intensities: list[float]
     ) -> float:
         """Estimate a cell cycle percentage based on intensities.
 
@@ -437,8 +437,8 @@ class PIPFUCCISensor(FUCCISensor):
             return self._find_g2m_percentage(intensities[1])
 
     def get_expected_intensities(
-        self, percentage: Union[float, np.ndarray]
-    ) -> List[Union[float, np.ndarray]]:
+        self, percentage: float | np.ndarray
+    ) -> list[float | np.ndarray]:
         """Return value of calibrated curves."""
         raise NotImplementedError("Intensity estimate not yet implemented!")