Version 1 with Graphical User Interface

TRACE-QC v1.0.0 - Web Application Release 🚀

Major Update: Graphical User Interface

We're excited to announce TRACE-QC v1.0.0, featuring a brand new web-based graphical user interface that makes quality control of 3D cell
culture imaging accessible to researchers without programming experience!

🎯 What's New

Web Application (gui/)

A complete Streamlit-based web interface that allows biologists to perform TRACE-QC analysis through a point-and-click workflow:

• 📤 Drag & Drop Upload: Simple CSV/TXT file upload with automatic format detection
• ⚙️ Interactive Configuration: Visual parameter selection with sliders and dropdowns
• ▶️ One-Click Analysis: Run TRACE-QC with a single button press and real-time progress tracking
• 📊 Visual Dashboard: Publication-quality plots and comprehensive QC reports
• 💾 Easy Export: Download corrected data, metrics, and QC reports with one click

Key Features

Zero Coding Required

• Upload your data file
• Configure settings visually
• Run analysis with one click
• Download corrected results

Intelligent Data Handling

• Supports both wide and long CSV formats
• Automatic format detection and conversion
• Real-time data validation with clear error messages
• Handles 2-12+ spheroids and 2-7+ time points

Comprehensive Quality Control

• Automated QC with normalized Fréchet distance metric
• Clear PASS/FAIL indicators with color-coded visualizations
• Detailed QC reports generated automatically
• Visual and numerical validation

Professional Visualizations

• Normalized Fréchet distance over time
• QC pass/fail summary charts
• Alignment geometry displays
• Spheroid trajectory analysis
• All plots publication-ready

📥 Installation

# Clone or update the repository
git clone https://github.com/emcramer/TRACEQC.git
cd TRACEQC

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

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

Or use the convenient launcher scripts:

./launch_gui.sh        # Linux/macOS
launch_gui.bat         # Windows (double-click)

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

🚀 Quick Start

5 minutes from installation to results:

1. Install: pip install -r gui/requirements.txt
2. Launch: streamlit run gui/app.py
3. Upload: Drag and drop your CSV file (example provided in gui/example_data/)
4. Configure: Set your sample name and verify time points
5. Run: Click "Run TRACE-QC Analysis"
6. Download: Export corrected data and QC reports

See gui/QUICKSTART.md for detailed instructions.

📊 Example Dataset

Try it out with the included sample dataset:

Example file location

gui/example_data/sample_spheroids.csv

📚 Documentation

New comprehensive documentation includes:

• gui/README.md - Complete usage guide
• gui/QUICKSTART.md - 5-minute tutorial
• gui/INSTALLATION.md - Detailed setup instructions
• README.md - Overview with GUI section

🔧 Technical Details

File Structure

gui/
├── app.py # Main Streamlit application (500+ lines)
├── requirements.txt # GUI-specific dependencies
├── utils/
│ ├── data_parser.py # Data parsing and validation
│ └── visualization.py # Plotting functions
└── example_data/
└── sample_spheroids.csv

Dependencies

• streamlit>=1.28.0 - Web framework
• pandas>=1.3.0 - Data processing
• numpy>=1.20.0 - Numerical operations
• matplotlib>=3.4.0 - Visualizations
• seaborn>=0.11.0 - Enhanced plotting

🎨 User Experience

Designed for biologists:

• No programming knowledge required
• Step-by-step guided workflow
• Immediate visual feedback
• Clear error messages
• Professional scientific aesthetic

Quality control in minutes:

• Upload → Configure → Run → Download
• Automated QC with accuracy threshold
• Visual and numerical validation
• Comprehensive reports

🌟 Impact

This release expands access to TRACE-QC by:

• Removing the coding barrier for experimental biologists
• Accelerating quality control workflows
• Preventing data misinterpretation from displacement artifacts
• Enabling high-throughput spheroid screening

📈 What's Changed

Added

• Complete web-based GUI with 4-tab workflow interface
• Automatic data format detection (wide/long CSV)
• Real-time data validation pipeline
• Interactive visualizations dashboard
• One-click result downloads (CSV, TXT reports)
• Example datasets for testing
• Launcher scripts for easy startup
• Comprehensive GUI documentation

Updated

• Main README.md with GUI quick start section
• Repository structure documentation

Maintained

• Full backward compatibility with Python API
• All existing functionality preserved
• Original command-line workflow unchanged

🐛 Known Issues

None reported. Please submit issues at: https://github.com/emcramer/TRACEQC/issues

⚙️ System Requirements

• Python: 3.8 or higher
• OS: Windows, macOS, or Linux
• RAM: Minimum 4 GB (8 GB recommended)
• Browser: Any modern browser (Chrome, Firefox, Safari, Edge)

🔗 Links

• Paper: https://doi.org/10.1016/j.crmeth.2025.101237
• Documentation: gui/README.md
• Quick Start: gui/QUICKSTART.md
• Example Data: gui/example_data/sample_spheroids.csv
• Issues: https://github.com/emcramer/TRACEQC/issues

📄 Citation

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

Cramer, E. M. et al. Temporal reassignment and correspondence evaluation with quality control for time-course imaging of 3D cell culture. Cell Reports Methods 5, 101237 (2025). DOI: https://doi.org/10.1016/j.crmeth.2025.101237

🙏 Acknowledgments

This work was supported by the Jayne Koskinas Ted Giovanis Foundation for Health and Policy, NIH/NCI U24CA284156, NIH/NCI T32CA153952, and NIH/NIGMS T32GM141938.

---

Download this release to get started with the GUI today!

For questions or support: chanyo@ohsu.edu or open an issue on GitHub.

---

v0.0.2-alpha

TRACE-QC Release 0.0.2-alpha

Algorithm named to TRACE-QC and additional comparisons/benchmarking added to evaluate algorithm robustness. Please see the full changelog below for a detailed breakdown of changes.

Full Changelog: v0.0.1-alpha...v0.0.2-alpha

Other changes include indexing the package on Zenodo.

align_spheroid

Initial version of the class and algorithm for correctly matching time course microscopy images of matrix embedded objects based on the microscope's field of view coordinates after drift or displacement due to perturbation during the experiment.