fucciphase 0.0.4
Cell cycle analysis plugin.
License: BSD-3-Clause
Requires Python: >=3.10

# fucciphase

[![License](https://img.shields.io/pypi/l/fucciphase.svg?color=green)](https://github.com/Synthetic-Physiology-Lab/fucciphase/raw/main/LICENSE)
[![PyPI](https://img.shields.io/pypi/v/fucciphase.svg?color=green)](https://pypi.org/project/fucciphase)
[![Python Version](https://img.shields.io/pypi/pyversions/fucciphase.svg?color=green)](https://python.org)
[![CI](https://github.com/Synthetic-Physiology-Lab/fucciphase/actions/workflows/ci.yml/badge.svg)](https://github.com/Synthetic-Physiology-Lab/fucciphase/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/Synthetic-Physiology-Lab/fucciphase/branch/main/graph/badge.svg)](https://codecov.io/gh/Synthetic-Physiology-Lab/fucciphase)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/Synthetic-Physiology-Lab/fucciphase/main.svg)](https://results.pre-commit.ci/latest/github/Synthetic-Physiology-Lab/fucciphase/main)

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:

```bash
pip install fucciphase
```

If you wish to install it from source:
    
```bash
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](examples/notebooks) can be set up with:

```bash
pip install fucciphase jupyter matplotlib pandas
````

### Install Napari + movie reading support (optional)

FUCCIphase does not install Napari by default. For .ome.tif visualisation, install:
```bash
pip install napari bioio bioio-ome-tiff bioio-tifffile
```
or, if installing from source with extras:
```bash
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](examples/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](examples/reproducibility)

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

```bash
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:

```bash
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:

[![Preview of the video](examples/reproducibility/outputs/thumbnail.png)](outputs/video_downscaled_hacat.mp4)

---

### 3 — `examples/example_data/` [📁 example_data](examples/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](https://imagej.net/plugins/trackmate/) XML file:

```python
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](https://pandas.pydata.org/) 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:

   ```bash
   fucciphase your_tracks.xml -ref your_reference.csv -dt <your timestep> -m <ch1> -c <ch2>
   ```
4. Visualize with:

   ```bash
   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:

```bash
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:
```bash
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