Tooluniverse Multi Omics Integration

Multi-Omics Integration

Coordinate and integrate multiple omics datasets for comprehensive systems biology analysis. Orchestrates specialized ToolUniverse skills to perform cross-omics correlation, multi-omics clustering, pathway-level integration, and unified interpretation.

---

Domain Reasoning

Multi-omics integration asks whether different molecular layers tell a concordant story. If a gene is upregulated in RNA-seq AND its protein is elevated in proteomics, that is concordant evidence of true biological change. Discordance — high mRNA but low protein, or elevated protein without matching mRNA — may indicate post-transcriptional regulation (miRNA silencing, protein degradation, translational control) and is itself a meaningful finding worth reporting. Not every discordance is noise; some are the most interesting biology.

LOOK UP DON'T GUESS

• Expected RNA-protein correlation ranges: compute Spearman r from the actual data; the typical range (0.4-0.6) is a guide, not a guarantee.
• Pathway enrichment results: run ReactomeAnalysis_pathway_enrichment or gseapy on the actual gene lists; never list enriched pathways from memory.
• eQTL associations: query GTEx or eQTL databases for the specific variant and tissue; do not assume regulatory relationships.
• Methylation-expression directionality at specific loci: retrieve experimental data; promoter repression is the canonical model but exceptions exist.

---

When to Use This Skill

• User has multiple omics datasets (RNA-seq + proteomics, methylation + expression, etc.)
• Cross-omics correlation queries (e.g., "How does methylation affect expression?")
• Multi-omics biomarker discovery or patient subtyping
• Systems biology questions requiring multiple molecular layers
• Precision medicine applications with multi-omics patient data

---

Workflow Overview

Phase 1: Data Loading & QC
  Load each omics type, format-specific QC, normalize
  Supported: RNA-seq, proteomics, methylation, CNV/SNV, metabolomics

Phase 2: Sample Matching
  Harmonize sample IDs, find common samples, handle missing omics

Phase 3: Feature Mapping
  Map features to common gene-level identifiers
  CpG->gene (promoter), CNV->gene, metabolite->enzyme

Phase 4: Cross-Omics Correlation
  RNA vs Protein (translation efficiency)
  Methylation vs Expression (epigenetic regulation)
  CNV vs Expression (dosage effect)
  eQTL variants vs Expression (genetic regulation)

Phase 5: Multi-Omics Clustering
  MOFA+, NMF, SNF for patient subtyping

Phase 6: Pathway-Level Integration
  Aggregate omics evidence at pathway level
  Score pathway dysregulation with combined evidence

Phase 7: Biomarker Discovery
  Feature selection across omics, multi-omics classification

Phase 8: Integrated Report
  Summary, correlations, clusters, pathways, biomarkers

See: phase_details.md for complete code and implementation details.

---

Supported Data Types

---

Core Operations

Sample Matching

def match_samples_across_omics(omics_data_dict):
    """Match samples across multiple omics datasets."""
    sample_ids = {k: set(df.columns) for k, df in omics_data_dict.items()}
    common_samples = set.intersection(*sample_ids.values())
    matched_data = {k: df[sorted(common_samples)] for k, df in omics_data_dict.items()}
    return sorted(common_samples), matched_data

Cross-Omics Correlation

from scipy.stats import spearmanr, pearsonr

# RNA vs Protein: expect positive r ~ 0.4-0.6
# Methylation vs Expression: expect negative r (promoter repression)
# CNV vs Expression: expect positive r (dosage effect)

for gene in common_genes:
    r, p = spearmanr(rna[gene], protein[gene])

Pathway Integration

# Score pathway dysregulation using combined evidence from all omics
# Aggregate per-gene evidence, then per-pathway
pathway_score = mean(abs(rna_fc) + abs(protein_fc) + abs(meth_diff) + abs(cnv))

See: phase_details.md for full implementations of each operation.

---

Multi-Omics Clustering Methods

---

ToolUniverse Skills Coordination

---

Use Cases

Cancer Multi-Omics

Integrate TCGA RNA-seq + proteomics + methylation + CNV to identify patient subtypes, cross-omics driver genes, and multi-omics biomarkers.

eQTL + Expression + Methylation

Identify SNP -> methylation -> expression regulatory chains (mediation analysis).

Drug Response Multi-Omics

Predict drug response using baseline multi-omics profiles; identify resistance/sensitivity pathways.

See: phase_details.md "Use Cases" for detailed step-by-step workflows.

---

Quantified Minimums

---

Limitations

• Sample size: n >= 20 recommended for integration
• Missing data: Pairwise integration if not all samples have all omics
• Batch effects: Different platforms require careful normalization
• Computational: Large datasets may require significant memory
• Interpretation: Results require domain expertise for validation

---

References

• MOFA+: https://doi.org/10.1186/s13059-020-02015-1
• Similarity Network Fusion: https://doi.org/10.1038/nmeth.2810
• Multi-omics review: https://doi.org/10.1038/s41576-019-0093-7
• See individual ToolUniverse skill documentation for omics-specific methods

---

Detailed Reference

• phase_details.md - Complete code for all phases, correlation functions, clustering, pathway integration, biomarker discovery, report template, and detailed use cases

Multi-Omics Integration: Phase Details

Complete implementation details for each phase of the multi-omics integration workflow.

---

Phase 1: Data Loading & QC

Supported formats:

• Expression: CSV/TSV matrices, HDF5, AnnData (.h5ad)
• Proteomics: MaxQuant output, Spectronaut, DIA-NN
• Methylation: IDAT files, beta value matrices
• Variants: VCF, SEG files (CNV)
• Metabolomics: Peak tables, identified metabolites

QC per omics:

# RNA-seq: Filter low-count genes, normalize (TPM/DESeq2), log-transform
# Proteomics: Filter high-missing proteins, impute (KNN/minimum), median-normalize
# Methylation: Remove failed probes, ComBat batch correction, filter cross-reactive
# Variants: Use variant-analysis skill for VCF QC, CNV segmentation validation

---

Phase 2: Sample Matching

def match_samples_across_omics(omics_data_dict):
    """
    Match samples across multiple omics datasets.

    Parameters:
    omics_data_dict: {
        'rnaseq': DataFrame (genes x samples),
        'proteomics': DataFrame (proteins x samples),
        'methylation': DataFrame (CpGs x samples),
        'cnv': DataFrame (genes x samples)
    }
    """
    sample_ids = {
        omics_type: set(df.columns)
        for omics_type, df in omics_data_dict.items()
    }
    common_samples = set.intersection(*sample_ids.values())
    matched_data = {
        omics_type: df[sorted(common_samples)]
        for omics_type, df in omics_data_dict.items()
    }
    return sorted(common_samples), matched_data

Handling missing omics: Use pairwise integration if not all samples have all omics types.

---

Phase 3: Feature Mapping

Map all features to gene-level identifiers:

• RNA-seq: Already gene-level
• Proteomics: Map protein to gene
• Methylation: Map CpG to gene (promoter TSS +/- 2kb, gene body)
• CNV: Map CNV regions to overlapping genes
• Metabolomics: Map metabolite to enzyme gene

---

Phase 4: Cross-Omics Correlation

4.1: RNA vs Protein (Translation Efficiency)

def correlate_rna_protein(rnaseq_data, proteomics_data):
    """Expected: Positive correlation (r ~ 0.4-0.6 typical)"""
    common_genes = set(rnaseq_data.index) & set(proteomics_data.index)
    correlations = {}
    for gene in common_genes:
        r, p = spearmanr(rnaseq_data.loc[gene], proteomics_data.loc[gene])
        correlations[gene] = {'r': r, 'p': p}
    discordant = {g: v for g, v in correlations.items() if abs(v['r']) < 0.2}
    return correlations, discordant

4.2: Methylation vs Expression

def correlate_methylation_expression(methylation_data, rnaseq_data):
    """Expected: Negative correlation (increased methylation -> decreased expression)"""
    results = {}
    for gene in methylation_data.index:
        if gene in rnaseq_data.index:
            r, p = spearmanr(methylation_data.loc[gene], rnaseq_data.loc[gene])
            results[gene] = {'r': r, 'p': p, 'direction': 'repressive' if r < 0 else 'activating'}
    regulated = {g: v for g, v in results.items() if v['r'] < -0.5 and v['p'] < 0.01}
    return results, regulated

4.3: CNV vs Expression (Dosage Effect)

def correlate_cnv_expression(cnv_data, rnaseq_data):
    """Expected: Positive correlation (gene dosage effect)"""
    results = {}
    for gene in cnv_data.index:
        if gene in rnaseq_data.index:
            r, p = pearsonr(cnv_data.loc[gene], rnaseq_data.loc[gene])
            results[gene] = {'r': r, 'p': p}
    dosage_genes = {g: v for g, v in results.items() if v['r'] > 0.5 and v['p'] < 0.01}
    return results, dosage_genes

---

Phase 5: Multi-Omics Clustering

MOFA+ (Multi-Omics Factor Analysis)

# Conceptual workflow (uses R's MOFA2 or Python implementation)
# 1. Prepare multi-omics data as list of matrices
# 2. Run MOFA+ to identify factors
# 3. Inspect factor variance explained per omics
# 4. Cluster samples based on factor scores
#
# Example interpretation:
# Factor 1: 40% RNA-seq variance, 30% proteomics -> Cell proliferation
# Factor 2: 50% methylation variance -> Epigenetic subtype
# Factor 3: 20% CNV variance -> Genomic instability

Joint NMF

def joint_nmf_clustering(omics_data_dict, n_clusters=3):
    """Joint NMF across omics for clustering."""
    combined_matrix = np.vstack([
        omics_data_dict['rnaseq'].values,
        omics_data_dict['proteomics'].values,
        omics_data_dict['methylation'].values
    ])
    from sklearn.decomposition import NMF
    model = NMF(n_components=n_clusters, init='nndsvd', random_state=42)
    W = model.fit_transform(combined_matrix)
    H = model.components_
    from sklearn.cluster import KMeans
    clusters = KMeans(n_clusters=n_clusters).fit_predict(H.T)
    return clusters, W, H

---

Phase 6: Pathway-Level Integration

def integrate_pathway_evidence(omics_results, pathway_genes):
    """Score pathway dysregulation across omics."""
    pathway_scores = []
    for gene in pathway_genes:
        gene_score = 0
        evidence_count = 0
        for omics_type in ['rnaseq', 'proteomics', 'methylation', 'cnv']:
            if gene in omics_results[omics_type]:
                gene_score += abs(omics_results[omics_type][gene])
                evidence_count += 1
        if evidence_count > 0:
            pathway_scores.append(gene_score / evidence_count)
    return {
        'pathway_score': np.mean(pathway_scores) if pathway_scores else 0,
        'n_genes_with_evidence': len(pathway_scores),
    }

ToolUniverse enrichment:

tu = ToolUniverse()
all_dysregulated = set(rnaseq_degs) | set(diff_proteins) | set(methylation_dmgs)
enrichment = tu.run_one_function({
    "name": "Enrichr_enrich",
    "arguments": {"gene_list": ",".join(all_dysregulated), "library": "KEGG_2021_Human"}
})

---

Phase 7: Biomarker Discovery

def select_multiomics_features(X_dict, y, n_features=50):
    """Select top features across omics for classification."""
    from sklearn.feature_selection import SelectKBest, f_classif
    selected_features = {}
    for omics_type, X in X_dict.items():
        selector = SelectKBest(f_classif, k=min(n_features, X.shape[1]))
        selector.fit(X, y)
        selected_features[omics_type] = X.columns[selector.get_support()].tolist()
    return selected_features

def multiomics_classification(X_dict, y, selected_features):
    """Train classifier using multi-omics features."""
    from sklearn.ensemble import RandomForestClassifier
    from sklearn.model_selection import cross_val_score
    X_combined = pd.concat([X_dict[k][v] for k, v in selected_features.items()], axis=1)
    clf = RandomForestClassifier(n_estimators=100, random_state=42)
    scores = cross_val_score(clf, X_combined, y, cv=5, scoring='roc_auc')
    return {'mean_auc': scores.mean(), 'std_auc': scores.std(), 'n_features': X_combined.shape[1]}

---

Phase 8: Report Template

# Multi-Omics Integration Report

## Dataset Summary
- **Omics Types**: RNA-seq, Proteomics, Methylation, CNV
- **Common Samples**: N patients (disease/control split)
- **Features**: genes, proteins, CpGs, CNV regions

## Cross-Omics Correlation
### RNA-Protein: Overall r, highly correlated count, discordant genes
### Methylation-Expression: Anticorrelation, epigenetically regulated genes
### CNV-Expression: Dosage effect genes

## Multi-Omics Clustering (MOFA+/NMF)
### Factors and variance explained
### Patient subtypes with molecular profiles

## Pathway Integration
### Top dysregulated pathways with multi-omics scores

## Multi-Omics Biomarkers
### Classification performance (AUC, features per omics)
### Top biomarker features

## Biological Interpretation
### Summary of findings across molecular layers

---

Use Cases (Detailed)

Cancer Multi-Omics

1. Load 4 omics types for N patients 2. Match samples (find common across all omics) 3. Correlate RNA-protein (translation-regulated genes) 4. Correlate methylation-expression (epigenetically silenced genes) 5. Correlate CNV-expression (dosage-sensitive genes) 6. Run MOFA+ for latent factors 7. Identify subtypes with distinct multi-omics profiles 8. Pathway enrichment per subtype 9. Select multi-omics biomarkers

eQTL + Expression + Methylation

1. Load genotype, expression, methylation data 2. For each GWAS SNP: test eQTL, test meQTL, test CpG-gene correlation 3. Identify SNP -> methylation -> expression regulatory chains

Drug Response Multi-Omics

1. Load baseline multi-omics (pre-treatment) + drug response 2. Correlate each omics with response 3. Select predictive multi-omics features 4. Train classifier, identify resistance/sensitivity pathways

---

Advanced Analysis Patterns

• Omics-Driven Patient Stratification: Precision medicine applications
• Multi-Omics Network Analysis: Integrated PPI + co-expression + regulatory networks
• Temporal Multi-Omics: Longitudinal data / treatment response
• Spatial Multi-Omics: Spatial transcriptomics + proteomics