Skip to content

README.md

Latest commit

 

History

History
299 lines (197 loc) · 6.98 KB

README.md

File metadata and controls

299 lines (197 loc) · 6.98 KB
Raw

TRACE-QC Web Application

A user-friendly web interface for quality control of 3D cell culture time-course imaging data.

Overview

The TRACE-QC web application provides an intuitive interface for biologists and researchers to:

  • Upload spheroid position data
  • Run the TRACE-QC algorithm without coding
  • Visualize alignment results
  • Review quality control metrics
  • Download corrected data and reports

Features

  • 🖱️ Drag & Drop: Easy file upload interface
  • 📊 Interactive Visualizations: Real-time plots and dashboards
  • ✅ Automated QC: Immediate quality control feedback
  • 💾 Export Results: Download corrected data and reports
  • 📱 Responsive Design: Works on desktop and tablet devices

Installation

Prerequisites

  • Python 3.8 or higher
  • pip package manager

Quick Install

  1. Navigate to the TRACEQC directory:
cd /path/to/TRACEQC
  1. Install GUI dependencies:
pip install -r gui/requirements.txt

Alternatively, if you've already installed the main package:

cd gui
pip install streamlit seaborn plotly

Running the Application

Start the Web Server

From the TRACEQC root directory:

streamlit run gui/app.py

Or from the gui directory:

cd gui
streamlit run app.py

The application will automatically open in your default web browser at:

http://localhost:8501

Stop the Server

Press Ctrl+C in the terminal where the server is running.

Usage Guide

Step 1: Upload Data

  1. Navigate to the "Upload Data" tab
  2. Click "Browse files" or drag and drop your CSV/TXT file (<50 MB)
  3. Review the data preview and validation results

Data Format Requirements

Your data file should contain X and Y coordinates for each spheroid at each time point.

Supported Format 1: Wide Format (Recommended)

spheroid_id,x_0h,y_0h,x_24h,y_24h,x_48h,y_48h,x_72h,y_72h
A,100.5,200.3,105.2,198.1,110.8,195.4,115.3,192.7
B,150.2,220.4,148.6,222.1,145.9,225.3,143.2,228.5
C,180.7,190.2,182.3,188.9,185.1,186.5,188.4,184.2

Supported Format 2: Long Format

spheroid_id,timepoint,x,y
A,0h,100.5,200.3
A,24h,105.2,198.1
A,48h,110.8,195.4
B,0h,150.2,220.4
B,24h,148.6,222.1
B,48h,145.9,225.3

Step 2: Configure Settings

  1. Go to the "Configure" tab
  2. Enter a descriptive name for your sample/well
  3. Verify detected time points are correct
  4. Adjust QC threshold if needed (default: 1.0)
  5. Select visualization options

QC Threshold:

  • Values ≤ 1.0 indicate successful alignment (~90% accuracy)
  • Increase threshold for more lenient QC
  • Decrease threshold for stricter QC

Step 3: Run Analysis

  1. Navigate to the "Run Analysis" tab
  2. Review your configuration
  3. Click "Run TRACE-QC Analysis"
  4. Wait for the progress bar to complete

The analysis typically takes a few seconds for standard datasets (4-6 spheroids).

Step 4: View Results

  1. Go to the "Results" tab to see:

    • Quality Control Summary: Overall pass/fail status
    • Metrics Table: Normalized Fréchet distance for each time point
    • Visualizations:
      • Fréchet distance over time
      • QC status pie chart
      • Alignment geometry plots
      • Spheroid trajectory analysis

  2. Download results:

    • Corrected Data (CSV): Aligned coordinates with corrected labels
    • QC Report (TXT): Detailed quality control report
    • Metrics (CSV): Quality metrics by time point

Interpreting Results

QC Status: PASSED ✅

The alignment was successful. All time points show normalized Fréchet distances below the threshold. Your data can be used for downstream analysis with confidence.

QC Status: FAILED ⚠️

One or more time points show extreme displacement. This may indicate:

  • Matrix detachment or severe rotation
  • Spheroid fusion or loss events
  • Matrix degradation
  • Experimental artifacts

Action: Review visualizations carefully and consider manual inspection of problematic time points.

Example Dataset

A sample dataset is provided in gui/example_data/ for testing:

# Copy to downloads or desktop for easy access
cp gui/example_data/sample_spheroids.csv ~/Desktop/

Then upload this file through the web interface to see how the application works.

Troubleshooting

Application Won't Start

Error: ModuleNotFoundError: No module named 'streamlit'

Solution: Install dependencies

pip install -r gui/requirements.txt

Data Upload Fails

Error: "Could not detect data format"

Solution:

  • Ensure your CSV has headers
  • Check that column names follow the format: x_0h, y_0h, x_24h, y_24h, etc.
  • Or use long format with columns: spheroid_id, timepoint, x, y

Analysis Fails

Error: "Error during analysis"

Possible causes:

  • Missing or NaN values in coordinate columns
  • Mismatched number of X and Y columns
  • Non-numeric values in coordinate columns

Solution:

  • Review the validation errors in the Upload tab
  • Check your data file for missing values
  • Ensure all coordinates are numeric

Slow Performance

For datasets with > 10 spheroids, the permutation step may be slow due to factorial complexity.

Solutions:

  • Reduce the number of spheroids if possible
  • Consider using the Python API directly for batch processing
  • Use a more powerful machine

Advanced Usage

Custom Port

Run on a different port:

streamlit run gui/app.py --server.port 8502

Remote Access

To access from other devices on your network:

streamlit run gui/app.py --server.address 0.0.0.0

Then access at http://YOUR_IP:8501

⚠️ Security Warning: Only do this on trusted networks.

Command Line Options

streamlit run gui/app.py --help

Technical Details

Architecture

  • Frontend: Streamlit (Python web framework)
  • Backend: TRACE-QC align_spheroid package
  • Visualization: Matplotlib, Seaborn, Plotly
  • Data Processing: Pandas, NumPy

File Structure

gui/
├── app.py                  # Main Streamlit application
├── requirements.txt        # GUI dependencies
├── README.md              # This file
├── utils/
│   ├── __init__.py        # Package initialization
│   ├── data_parser.py     # Data parsing and validation
│   └── visualization.py   # Plotting functions
└── example_data/
    └── sample_spheroids.csv  # Example dataset

Support

For issues, questions, or feature requests:

Citation

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

Cramer et al., 2025, Cell Reports Methods 5, 101237 DOI: 10.1016/j.crmeth.2025.101237

License

MIT License - see LICENSE file for details.

Acknowledgments

TRACE-QC GUI was developed to make quality control of 3D cell culture imaging accessible to researchers without programming experience.

Special thanks to the Streamlit community for the excellent web framework.