Skip to content
BranchesTags

Repository files navigation



TRACE-QC: Temporal Reassignment and Correspondence Evaluation with Quality Control

DOI Paper

TRACE-QC is a Python package for automated quality control and correction of mislabeling in longitudinal imaging of 3D cell cultures. Using a parameter-free algorithm that operates solely on image metadata, TRACE-QC detects and corrects spatial displacement artifacts in time-course imaging of tumor spheroids, organoids, and other matrix-embedded 3D structures.

Publication

Temporal reassignment and correspondence evaluation with quality control for time-course imaging of 3D cell culture Eric M. Cramer, Tamara Lopez-Vidal, Jeanette Johnson, Vania Wang, Daniel R. Bergman, Ashani Weeraratna, Richard Burkhart, Elana J. Fertig, Jacquelyn W. Zimmerman, Laura M. Heiser, and Young Hwan Chang Cell Reports Methods 5, 101237 (2025) DOI: 10.1016/j.crmeth.2025.101237

The Problem

During long-term imaging of 3D cell cultures embedded in extracellular matrix:

  • Matrix displacement can occur from detachment, rotation, or mechanical disruption
  • Spheroids are mislabeled when imaged at previous locations after moving
  • Manual correction is time-consuming and error-prone for high-throughput experiments
  • Data integrity is compromised without proper quality control

In our experimental dataset, 9 out of 12 wells (75%) showed displacement, affecting 66% of total measurements.

The Solution

TRACE-QC provides:

  • ✅ Automated mislabeling detection and correction using image coordinates (X, Y metadata)
  • ✅ Parameter-free algorithm requiring no tuning or ground truth data
  • ✅ Quality control metric (normalized Fréchet distance) for automated decision-making
  • ✅ No experimental modifications needed - works with existing imaging workflows

How It Works

TRACE-QC uses a two-stage algorithm:

  1. Permutation-based matching: Finds optimal point correspondence by minimizing the L2 norm of distance matrix differences
  2. Procrustes alignment: Applies SVD-based rotation and translation to align spheroid positions

The algorithm corrects for:

  • Global well rotations
  • Global translations (matrix shifts)
  • Local spheroid movements (jittering)

Quality Control: Normalized Fréchet distance ≤ 1.0 indicates successful alignment (~90% accuracy).

Repository Structure

(Key files described)

TRACEQC/
├── align_spheroid/          # Core Python package
│   ├── __init__.py          # Package initialization
│   ├── alignment.py         # Main TRACE-QC algorithm (Aligner2D class)
│   ├── alignment_polygon.py # Alternative polygon-based alignment
│   ├── evaluation.py        # Quality control metrics and evaluation functions
│   ├── synthetic_data.py    # CellSimulator for generating test data
│   └── utils.py             # Utility functions
├── gui/                     # Web application (NEW!)
│   ├── app.py              # Streamlit web interface
│   ├── requirements.txt    # GUI-specific dependencies
│   ├── README.md           # GUI documentation
│   ├── utils/              # GUI utility modules
│   │   ├── data_parser.py  # Data parsing and validation
│   │   └── visualization.py # Plotting functions
│   └── example_data/       # Sample datasets for testing
│       ├── sample_spheroids.csv
│       ├── example_well_b2.csv  # Example data with successful alignment
│       └── example_well_b3.csv  # Example data with unsuccessful alignment due to matrix degradation
├── tests/                   # Unit tests
│   ├── test_alignment.py    # Tests for alignment algorithms
│   ├── test_evaluation.py   # Tests for evaluation metrics
│   └── test_synthetic_data.py # Tests for synthetic data generation
├── paper/                   # Jupyter notebooks for manuscript figures
│   ├── figure-1.ipynb       # Figure 1: Experimental setup and displacement
│   ├── figure-2.ipynb       # Figure 2: Algorithm performance
│   ├── figure-3.ipynb       # Figure 3: Biological data application
│   └── tracker-comparison.ipynb # Algorithm benchmarking
├── synthetic-example.ipynb  # Example notebook demonstrating TRACE-QC
├── requirements.txt         # Python dependencies
├── LICENSE                  # MIT License
└── README.md               # This file

Installation

1. Clone the repository

git clone https://github.com/emcramer/TRACEQC.git
cd TRACEQC

2. Create a virtual environment (recommended)

python3 -m venv venv
source venv/bin/activate  # On Linux/macOS
# OR
venv\Scripts\activate     # On Windows

3. Install dependencies

pip install -r requirements.txt

Quick Start

Option 1: Web Application (No Coding Required) 🌐

Use the TRACE-QC web interface for a user-friendly, point-and-click experience! The streamlit application is available online for those who want to to access the GUI and upload your data to run TRACEQC. If you wish to run the GUI locally, download the repo and run the following:

# Install GUI dependencies
pip install -r gui/requirements.txt

# Start the web application
streamlit run gui/app.py

The application will open in your browser at http://localhost:8501.

To use the GUI, simply:

  1. Upload your CSV/TXT data file (<50 MB)
  2. Configure settings
  3. Click "Run Analysis"
  4. Download results

See the GUI README for detailed instructions. GIF demo below.

Demonstration of the TRACEQC graphical user interface.

Option 3: Python API (For Programmatic Use)

For integration into analysis pipelines or custom scripts:

from align_spheroid import Aligner2D
import numpy as np

# Prepare your data: shape (n_points, n_timepoints)
# dataX and dataY contain x,y coordinates for each spheroid at each time point
time_points = ['0h', '24h', '48h', '72h', '168h']

# Initialize and run TRACE-QC
aligner = Aligner2D(well_name="Well_A1", time_points=time_points)
aligner.align(dataX, dataY)

# Access corrected results
corrected_data = aligner.registered_df  # DataFrame with corrected labels
aligned_coords = aligner.aligned_points  # List of aligned coordinates

# Visualize alignment
aligner.plot(show_plot=True)

# Quality control: Check normalized Fréchet distance
from align_spheroid.evaluation import normalize_distance, calculate_frechet

frechet_dist = calculate_frechet(aligner.aligned_points[0], aligner.aligned_points[1])
norm_frechet = normalize_distance(aligner.aligned_points[0], frechet_dist)
print(f"Normalized Fréchet distance: {norm_frechet:.2f}")
if norm_frechet <= 1.0:
    print("✓ Alignment successful")
else:
    print("✗ Extreme displacement detected - manual review recommended")

Generate Synthetic Data for Testing

from align_spheroid import CellSimulator

# Create simulator
sim = CellSimulator(
    n_circles=6,
    width=1000,
    height=1000,
    rng=np.random.default_rng(seed=42)
)

# Simulate displacement over time
simulated_data = sim.simulate(
    time_points=['0h', '24h', '48h', '72h'],
    rotations=[15, 30, 45],              # Rotation angles (degrees)
    translations=[(10, 10), (20, 15), (15, 25)],  # (dx, dy) translations
    jitters=[(5, 5), (5, 5), (5, 5)],    # Random jittering
    shuffle_points=True                   # Shuffle row order (mimics real data)
)

Running Tests

Run all tests using pytest:

pytest tests/

Run specific test modules:

pytest tests/test_alignment.py
pytest tests/test_evaluation.py
pytest tests/test_synthetic_data.py

Examples and Demos

Synthetic Data Example

See synthetic-example.ipynb for a complete walkthrough demonstrating:

  • Synthetic spheroid data generation
  • Application of TRACE-QC algorithm
  • Visualization of alignment results
  • Quality control metric calculation
jupyter notebook synthetic-example.ipynb

Manuscript Figures

The paper/ directory contains notebooks reproducing all figures from the publication:

jupyter notebook paper/figure-1.ipynb  # Experimental setup and displacement
jupyter notebook paper/figure-2.ipynb  # Algorithm performance validation
jupyter notebook paper/figure-3.ipynb  # Application to biological data
jupyter notebook paper/tracker-comparison.ipynb  # Benchmarking vs other methods

Note: Figure notebooks require the biological dataset (available on Zenodo).

Applications

TRACE-QC is designed for:

  • Tumor spheroid assays (invasion, drug screening, growth dynamics)
  • Organoid cultures (development, differentiation studies)
  • Any 3D culture embedded in extracellular matrix with longitudinal imaging
  • High-throughput screens where manual quality control is impractical

Key Features

Core Algorithm (align_spheroid/alignment.py)

  • Aligner2D class: Main TRACE-QC implementation
  • Permutation-based optimization using L2 norm of distance matrices
  • Procrustes analysis with SVD for rotation/translation
  • Handles global rotations, translations, and local jittering
  • Method chaining support

Quality Control Metrics (align_spheroid/evaluation.py)

  • Normalized Fréchet distance (primary QC metric)

Synthetic Data Generation (align_spheroid/synthetic_data.py)

  • CellSimulator: Generate synthetic spheroid data
  • Configurable transformations (rotation, translation, jittering)
  • Individual cell movement simulation
  • Ground truth labels for validation

Limitations

TRACE-QC may fail or produce suboptimal results when:

  1. Perfectly symmetrical arrangements: Regular polygons (square, hexagon) cause rotational ambiguity
  2. Extreme displacement: Normalized Fréchet distance > 1.0
  3. Very close initial spacing: Small nearest-neighbor distances increase sensitivity
  4. Variable spheroid numbers: Algorithm requires same N at all time points
  5. Matrix degradation: Severe fragmentation over time

Important: Algorithm failure can itself be a valuable QC signal indicating spheroid fusion, dissolution, or matrix instability.

Computational Requirements

  • Python 3.8+
  • Memory: Scales with O(N! × N²) for permutation step
  • Recommended: N ≤ 8-10 spheroids per well for practical runtimes
  • For larger N, consider alternative methods (SCS) or spatial partitioning

Citation

If you use TRACE-QC in your research, please cite:

@article{cramer2025trace,
  title={Temporal reassignment and correspondence evaluation with quality control for time-course imaging of 3D cell culture},
  author={Cramer, Eric M and Lopez-Vidal, Tamara and Johnson, Jeanette and Wang, Vania and Bergman, Daniel R and Weeraratna, Ashani and Burkhart, Richard and Fertig, Elana J and Zimmerman, Jacquelyn W and Heiser, Laura M and Chang, Young Hwan},
  journal={Cell Reports Methods},
  volume={5},
  pages={101237},
  year={2025},
  publisher={Elsevier},
  doi={10.1016/j.crmeth.2025.101237}
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contact

For questions, issues, or collaboration inquiries:

Acknowledgments

This work was supported by:

  • Jayne Koskinas Ted Giovanis Foundation for Health and Policy
  • NIH/NCI U24CA284156
  • NIH/NCI T32CA153952
  • NIH/NIGMS T32GM141938
  • Charles and Margaret Levin Family Foundation
  • Dana & Albert R. Broccoli Charitable Foundation

We thank Dr. David Tuveson, Dr. Dennis Plenker, Dr. Amber Habowski, and Hardik Patel for kindly sharing the hT231 cell line.

About

A python package for quality control of data from time-course imaging of 3D cell culture.

Resources

Readme
MIT license
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Contributors

Languages