QBioCode

A comprehensive suite of computational resources for quantum machine learning applications in healthcare and life sciences.

QBioCode provides tools for benchmarking quantum and classical machine learning models, analyzing data complexity, and making informed model selection decisions for healthcare and life science applications.

🌟 Key Features

• QProfiler: Automated ML benchmarking with data complexity analysis
• QSage: Meta-learning tool for intelligent model selection
• Data Generation: Create artificial datasets with controlled complexity
• Quantum ML Support: QSVC, PQK, VQC, QNN implementations
• Classical ML Baselines: RF, SVM, LR, DT, NB, MLP, XGBoost
• Comprehensive Documentation: Detailed tutorials and API reference

📋 Requirements

QBioCode requires Python 3.10 or higher and has been tested with Python versions 3.10, 3.11, and 3.12.

Note: Python 3.10+ is required for compatibility with the latest Qiskit ecosystem (qiskit-ibm-runtime 0.44.0+).

🚀 Quick Start

Installation

Install from PyPI (Recommended)

# Install the latest stable version
pip install qbiocode

# Install with apps support (QProfiler, QSage)
pip install qbiocode[apps]

# Install with all optional dependencies
pip install qbiocode[all]

Install with Conda

QBioCode will be available on conda-forge and bioconda after the initial release review process.

# Once available on conda-forge (recommended)
conda install -c conda-forge qbiocode

# Or from bioconda (includes bioinformatics dependencies)
conda install -c bioconda -c conda-forge qbiocode

# Create a new environment with qbiocode
conda create -n qbiocode -c conda-forge qbiocode
conda activate qbiocode

Current Status: Conda packages are pending submission to conda-forge and bioconda. In the meantime, use pip within a conda environment:

conda create -n qbiocode python=3.10
conda activate qbiocode
pip install qbiocode

Install from Source

# Clone the repository
git clone https://github.com/IBM/QBioCode.git
cd QBioCode

# Create virtual environment
python -m venv .env
source .env/bin/activate  # On Windows: .env\Scripts\activate

# Install QBioCode in editable mode
pip install -e .

# Install with apps support (QProfiler, QSage)
pip install -e ".[apps]"

macOS Users: XGBoost requires OpenMP. Install it using Homebrew:

brew install libomp
pip install --force-reinstall xgboost

For detailed installation instructions, see the Installation Guide.

Running Tests

# Install the package with development dependencies
pip install -e ".[dev]"

# Run the test suite
python -m pytest

The current test suite focuses on utility modules and data-generation helpers that do not require a full runtime setup for all optional quantum workflows.

Basic Usage

import qbiocode as qbc

# Generate artificial data
qbc.generate_data(
    type_of_data='moons',
    save_path='data/moons',
    n_samples=[100, 200],
    noise=[0.1, 0.2],
    random_state=42
)

# Run QProfiler
from apps.qprofiler import qprofiler
import yaml

config = yaml.safe_load(open('configs/config.yaml'))
qprofiler.main(config)

📚 Applications

QProfiler

Automated ML Benchmarking with Data Complexity Analysis

QProfiler provides a comprehensive benchmarking pipeline that:

• Evaluates both classical and quantum ML models
• Computes 15+ data complexity metrics
• Correlates model performance with data characteristics
• Generates detailed performance reports and visualizations

Usage:

# Command line
qprofiler --config configs/config.yaml

# Python API
from apps.qprofiler import qprofiler
qprofiler.main(config)

📖 QProfiler Documentation | 📓 Tutorial

QSage

Intelligent Model Selection via Meta-Learning

QSage uses surrogate models trained on extensive benchmarking data to:

• Predict model performance without running experiments
• Recommend best models based on dataset characteristics
• Save computational resources
• Provide interpretable predictions

Usage:

# Command line
qsage --data your_data.csv --output predictions.csv

# Python API
from apps.sage.sage import QuantumSage
sage = QuantumSage(data=benchmark_df, features=features, metrics=metrics)
predictions = sage.predict(new_dataset_features)

📖 QSage Documentation | 📓 Tutorial

📖 Tutorials

Comprehensive Jupyter notebook tutorials are available:

1. Artificial Data Generation

Learn how to create synthetic datasets with controlled properties:

• 2D manifolds (circles, moons, spirals)
• 3D manifolds (swiss_roll, s_curve, spheres)
• High-dimensional classification data
• Customizable complexity parameters

2. QProfiler Tutorial

Step-by-step guide to benchmarking ML models:

• Data generation and preparation
• Configuration setup
• Running QProfiler
• Analyzing results and visualizations
• Understanding data complexity metrics

3. QSage Tutorial

Learn to use meta-learning for model selection:

• Loading pre-trained QSage models
• Making predictions on new datasets
• Analyzing prediction accuracy
• Understanding feature importance

4. Quantum Projection Learning

Advanced quantum ML techniques with classical baselines.

🔧 Core Modules

Data Generation

import qbiocode as qbc

# Generate various dataset types
qbc.generate_data(type_of_data='circles', ...)
qbc.generate_data(type_of_data='moons', ...)
qbc.generate_data(type_of_data='classes', ...)

Machine Learning Models

Classical Models:

• Random Forest (RF)
• Support Vector Machine (SVM)
• Logistic Regression (LR)
• Decision Tree (DT)
• Naive Bayes (NB)
• Multi-Layer Perceptron (MLP)
• XGBoost

Quantum Models:

• Quantum Support Vector Classifier (QSVC)
• Projected Quantum Kernel (PQK)
• Variational Quantum Classifier (VQC)
• Quantum Neural Network (QNN)

Embeddings

• PCA, LLE, Isomap, Spectral Embedding
• UMAP, NMF
• Autoencoder

Evaluation

• Model performance metrics (accuracy, F1, AUC)
• Data complexity analysis
• Correlation studies

🛠️ Utilities

QML Config Generation

Generate configuration files for quantum model hyperparameter tuning:

from qbiocode.utils import generate_qml_experiment_configs

num_configs, used_files = generate_qml_experiment_configs(
    template_config_path='configs/config.yaml',
    output_dir='configs/qml_gridsearch',
    data_dirs=['data/my_datasets'],
    qmethods=['qnn', 'vqc', 'qsvc'],
    reps=[1, 2],
    n_components=[5, 10],
    embeddings=['none', 'pca', 'isomap']
)

📊 Documentation

Full documentation is available at: https://ibm.github.io/QBioCode/

• Installation Guide
• API Reference
• Tutorials
• Background

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

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

📝 Citation

If you use QBioCode in your research, please cite:

@software{qbiocode2024,
  title = {QBioCode: Quantum Machine Learning for Healthcare and Life Sciences},
  author = {Raubenolt, Bryan and Bose, Aritra and Rhrissorrakrai, Kahn and 
            Utro, Filippo and Mohan, Akhil and Blankenberg, Daniel and Parida, Laxmi},
  year = {2024},
  url = {https://github.com/IBM/QBioCode}
}

See CITATION.cff for more details.

👥 Authors

Core Contributors:

• Bryan Raubenolt (raubenb@ccf.org) - Cleveland Clinic
• Aritra Bose (a.bose@ibm.com) - IBM Research
• Kahn Rhrissorrakrai (krhriss@us.ibm.com) - IBM Research
• Filippo Utro (futro@us.ibm.com) - IBM Research
• Akhil Mohan (mohana2@ccf.org) - Cleveland Clinic
• Daniel Blankenberg (blanked2@ccf.org) - Cleveland Clinic
• Laxmi Parida (parida@us.ibm.com) - IBM Research

📞 Support

For questions, issues, or feature requests:

• Open an issue on GitHub
• Check the documentation
• Contact the authors

---

QBioCode - Advancing quantum machine learning for healthcare and life sciences 🧬⚛️