fucciphase 0.0.2__tar.gz → 0.0.3__tar.gz

{fucciphase-0.0.2 → fucciphase-0.0.3}/.copier-answers.yml

@@ -1,7 +1,7 @@
 # Do not edit - changes here will be overwritten by Copier
 _commit: v1.0
 _src_path: gh:pydev-guide/pyrepo-copier
-author_email: first.last@example.com
+author_email: first.last@examples.com
 author_name: Joran Deschamps
 git_versioning: true
 github_username: jdeschamps

{fucciphase-0.0.2 → fucciphase-0.0.3}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
     # included in the sdist (unless explicitly excluded)
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
       - run: pipx run check-manifest
 
   test:
@@ -27,7 +27,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
         platform: [ubuntu-latest, macos-latest, windows-latest]
 
     steps:
@@ -36,7 +36,7 @@ jobs:
         with:
           access_token: ${{ github.token }}
 
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
 
       - name: 🐍 Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v6
@@ -85,7 +85,7 @@ jobs:
       contents: write
 
     steps:
-      - uses: actions/checkout@v5
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 

{fucciphase-0.0.2 → fucciphase-0.0.3}/.pre-commit-config.yaml

@@ -14,7 +14,7 @@ repos:
       - id: validate-pyproject
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.13.3
+    rev: v0.14.7
     hooks:
       - id: ruff
         types_or: [python, pyi, jupyter]
@@ -22,7 +22,7 @@ repos:
       - id: ruff-format
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.18.2
+    rev: v1.19.0
     hooks:
       - id: mypy
         files: "^src/"
@@ -32,6 +32,6 @@ repos:
 
   # strip out jupyter notebooks
   - repo: https://github.com/kynan/nbstripout
-    rev: 0.8.1
+    rev: 0.8.2
     hooks:
       - id: nbstripout

fucciphase-0.0.3/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: fucciphase
+Version: 0.0.3
+Summary: Cell cycle analysis plugin.
+Project-URL: homepage, https://github.com/nobias-ht/fucciphase
+Project-URL: repository, https://github.com/nobias-ht/fucciphase
+Author-email: Joran Deschamps <joran.deschamps@fht.org>
+License: BSD-3-Clause
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.8
+Requires-Dist: dtaidistance
+Requires-Dist: lineagetree<1.5.0
+Requires-Dist: matplotlib
+Requires-Dist: monotonic-derivative
+Requires-Dist: numpy
+Requires-Dist: openpyxl
+Requires-Dist: pandas
+Requires-Dist: scipy
+Requires-Dist: svgwrite
+Provides-Extra: dev
+Requires-Dist: ipython; extra == 'dev'
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pdbpp; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: rich; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: doc
+Requires-Dist: sphinx; extra == 'doc'
+Provides-Extra: jupyter
+Requires-Dist: jupyter; extra == 'jupyter'
+Provides-Extra: napari
+Requires-Dist: bioio; extra == 'napari'
+Requires-Dist: bioio-ome-tiff; extra == 'napari'
+Requires-Dist: bioio-tifffile; extra == 'napari'
+Requires-Dist: napari; extra == 'napari'
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+# 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

fucciphase-0.0.3/README.md

@@ -0,0 +1,190 @@
+# 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

fucciphase-0.0.3/examples/README.md

@@ -0,0 +1,140 @@
+# FUCCIphase – Examples and Tutorials
+
+This folder contains practical examples showing how to use FUCCIphase for:
+
+- processing TrackMate XML files  
+- estimating cell-cycle phases and percentages  
+- visualizing results with Napari  
+- reproducing analysis pipelines using Jupyter notebooks  
+
+The folder is organized into two main sections:
+````
+examples/
+│
+├── README.md
+│
+├── example_data/
+│   ├── example_data_tempophase.csv
+│   ├── fuccisa_hacat.json
+│   ├── fuccisa_hela_molcel_2017.json
+│   ├── fuccisa_tempophase.json
+│   └── hacat_fucciphase_reference.csv
+│
+├── notebooks/
+│   ├── color-tails-by-percentage.ipynb
+│   ├── example_estimated.ipynb
+│   ├── example_reconstruction.ipynb
+│   ├── example_simulated.ipynb
+│   ├── explanation-dtw-alignment.ipynb
+│   ├── extract_calibration_data.ipynb
+│   ├── getting_started.ipynb
+│   ├── movie_tails_percentages.mp4
+│   ├── percentage_reconstruction.ipynb
+│   ├── phaselocking-workflow-lazy.ipynb
+│   ├── sensor_calibration.ipynb
+│   └── README.md
+│
+└── reproducibility/
+    ├── README.md
+    │
+    ├── inputs/
+    │   ├── downscaled_hacat.ome.tif
+    │   ├── hacat_fucciphase_reference.csv
+    │   └── merged_linked.ome.xml
+    │
+    └── outputs/
+        ├── thumbnail.png
+        └── video_downscaled_hacat.mp4
+````
+---
+# 1. Quickstart: run FUCCIphase on your data
+
+If you already have:
+
+   - a TrackMate XML file  
+   - a FUCCI reference CSV  
+   - your imaging timestep
+      
+you can run FUCCIphase from the command line:
+
+```bash
+fucciphase path/to/your_tracks.xml -ref path/to/your_reference.csv -dt 0.25 -m MEAN_INTENSITY_CH1 -c MEAN_INTENSITY_CH2 --generate_unique_tracks true
+````
+
+This produces a processed CSV:
+```
+your_tracks.xml_processed.csv
+```
+containing:
+* normalized intensities
+* discrete phases
+* DTW-based cell-cycle percentages
+* per-track metadata
+
+For more details:
+```bash
+fucciphase -h
+```
+
+---
+
+# 2. Visualize your results in Napari
+
+You can launch the Napari viewer with:
+
+```bash
+fucciphase-napari your_tracks_processed.csv your_video.ome.tif -m 0 -c 1 -s 2 --pixel_size <pixel size>
+```
+
+This opens:
+
+* raw channels
+* segmentation masks
+* track overlays
+* estimated percentages as floating labels
+
+Useful for:
+
+* debugging
+* figure creation
+* validating results visually
+
+---
+
+# 3. Example Jupyter notebooks
+
+The `notebooks/` folder contains lightweight notebooks demonstrating:
+
+| Notebook                        | Description                                     |
+| ------------------------------- | ----------------------------------------------- |
+| getting_started.ipynb           | Minimal example for new users                   |
+| example_simulated.ipynb         | Simulated two-channel FUCCI traces              |
+| example_estimated.ipynb         | Percentage estimation walkthrough               |
+| example_reconstruction.ipynb    | Reconstruct intensity profiles from percentages |
+| explanation-dtw-alignment.ipynb | How DTW subsequence alignment works             |
+| color-tails-by-percentage.ipynb | Example trajectory coloring                     |
+| sensor_calibration.ipynb        | Building reference traces                       |
+
+These notebooks are intended as **mini-tutorials** for common tasks.
+
+---
+
+# 4. Full reproducibility tutorial
+
+A complete, end-to-end workflow with real data is located in:
+
+[reproducibility folder](./reproducibility/)
+
+It includes:
+
+* **inputs**: TrackMate XML, reference CSV, example video
+* **outputs**: processed CSV files, thumbnails, exported XML
+
+This is the recommended starting point for reproducing the figures shown in the repository.
+
+---
+# 5. Troubleshooting & Support
+
+If you find bugs, unexpected behavior, or want new features, open an issue:
+
+🔗 [https://github.com/Synthetic-Physiology-Lab/fucciphase/issues](https://github.com/Synthetic-Physiology-Lab/fucciphase/issues)

fucciphase-0.0.3/examples/notebooks/README.md

@@ -0,0 +1,34 @@
+# FUCCIphase example notebooks
+
+This folder contains a set of Jupyter notebooks that demonstrate how to use
+**FUCCIphase** in different scenarios, from basic usage to more advanced
+workflows such as calibration, simulation and reconstruction.
+
+All notebooks assume that:
+
+- `fucciphase` is installed in your environment (e.g. `pip install -e .` from the repo root)
+- `jupyter` is installed (e.g. `pip install jupyter`)
+- You run the notebooks from the **repository root** or from within
+  the `examples` folder so that relative paths to data files work.
+
+> 💡 Tip: start Jupyter from the repo root:
+> ```bash
+> cd path/to/fucciphase
+> jupyter notebook
+> ```
+> then navigate to `examples/notebooks/`.
+
+## Notebook overview
+
+| Notebook file                          | Purpose                                                                                              | 
+|----------------------------------------|------------------------------------------------------------------------------------------------------|
+| `getting_started.ipynb`                | Minimal end-to-end example: load TrackMate output, apply a FUCCI sensor, inspect results.            | 
+| `extract_calibration_data.ipynb`       | Extract FUCCI calibration time-courses from raw movies (TrackMate XML + images) to build references. | 
+| `sensor_calibration.ipynb`             | Build or inspect a FUCCI sensor from calibration data (e.g. HaCaT reference traces).                 | 
+| `explanation-dtw-alignment.ipynb`      | Explain and demonstrate the DTW-based alignment used for phase estimation and CALIPERS workflows.    | 
+| `example_simulated.ipynb`              | Simulate synthetic FUCCI trajectories and test FUCCIphase on controlled, ground-truth data.          |
+| `example_reconstruction.ipynb`         | Reconstruct FUCCI signals or phase trajectories from partial / noisy data and compare to originals.  | 
+| `percentage_reconstruction.ipynb`      | Reconstruct and smooth phase-percentage trajectories and compare raw vs reconstructed dynamics.      | 
+| `phaselocking-workflow-lazy.ipynb`     | Phase-lock and align many trajectories to a common reference using a lightweight, scalable workflow. | 
+| `example_estimated.ipynb`              | Explore and visualise FUCCIphase output tables with per-cell phase estimates over time.              | 
+| `color-tails-by-percentage.ipynb`      | Visualise phase distributions over time or conditions as “colour tail” plots for figures.            |