Skip to content

Version 1 with Graphical User Interface

Latest
Latest

Choose a tag to compare

View all tags
@emcramer emcramer released this 02 Dec 18:23
· 5 commits to main since this release
v1.0.0
c0ef14a
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

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

📄 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.

Assets 3
Loading