fucciphase 0.0.5

Cell cycle analysis plugin.

fucciphase

FUCCI cell cycle analysis plugin. Obtain cell cycle information from FUCCI fluorescence intensities.

Installation

The best way to run fucciphase is to install it in a virtual conda environment. Make sure that git is installed and can be called from the command line.

To install from pip:

pip install fucciphase

If you wish to install it from source:

git clone https://github.com/Synthetic-Physiology-Lab/fucciphase
cd fucciphase
pip install -e .

The installation should not take longer than a few seconds (depending on your internet connection).

A minimal environment for running the notebooks can be set up with:

pip install fucciphase jupyter matplotlib pandas

Install Napari + movie reading support (optional)

FUCCIphase does not install Napari by default. For .ome.tif visualisation, install:

pip install napari bioio bioio-ome-tiff bioio-tifffile

or, if installing from source with extras:

pip install -e ".[napari]"

---

What’s Inside This Repository

This repository is organized to support both analysis workflows and reproducible usage examples of FUCCIphase. If you're new to the tool, this is where to start.

1 — examples/notebooks/ 📁 notebooks

Interactive Jupyter workflows demonstrating how to use FUCCIphase in practical scenarios.

Notebook	Purpose
extract_calibration_data.ipynb	Convert raw movies + TrackMate XML into FUCCI reference curves
sensor_calibration.ipynb	Build a FUCCI sensor model from calibration traces
getting_started.ipynb	Minimal end-to-end example of FUCCIphase usage
example_estimated.ipynb	Visualize fucciphase output tables
percentage_reconstruction.ipynb	Smooth and reconstruct %phase trajectories
example_reconstruction.ipynb	Recover incomplete/noisy fluorescence traces
example_simulated.ipynb	Generate synthetic FUCCI signals for testing
color-tails-by-percentage.ipynb	Visualize population-level phase composition
explanation-dtw-alignment.ipynb	How DTW alignment works internally
phaselocking-workflow-lazy.ipynb	Scalable phase-locking for large datasets

---

2 — examples/reproducibility/ 📁 reproducibility

This is a minimal workflow that uses the sample data. Navigate to the reproducibility directory, then run the following command in one step:

fucciphase inputs/merged_linked.ome.xml `
          -ref ../example_data/hacat_fucciphase_reference.csv `
          -dt 0.25 `
          -m MEAN_INTENSITY_CH1 `
          -c MEAN_INTENSITY_CH2 `
          --generate_unique_tracks true `

and to visualize results in napari:

fucciphase-napari outputs/merged_linked.ome_processed.csv inputs/downscaled_hacat.ome.tif -m 0 -c 1 -s 2 --pixel_size 0.544

Below a preview of the output generated by the reproducibility workflow:

---

3 — examples/example_data/ 📁 example_data

Reference-style FUCCI datasets used for calibration & sensor building.

Includes:

File	Meaning
*_reference.csv	FUCCI calibration traces used to learn the sensor
*.json	Saved sensor models usable via CLI or notebooks

Use this folder if you want to train your own sensor or understand expected input format.

---

Basic usage

Fucci phase currently supports loading a TrackMate XML file:

from fucciphase import process_trackmate
from fucciphase.sensor import get_fuccisa_default_sensor

trackmate_xml = "path/to/trackmate.xml"
channel1 = "MEAN_INTENSITY_CH3"
channel2 = "MEAN_INTENSITY_CH4"

sensor = get_fuccisa_default_sensor()

df = process_trackmate(trackmate_xml,
                       channels=[channel1, channel2],
		       sensor=sensor,
                       thresholds=[0.1, 0.1])
print(df)

The TrackMate XML is converted to a Pandas DataFrame. Thus, in general data (e.g., stored in a CSV or XLSX file) that can be parsed into a DataFrame is supported.

The runtime of the scripts depends on your datasize. 2D samples with a few hundred to a few thousand cells can be processed in a few minutes. Visualization in Napari can take a bit longer. Standard processing does not require a powerful computer. Make sure that you have sufficient RAM to load videos for visualization in Napari.

Using your own data

To process your own dataset:

1. Export tracking from Fiji/TrackMate as .xml

2. Build a reference CSV (minimum one full cell cycle):

   percentage, time, cyan, magenta
   

   For reference, check the example files available in the example_data folder.

3. Run:

   fucciphase your_tracks.xml -ref your_reference.csv -dt <your timestep> -m <ch1> -c <ch2>
   

4. Visualize with:

   fucciphase-napari your_tracks_processed.csv your_video.ome.tif -m <ch1> -c <ch2> -s <mask>
   

---

Development

To develop fucciphase, clone the repository, install fucciphase in your environment and install the pre-commit hooks:

git clone https://github.com/Synthetic-Physiology-Lab/fucciphase
cd fucciphase
pip install -e ".[test, dev]"
pre-commit install

If you want to build the documentation, replace the abovementioned pip install by:

pip install -e ".[test, dev, doc]"

---

Cite us

Di Sante, M., Pezzotti, M., Zimmermann, J., Enrico, A., Deschamps, J., Balmas, E., Becca, S., Solito, S., Reali, A., Bertero, A., Jug, F. and Pasqualini, F.S., 2025. CALIPERS: Cell cycle-aware live imaging for phenotyping experiments and regeneration studies. bioRxiv, https://doi.org/10.1101/2024.12.19.629259