Skip to content

v1.2.0

Latest
Latest

Choose a tag to compare

View all tags
@dpatel511 dpatel511 released this 18 Oct 21:41
· 131 commits to main since this release
v1.2.0
d3ce424

MetaQuest v1.2.0 - Major Feature Release

Release Date: October 2025
Status: Stable
License: TBD

🎉 Overview

MetaQuest v1.2.0 represents a significant leap forward in metagenomics analysis capabilities. This release introduces enhanced functional annotation, advanced gene prediction controls, professional logging systems, and a comprehensive reporting engine - transforming MetaQuest into a complete solution for both clinical diagnostics and research applications.

🚀 What's New in v1.2.0

1. Enhanced Functional Annotation System

Dual-Database Annotation

  • COG Database Integration: Comprehensive functional categories and orthologous groups for detailed pathway analysis
  • SwissProt Database Integration: High-quality, manually curated protein annotations for accurate functional characterization
  • Combined Annotation Strategy: Dramatically increased coverage and annotation depth compared to single-database approaches
  • Mobile Genetic Element Analysis: Specialized tracking of IS families, transposases, and other mobile elements

Key Benefits:

  • Significantly higher annotation coverage (typically 60-80% vs 30-50% with single databases)
  • More detailed functional category distributions
  • Enhanced pathway and process enrichment insights
  • Better detection of horizontally transferred genes

2. Advanced Gene Prediction Controls

Customizable Contig Filtering

  • Default Behavior: Automatic filtering of contigs <1000bp before annotation for optimal performance
  • Custom Thresholds: --min-contig-length flag for user-defined filtering criteria
  • Complete Flexibility: --no-filter-contigs option to annotate all sequences regardless of length
  • Performance Optimization: Balanced approach between annotation quality and computational efficiency

Enhanced tbl2asn Management

  • Automatic Timeout Control: Default 300-second timeout prevents hung processes
  • Auto-Kill Functionality: Stuck tbl2asn processes are automatically terminated and recovery initiated
  • Configurable Timeouts: --tbl2asn-timeout allows customization for large datasets
  • Override Option: --no-kill-tbl2asn for datasets requiring unlimited processing time

Threading Optimization

  • Parallel Processing: --annotation-threads flag for optimal resource utilization
  • Scalable Performance: Adjust thread count based on available system resources
  • Improved Speed: Significantly faster annotation on multi-core systems

3. Professional Logging System

Standard Mode (Default)

  • Clean, user-friendly progress tracking with visual indicators
  • Formatted section headers with clear visual separators
  • Progress spinners for long-running operations
  • Color-coded status messages (✓ success, ✗ error, ⚠ warning)
  • Time-formatted completion summaries for all operations

Debug Mode (--debug flag)

  • Complete diagnostic output for troubleshooting
  • Full command-line invocations for all external tools
  • Complete stdout/stderr streams from programs
  • Detailed error traces with stack information
  • Performance metrics and timing data
  • Essential for development and issue resolution

Structured Logging

  • Consistent format across all pipeline operations
  • Automatic logging to metaquest.log in output directory
  • Timestamps and operation context for all events
  • Hierarchical message organization

4. Comprehensive Reporting Engine

Enhanced Text Reports

Taxonomic Reports

  • Clinical Summary: Immediate actionable insights for healthcare professionals
  • Researcher View: Detailed taxonomic breakdown with statistical metrics
  • Diversity Metrics: Shannon, Simpson, Chao1, and Observed Species indices
  • Abundance Profiles: Hierarchical taxonomic composition from phylum to species

Functional Reports (NEW)

  • COG Category Analysis: Detailed functional category distributions with percentages
  • Mobile Element Tracking: IS family classification and transposase detection
  • Annotation Quality Metrics: Coverage scores, identity percentages, functional diversity
  • Pathway Enrichment: Identification of over-represented biological processes
  • Protein Function Summary: Top annotated proteins with functional descriptions

Pathogen Risk Reports

  • Three-Tier Risk Assessment: High/Medium/Low risk stratification
  • Integrated Risk Scoring: Combined pathogenicity, AMR, and virulence scores
  • Clinical Interpretation: Actionable recommendations for healthcare providers
  • Evidence-Based Assessment: Citations to pathogen and resistance databases

Professional Formatting

  • Emoji indicators for quick visual scanning (🦠 🔬 ⚠️ ✓)
  • Clear section headers and structured organization
  • Role-based content tailored to clinicians vs researchers
  • Quality metrics prominently displayed

5. Improved Architecture & Maintainability

Code Refactoring

  • Enhanced modular architecture in reporting/ module
  • Separation of concerns between data processing and presentation
  • Reusable base classes for consistent formatting
  • Improved error handling and validation

Enhanced Visualization System

  • Modular visualization components for easier maintenance
  • Specialized plotters for different analysis types
  • Modern color schemes and publication-ready aesthetics
  • Responsive design for various output formats

🔧 Key Improvements

Performance Enhancements

  • Faster Annotation: Optimized COG and SwissProt database queries
  • Memory Efficiency: Reduced memory footprint for large dataset processing
  • Parallel Processing: Better utilization of multi-core systems
  • Database Integration: Combined databases reduce redundant searches

Usability Improvements

  • Clearer Progress Tracking: Real-time feedback on operation status
  • Better Error Messages: Actionable guidance for common issues
  • Flexible Configuration: Extensive command-line options for customization
  • Comprehensive Documentation: Updated guides and examples

Robustness & Reliability

  • Enhanced Error Handling: Graceful failure recovery mechanisms
  • Input Validation: Comprehensive checks before processing
  • Process Management: Automatic handling of stuck or failed external tools
  • Quality Assurance: Built-in checks for annotation quality

📊 Example Usage

Basic Analysis with Enhanced Features

# Standard FASTQ analysis with dual-database annotation
metaquest analyze fastq --single sample.fastq.gz -o results/

# View comprehensive reports
cat results/taxonomic_report.txt
cat results/functional_report.txt
cat results/pathogen_risk_report.txt

Advanced Annotation Controls

# Custom contig filtering (500bp threshold)
metaquest analyze fastq --single reads.fq --min-contig-length 500 -o results/

# Annotate all contigs without filtering
metaquest analyze fasta assembly.fasta --no-filter-contigs -o results/

# Extended timeout for large datasets
metaquest analyze fastq --paired R1.fq R2.fq --tbl2asn-timeout 600 -o results/

# Maximum parallelization
metaquest analyze fasta genome.fasta --annotation-threads 16 -o results/

Debug Mode for Troubleshooting

# Run with complete diagnostic output
metaquest --debug analyze fastq --single sample.fq -o debug_results/

# Debug output includes:
# - Full command invocations for all tools
# - Complete tool output streams
# - Detailed error traces
# - Performance timing information

Skip Annotation for Rapid Taxonomic Analysis

# Fast taxonomic-only analysis
metaquest analyze fastq --single sample.fastq.gz --skip-annotation -o fast_results/

🛠 Installation & Updates

New Installation

# Clone repository
git clone https://github.com/your-org/metaquest.git
cd metaquest

# Create environment
conda env create -f environment.yml
conda activate metaquest

# Install MetaQuest
pip install -e .

# Download COG and SwissProt databases
./scripts/setup_databases.sh

# Verify installation
metaquest check

Updating from v1.1.0

# Update repository
cd metaquest
git pull origin main

# Update environment (if needed)
conda env update -f environment.yml

# Reinstall package
pip install -e .

# Download new databases
./scripts/setup_databases.sh --cog --swissprot

# Verify update
metaquest check

📚 Updated Documentation

  • Installation Guide - Updated with database setup instructions
  • Usage Guide - Comprehensive examples for new features
  • Annotation Guide - NEW: COG and SwissProt database information
  • Interactive Help: metaquest --help for complete command reference

🔬 System Requirements

Minimum Requirements (Unchanged)

  • Operating System: Linux or macOS
  • RAM: 8GB (16GB recommended for large datasets)
  • Disk Space: 50GB available for databases and results
  • Software: Conda package manager

Updated Database Requirements

  • Kraken2: ~8GB disk space
  • Pathogen DBs (CARD + VFDB): ~500MB disk space
  • COG Database: ~1GB disk space (NEW)
  • SwissProt Database: ~1GB disk space (NEW)
  • Total Database Storage: ~11GB

🎯 Use Cases

Clinical Applications

  • Pathogen Identification: Enhanced functional characterization for better diagnosis
  • AMR Profiling: Mobile genetic element tracking for resistance gene detection
  • Outbreak Investigation: Comprehensive functional comparison across samples
  • Quality Control: Professional logging for compliance and auditing

Research Applications

  • Microbiome Studies: Detailed functional annotation for pathway analysis
  • Comparative Genomics: Dual-database approach for comprehensive gene characterization
  • Functional Metagenomics: Enhanced COG categories for metabolic reconstruction
  • Method Development: Debug mode for pipeline optimization and validation

🐛 Bug Fixes

  • Fixed memory leak in large FASTA processing
  • Resolved tbl2asn hanging issues on complex assemblies
  • Corrected annotation statistics calculation for filtered contigs
  • Fixed report generation errors with special characters in sample names
  • Improved handling of incomplete database downloads

⚠️ Breaking Changes

None

This release maintains full backward compatibility with v1.1.0. All existing commands and workflows continue to function as expected.

Deprecated Features

  • Single-database annotation (still supported but not recommended)
  • Legacy logging format (replaced by professional logging system)

🔮 Roadmap

Upcoming in v1.3.0 (Q1 2026)

  • Metagenomic Assembly: SPAdes integration for de novo assembly
  • Enhanced Virulence Analysis: Comprehensive virulence factor detection
  • Extended AMR Characterization: Additional resistance mechanism profiling
  • Metabolic Pathway Reconstruction: KEGG integration for pathway analysis

Future Releases

  • Additional Database Support: Pfam, TIGRFAMs integration (Q2 2026)
  • Cloud Computing Support: AWS/GCP deployment options (Q3 2026)
  • Web Interface: Interactive browser-based analysis (Q4 2026)
  • API Access: Programmatic pipeline control (Q4 2026)

🤝 Contributing

We welcome community contributions! Priority areas for v1.2.x:

  • Annotation Optimization: Improve COG/SwissProt coverage algorithms
  • Database Curation: Help maintain and update functional databases
  • Clinical Validation: Real-world testing in diagnostic settings
  • Documentation: User guides and tutorial development
  • Testing: Dataset validation and benchmarking studies

See our contributing guidelines for more information.

📞 Support

Troubleshooting Tips

  1. Always use --debug flag when reporting issues
  2. Check metaquest.log in your output directory
  3. Run metaquest check to verify system dependencies
  4. Ensure databases are properly downloaded with ./scripts/setup_databases.sh --all

🏆 Acknowledgments

MetaQuest Development Team - Advancing metagenomics through integrated computational solutions

Special thanks to:

  • Early adopters who provided valuable feedback on annotation systems
  • Contributors who helped validate functional annotation accuracy
  • Clinical partners who tested pathogen detection workflows
  • The bioinformatics community for database curation efforts

📄 Citation

Citation information will be provided upon publication. If you use MetaQuest in your research, please check back for citation details or cite this repository.

Version Comparison

v1.2.0 vs v1.1.0

Feature v1.1.0 v1.2.0
Functional Databases Single database COG + SwissProt dual database
Annotation Coverage ~30-50% ~60-80%
Mobile Element Analysis Basic Comprehensive IS family tracking
Gene Prediction Controls Fixed parameters Fully customizable
Logging System Basic Professional dual-mode system
Reports Basic text output Comprehensive multi-perspective reports
tbl2asn Handling Manual intervention required Automatic timeout and recovery
Debug Capabilities Limited Complete diagnostic output

Release Status: Production-ready stable release
Recommended for: All users (clinical and research)
Migration: Seamless upgrade from v1.1.0

MetaQuest v1.2.0 - Transforming metagenomic analysis through enhanced annotation and professional-grade reporting

Assets 2
Loading