fucciphase 0.0.1__py3-none-any.whl

fucciphase/utils/normalize.py

@@ -0,0 +1,202 @@
+from typing import List, Optional, Tuple, Union
+
+import numpy as np
+import pandas as pd
+from scipy import signal
+
+
+def get_norm_channel_name(channel: str) -> str:
+    """Return the name of the normalized channel.
+
+    Parameters
+    ----------
+    channel : str
+        Name of the channel to normalize.
+
+    Returns
+    -------
+    str
+        Name of the normalized channel.
+    """
+    return f"{channel}_NORM"
+
+
+def get_avg_channel_name(channel: str) -> str:
+    """Return the name of the moving-averaged channel.
+
+    Parameters
+    ----------
+    channel : str
+        Name of the channel to average using moving average.
+
+    Returns
+    -------
+    str
+        Name of the moving-averaged channel.
+    """
+    return f"{channel}_AVG"
+
+
+def norm(vector: Union[pd.Series, np.ndarray]) -> Union[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.
+
+    Returns
+    -------
+    Union[pd.Series, np.ndarray]
+        Normalized vector.
+    """
+    max_ch = vector.max()
+    min_ch = vector.min()
+    norm_ch = np.round(
+        (vector - min_ch) / (max_ch - min_ch),
+        2,  # number of decimals
+    )
+
+    return norm_ch
+
+
+# flake8: noqa: C901
+def normalize_channels(
+    df: pd.DataFrame,
+    channels: Union[str, List[str]],
+    use_moving_average: bool = True,
+    moving_average_window: int = 7,
+    manual_min: Optional[List[float]] = None,
+    manual_max: Optional[List[float]] = None,
+    track_id_name: str = "TRACK_ID",
+) -> List[str]:
+    """Normalize channels, add in place the resulting columns to the
+    dataframe, and return the new columns' name.
+
+    A moving average can be applied to each individual track before normalization.
+
+    Normalization is performed by inferring the min at the position of the maximum
+    of the other channel. Then, the min is subtracted and the result is divided
+    by (max - min).
+    These values are computed across all spots in each channel. Note that the resulting
+    normalized values are rounded to the 2nd decimal.
+
+    The min and max values can be provided manually. They should be determined by
+    imaging a large number of cells statically and computing the min and max values
+    observed.
+    This option is meant for static imaging. It is assumed that there are enough cells
+    in the image to have enough samples from each phase of the cell cycle.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Dataframe
+    channels : Union[str, List[str]]
+        Name of the channels to normalize.
+    use_moving_average : bool
+        Whether to apply a moving average to each track before normalization.
+    moving_average_window : int
+        Size of the window used for the moving average, default 7.
+    manual_min : Optional[List[float]]
+        If provided, the minimum value to use for normalization.
+    manual_max : Optional[List[float]]
+        If provided, the maximum value to use for normalization.
+    track_id_name: str
+        Name of column with track IDs
+
+    Returns
+    -------
+    List[str]
+        Name of the new column(s).
+
+    Raises
+    ------
+    ValueError
+        If the dataframe does not contain the mandatory columns.
+    """
+    if not isinstance(channels, list):
+        channels = [channels]
+
+    if manual_min is not None:
+        # check that it has the same number of entries as there are channels
+        if len(manual_min) != len(channels):
+            raise ValueError(
+                f"Expected {len(channels)} values for manual_min, got {len(manual_min)}"
+            )
+    if manual_max is not None:
+        # check that it has the same number of entries as there are channels
+        if len(manual_max) != len(channels):
+            raise ValueError(
+                f"Expected {len(channels)} values for manual_max, got {len(manual_max)}"
+            )
+
+    # check that the dataframe contains the channel
+    new_columns = []
+    for channel in channels:
+        if channel not in df.columns:
+            raise ValueError(f"Column {channel} not found")
+
+        # compute the moving average for each track ID
+        if use_moving_average:
+            # apply moving average to each track ID
+            unique_track_IDs = df[track_id_name].unique()
+
+            avg_channel = get_avg_channel_name(channel)
+            for track_ID in unique_track_IDs:
+                index, ma = smooth_track(
+                    df, track_ID, channel, track_id_name, moving_average_window
+                )
+                # update the dataframe by adding a new column
+                df.loc[index, avg_channel] = ma
+
+    # normalize channels
+    for channel in 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])
+
+        # add the new column
+        new_column = get_norm_channel_name(channel)
+        df[new_column] = norm_ch
+        new_columns.append(new_column)
+
+    return new_columns
+
+
+def smooth_track(
+    df: pd.DataFrame,
+    track_ID: int,
+    channel: str,
+    track_id_name: str,
+    moving_average_window: int = 7,
+) -> Tuple[pd.Index, np.ndarray]:
+    """Smooth intensity in one channel for a single track.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Dataframe
+    track_ID: int
+        Index of track
+    channel : st
+        Name of the channel to smooth
+    track_id_name: str
+        Name of column with track IDs
+    moving_average_window : int
+        Size of the window used for the moving average, default 7.
+    """
+    # get the track
+    track: pd.DataFrame = df[df[track_id_name] == track_ID]
+
+    # compute the moving average
+    ma = signal.savgol_filter(
+        track[channel],
+        window_length=moving_average_window,
+        polyorder=3,
+        mode="nearest",
+    )
+    return track.index, ma

fucciphase/utils/phase_fit.py

@@ -0,0 +1,47 @@
+import numpy as np
+import pandas as pd
+from monotonic_derivative import ensure_monotonic_derivative
+
+
+def fit_percentages(frames: np.ndarray, percentages: np.ndarray) -> np.ndarray:
+    """Fit estimated percentages to function with non-negative derivative."""
+    best_fit: np.ndarray = ensure_monotonic_derivative(
+        x=frames,
+        y=percentages,
+        degree=1,
+        force_negative_derivative=False,
+    )
+    # clip to range (0, 100)
+    return np.clip(best_fit, 0.0, 100.0)
+
+
+def postprocess_estimated_percentages(
+    df: pd.DataFrame, percentage_column: str, track_id_name: str = "TRACK_ID"
+) -> None:
+    """Make estimated percentages continuous."""
+    if percentage_column not in df:
+        raise ValueError("The name of the percentage column is not in the DataFrame")
+    indices = df[track_id_name].unique()
+    postprocessed_percentage_column = percentage_column + "_POST"
+    df[postprocessed_percentage_column] = np.nan
+    for index in indices:
+        if index == -1:
+            continue
+        track = df[df[track_id_name] == index]
+        frames = track["FRAME"]
+        percentages = track[percentage_column]
+        if np.all(np.isnan(percentages)):
+            print("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."
+            )
+            print(track)
+        df.loc[df[track_id_name] == index, postprocessed_percentage_column] = (
+            restored_percentages
+        )

fucciphase/utils/simulator.py

@@ -0,0 +1,85 @@
+import numpy as np
+import pandas as pd
+
+from fucciphase.sensor import FUCCISASensor
+
+# TODO improve simulation, use logistic functions
+
+
+def simulate_single_channel(
+    t: np.ndarray, mean: float, sigma: float, amp: float = 1.0
+) -> np.ndarray:
+    """Simulate a single channel.
+
+    Parameters
+    ----------
+    t : np.ndarray
+        Time vector
+    mean : float
+        Mean of the Gaussian
+    sigma : float
+        Standard deviation of the Gaussian
+    amp : float
+        Amplitude of the Gaussian
+
+    Returns
+    -------
+    np.ndarray
+        Intensity vector
+    """
+    ch: np.ndarray = amp * np.exp(-((t - mean) ** 2) / (2 * sigma**2))
+
+    return np.round(ch, 2)
+
+
+def simulate_single_track(track_id: float = 42, mean: float = 0.5) -> pd.DataFrame:
+    """Simulate a single track.
+
+    Parameters
+    ----------
+    track_id : int
+        Track ID
+    mean : float
+        Temporal mean corresponding to the crossing between the two channels
+
+    Returns
+    -------
+    pd.DataFrame
+        Dataframe mocking a Trackmate single track import.
+    """
+    # example data
+    phase_percentages = [33.3, 33.3, 33.3]
+    center = [20.0, 55.0, 70.0, 95.0]
+    sigma = [5.0, 5.0, 10.0, 1.0]
+    # create sensor
+    sensor = FUCCISASensor(
+        phase_percentages=phase_percentages,
+        center=center,
+        sigma=sigma,
+    )
+    # create the time vector
+    percentage = np.arange(0, 50) / 50
+    t = 24 * percentage
+    percentage *= 100
+
+    # create the channels as Gaussian of time
+    ch1, ch2 = sensor.get_expected_intensities(percentage)
+
+    # create dataframe
+    df = pd.DataFrame(
+        {
+            "LABEL": [f"ID{i}" for i in range(len(t))],
+            "ID": list(range(len(t))),
+            "TRACK_ID": [track_id for _ in range(len(t))],
+            "POSITION_X": [np.round(mean * i * 0.02, 2) for i in range(len(t))],
+            "POSITION_Y": [np.round(mean * i * 0.3, 2) for i in range(len(t))],
+            "POSITION_T": [np.round(i * 0.01, 2) for i in range(len(t))],
+            "FRAME": list(range(len(t))),
+            "PERCENTAGE": percentage,
+            "MEAN_INTENSITY_CH1": [0 for _ in range(len(t))],
+            "MEAN_INTENSITY_CH2": [1 for _ in range(len(t))],
+            "MEAN_INTENSITY_CH3": ch1,
+            "MEAN_INTENSITY_CH4": ch2,
+        }
+    )
+    return df