@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/epigenomics-methylgpt-agent/SKILL.md

@@ -0,0 +1,111 @@
+<!--
+# COPYRIGHT NOTICE
+# This file is part of the "Universal Biomedical Skills" project.
+# Copyright (c) 2026 MD BABU MIA, PhD <md.babu.mia@mssm.edu>
+# All Rights Reserved.
+#
+# This code is proprietary and confidential.
+# Unauthorized copying of this file, via any medium is strictly prohibited.
+#
+# Provenance: Authenticated by MD BABU MIA
+
+-->
+
+---
+name: 'epigenomics-methylgpt-agent'
+description: 'AI-powered DNA methylation analysis using MethylGPT foundation models for epigenomic profiling, differential methylation detection, and cancer epigenome characterization.'
+measurable_outcome: Execute skill workflow successfully with valid output within 15 minutes.
+allowed-tools:
+  - read_file
+  - run_shell_command
+---
+
+
+# Epigenomics MethylGPT Agent
+
+The **Epigenomics MethylGPT Agent** leverages foundation models for comprehensive DNA methylation analysis. It integrates MethylGPT and DiffuCpG for methylation profiling, differential methylation region (DMR) detection, and cancer epigenome characterization at single-base resolution.
+
+## When to Use This Skill
+
+* When analyzing whole-genome bisulfite sequencing (WGBS) data for methylation patterns.
+* To identify differentially methylated regions (DMRs) between conditions (e.g., tumor vs. normal).
+* For cancer epigenome profiling and epigenetic biomarker discovery.
+* When predicting CpG methylation states using deep learning models.
+* To impute missing methylation data in high-throughput studies.
+
+## Core Capabilities
+
+1. **MethylGPT Foundation Model**: Leverages transformer-based architecture trained on large-scale methylome data for methylation state prediction and pattern recognition.
+
+2. **Differential Methylation Analysis**: Identifies DMRs with increased sensitivity using AI-enhanced detection compared to traditional statistical methods.
+
+3. **Cancer Epigenome Profiling**: Specialized analysis for tumor methylation signatures, including hypermethylation of tumor suppressors and global hypomethylation patterns.
+
+4. **Missing Data Imputation**: Uses DiffuCpG generative AI model to address missing data in methylation arrays and sequencing studies.
+
+5. **Single-Base Resolution**: Deep learning models capture sequence context and long-range dependencies for accurate CpG methylation identification.
+
+6. **Multi-Platform Support**: Analyzes data from Illumina methylation arrays (450K, EPIC), WGBS, RRBS, and targeted bisulfite sequencing.
+
+## Workflow
+
+1. **Input**: Provide methylation data (beta values, WGBS BAM files, or raw intensity data) and sample metadata.
+
+2. **Preprocessing**: Quality control, normalization, and batch effect correction.
+
+3. **Analysis**: Apply MethylGPT for methylation prediction, DMR calling, and pattern discovery.
+
+4. **Interpretation**: Annotate DMRs to genomic features (promoters, enhancers, gene bodies) and pathways.
+
+5. **Output**: DMR reports, methylation heatmaps, pathway enrichment, and epigenetic age estimates.
+
+## Example Usage
+
+**User**: "Identify differentially methylated regions between tumor and normal samples in this WGBS dataset."
+
+**Agent Action**:
+```bash
+python3 Skills/Genomics/Epigenomics_MethylGPT_Agent/methylgpt_analyzer.py \
+    --input tumor_normal_methylation.csv \
+    --groups tumor,normal \
+    --model methylgpt-base \
+    --analysis dmr \
+    --min_cpgs 5 \
+    --delta_beta 0.2 \
+    --output dmr_results.json
+```
+
+## Key Methods and Tools
+
+| Method | Application | Reference |
+|--------|-------------|-----------|
+| MethylGPT | Foundation model for methylome analysis | 2025 Nature Methods |
+| DiffuCpG | Generative AI for missing data imputation | 2025 Bioinformatics |
+| DeepMethyl | WGBS analysis for DMR detection | 2024 Genome Biology |
+| minfi | Illumina array preprocessing | Bioconductor |
+| DSS | Statistical DMR calling | Bioconductor |
+
+## Prerequisites
+
+* Python 3.10+
+* PyTorch 2.0+
+* Transformers library
+* methylgpt-model weights
+* Bioconductor R packages (optional)
+
+## Related Skills
+
+* Single_Cell_Foundation_Models - For single-cell methylation analysis
+* Variant_Interpretation - For methylation-variant associations
+* Multi_Omics_Integration - For combining methylation with expression data
+
+## Methodology
+
+DNA methylation analysis leverages CNNs and transformers to capture sequence context and long-range dependencies. The MethylGPT foundation model is pre-trained on millions of CpG sites across diverse tissues and conditions, enabling transfer learning for specific applications. DiffuCpG uses diffusion-based generative modeling to impute missing methylation values while preserving biological structure.
+
+## Author
+
+AI Group - Biomedical AI Platform
+
+
+<!-- AUTHOR_SIGNATURE: 9a7f3c2e-MD-BABU-MIA-2026-MSSM-SECURE -->

package/data/skills/equity-scorer/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: equity-scorer
+description: Compute HEIM diversity and equity metrics from VCF or ancestry data. Generates heterozygosity, FST, PCA plots, and a composite HEIM Equity Score with markdown reports.
+version: 0.1.0
+metadata:
+  openclaw:
+    requires:
+      bins:
+        - python3
+      env: []
+      config: []
+    always: false
+    emoji: "🦖"
+    homepage: https://github.com/ClawBio/ClawBio
+    os: [macos, linux]
+    install:
+      - kind: uv
+        package: biopython
+        bins: []
+      - kind: uv
+        package: pandas
+        bins: []
+      - kind: uv
+        package: scikit-learn
+        bins: []
+      - kind: uv
+        package: matplotlib
+        bins: []
+      - kind: uv
+        package: numpy
+        bins: []
+---
+
+# 🦖 Equity Scorer
+
+You are the **Equity Scorer**, a specialised bioinformatics agent for computing diversity and health equity metrics from genomic data. You implement the **HEIM (Health Equity Index for Minorities)** framework to quantify how well a dataset, biobank, or study represents global population diversity.
+
+## Core Capabilities
+
+1. **Heterozygosity Analysis**: Compute observed and expected heterozygosity per population.
+2. **FST Calculation**: Pairwise fixation index between population groups.
+3. **PCA Visualisation**: Principal Component Analysis of genotype data, coloured by ancestry/population.
+4. **HEIM Equity Score**: A composite 0-100 score measuring representation equity across populations.
+5. **Ancestry Distribution**: Summarise and visualise the ancestry composition of a dataset.
+6. **Markdown Report**: Full analysis report with tables, figures, methods, and reproducibility block.
+
+## Input Formats
+
+### VCF File
+Standard Variant Call Format (.vcf or .vcf.gz) with:
+- Genotype fields (GT) for multiple samples
+- Optional: population/ancestry annotations in sample metadata
+
+### Ancestry CSV
+Tabular file with columns:
+- `sample_id`: Unique identifier
+- `population` or `ancestry`: Population label (e.g., "EUR", "AFR", "EAS", "AMR", "SAS")
+- Optional: `superpopulation`, `country`, `ethnicity`
+- Optional: genotype columns for variant-level analysis
+
+## HEIM Equity Score Methodology
+
+The HEIM Equity Score (0-100) is a composite metric:
+
+```
+HEIM_Score = w1 * Representation_Index
+           + w2 * Heterozygosity_Balance
+           + w3 * FST_Coverage
+           + w4 * Geographic_Spread
+
+where:
+  Representation_Index = 1 - max_deviation_from_global_proportions
+  Heterozygosity_Balance = mean_het / max_possible_het
+  FST_Coverage = proportion_of_pairwise_FST_computed
+  Geographic_Spread = n_continents_represented / 7
+
+Default weights: w1=0.35, w2=0.25, w3=0.20, w4=0.20
+```
+
+### Score Interpretation
+
+| Score | Rating | Meaning |
+|-------|--------|---------|
+| 80-100 | Excellent | Strong representation across global populations |
+| 60-79 | Good | Reasonable diversity with some gaps |
+| 40-59 | Fair | Notable underrepresentation of some populations |
+| 20-39 | Poor | Significant diversity gaps |
+| 0-19 | Critical | Severely limited population representation |
+
+## Workflow
+
+When the user asks for diversity/equity analysis:
+
+1. **Detect input**: Check if the input is VCF or CSV. Inspect headers and sample count.
+2. **Extract populations**: Parse population labels from metadata or ancestry columns.
+3. **Compute metrics**:
+   - If VCF: parse genotypes, compute per-site and per-population heterozygosity, pairwise FST, run PCA
+   - If CSV: compute representation statistics, ancestry distribution, geographic spread
+4. **Calculate HEIM Score**: Apply the composite formula above.
+5. **Generate visualisations**:
+   - PCA scatter plot (PC1 vs PC2, coloured by population)
+   - Ancestry bar chart (proportion per population)
+   - Heterozygosity comparison (observed vs expected per population)
+   - FST heatmap (pairwise between populations)
+6. **Write report**: Markdown with embedded figure paths, methods, and reproducibility block.
+
+## Example Queries
+
+- "Score the diversity of my VCF file at data/samples.vcf"
+- "What is the HEIM Equity Score for the UK Biobank ancestry data?"
+- "Compare population representation between two cohorts"
+- "Generate a PCA plot coloured by ancestry for these samples"
+- "How underrepresented are African populations in this dataset?"
+
+## Output Structure
+
+```
+equity_report/
+├── report.md                 # Full analysis report
+├── figures/
+│   ├── pca_plot.png         # PCA scatter (PC1 vs PC2)
+│   ├── ancestry_bar.png     # Population proportions
+│   ├── heterozygosity.png   # Observed vs expected Het
+│   └── fst_heatmap.png      # Pairwise FST matrix
+├── tables/
+│   ├── population_summary.csv
+│   ├── heterozygosity.csv
+│   ├── fst_matrix.csv
+│   └── heim_score.json
+└── reproducibility/
+    ├── commands.sh          # Commands to re-run
+    ├── environment.yml      # Conda export
+    └── checksums.sha256     # Input file checksums
+```
+
+## Example Report Output
+
+```markdown
+# HEIM Equity Report: UK Biobank Subset
+
+**Date**: 2026-02-26
+**Samples**: 1,247
+**Populations**: 5 (EUR: 892, SAS: 156, AFR: 98, EAS: 67, AMR: 34)
+
+## HEIM Equity Score: 42/100 (Fair)
+
+### Breakdown
+- Representation Index: 0.31 (EUR overrepresented at 71.5%)
+- Heterozygosity Balance: 0.68 (AFR populations show highest diversity)
+- FST Coverage: 1.00 (all pairwise computed)
+- Geographic Spread: 0.71 (5/7 continental groups)
+
+### Key Finding
+African and American populations are underrepresented by 3.2x and 5.8x
+respectively relative to global proportions. This limits the generalisability
+of GWAS findings from this cohort to non-European populations.
+
+### Recommendations
+1. Prioritise recruitment from AMR and AFR communities
+2. Apply ancestry-aware statistical methods for any association analyses
+3. Report HEIM score alongside study demographics in publications
+```
+
+## Dependencies
+
+**Required (Python packages)**:
+- `biopython` >= 1.82 (VCF parsing via `Bio.SeqIO`, population genetics)
+- `pandas` >= 2.0 (data wrangling)
+- `numpy` >= 1.24 (numerical computation)
+- `scikit-learn` >= 1.3 (PCA)
+- `matplotlib` >= 3.7 (visualisation)
+
+**Optional**:
+- `cyvcf2` (faster VCF parsing for large files)
+- `seaborn` (enhanced visualisations)
+- `pysam` (BAM/VCF indexing)
+
+## Safety
+
+- **No data upload**: All computation local. No external API calls for genomic data.
+- **Large file warning**: If VCF > 1GB, warn the user and suggest subsetting or using `cyvcf2`.
+- **Ancestry sensitivity**: Population labels are analytical categories, not identities. Include this disclaimer in reports.

package/data/skills/esm/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: esm
+description: Comprehensive toolkit for protein language models including ESM3 (generative multimodal protein design across sequence, structure, and function) and ESM C (efficient protein embeddings and representations). Use this skill when working with protein sequences, structures, or function prediction; designing novel proteins; generating protein embeddings; performing inverse folding; or conducting protein engineering tasks. Supports both local model usage and cloud-based Forge API for scalable inference.
+---
+
+# ESM: Evolutionary Scale Modeling
+
+## Overview
+
+ESM provides state-of-the-art protein language models for understanding, generating, and designing proteins. This skill enables working with two model families: ESM3 for generative protein design across sequence, structure, and function, and ESM C for efficient protein representation learning and embeddings.
+
+## Core Capabilities
+
+### 1. Protein Sequence Generation with ESM3
+
+Generate novel protein sequences with desired properties using multimodal generative modeling.
+
+**When to use:**
+- Designing proteins with specific functional properties
+- Completing partial protein sequences
+- Generating variants of existing proteins
+- Creating proteins with desired structural characteristics
+
+**Basic usage:**
+
+```python
+from esm.models.esm3 import ESM3
+from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig
+
+# Load model locally
+model: ESM3InferenceClient = ESM3.from_pretrained("esm3-sm-open-v1").to("cuda")
+
+# Create protein prompt
+protein = ESMProtein(sequence="MPRT___KEND")  # '_' represents masked positions
+
+# Generate completion
+protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8))
+print(protein.sequence)
+```
+
+**For remote/cloud usage via Forge API:**
+
+```python
+from esm.sdk.forge import ESM3ForgeInferenceClient
+from esm.sdk.api import ESMProtein, GenerationConfig
+
+# Connect to Forge
+model = ESM3ForgeInferenceClient(model="esm3-medium-2024-08", url="https://forge.evolutionaryscale.ai", token="<token>")
+
+# Generate
+protein = model.generate(protein, GenerationConfig(track="sequence", num_steps=8))
+```
+
+See `references/esm3-api.md` for detailed ESM3 model specifications, advanced generation configurations, and multimodal prompting examples.
+
+### 2. Structure Prediction and Inverse Folding
+
+Use ESM3's structure track for structure prediction from sequence or inverse folding (sequence design from structure).
+
+**Structure prediction:**
+
+```python
+from esm.sdk.api import ESM3InferenceClient, ESMProtein, GenerationConfig
+
+# Predict structure from sequence
+protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP...")
+protein_with_structure = model.generate(
+    protein,
+    GenerationConfig(track="structure", num_steps=protein.sequence.count("_"))
+)
+
+# Access predicted structure
+coordinates = protein_with_structure.coordinates  # 3D coordinates
+pdb_string = protein_with_structure.to_pdb()
+```
+
+**Inverse folding (sequence from structure):**
+
+```python
+# Design sequence for a target structure
+protein_with_structure = ESMProtein.from_pdb("target_structure.pdb")
+protein_with_structure.sequence = None  # Remove sequence
+
+# Generate sequence that folds to this structure
+designed_protein = model.generate(
+    protein_with_structure,
+    GenerationConfig(track="sequence", num_steps=50, temperature=0.7)
+)
+```
+
+### 3. Protein Embeddings with ESM C
+
+Generate high-quality embeddings for downstream tasks like function prediction, classification, or similarity analysis.
+
+**When to use:**
+- Extracting protein representations for machine learning
+- Computing sequence similarities
+- Feature extraction for protein classification
+- Transfer learning for protein-related tasks
+
+**Basic usage:**
+
+```python
+from esm.models.esmc import ESMC
+from esm.sdk.api import ESMProtein
+
+# Load ESM C model
+model = ESMC.from_pretrained("esmc-300m").to("cuda")
+
+# Get embeddings
+protein = ESMProtein(sequence="MPRTKEINDAGLIVHSP...")
+protein_tensor = model.encode(protein)
+
+# Generate embeddings
+embeddings = model.forward(protein_tensor)
+```
+
+**Batch processing:**
+
+```python
+# Encode multiple proteins
+proteins = [
+    ESMProtein(sequence="MPRTKEIND..."),
+    ESMProtein(sequence="AGLIVHSPQ..."),
+    ESMProtein(sequence="KTEFLNDGR...")
+]
+
+embeddings_list = [model.logits(model.forward(model.encode(p))) for p in proteins]
+```
+
+See `references/esm-c-api.md` for ESM C model details, efficiency comparisons, and advanced embedding strategies.
+
+### 4. Function Conditioning and Annotation
+
+Use ESM3's function track to generate proteins with specific functional annotations or predict function from sequence.
+
+**Function-conditioned generation:**
+
+```python
+from esm.sdk.api import ESMProtein, FunctionAnnotation, GenerationConfig
+
+# Create protein with desired function
+protein = ESMProtein(
+    sequence="_" * 200,  # Generate 200 residue protein
+    function_annotations=[
+        FunctionAnnotation(label="fluorescent_protein", start=50, end=150)
+    ]
+)
+
+# Generate sequence with specified function
+functional_protein = model.generate(
+    protein,
+    GenerationConfig(track="sequence", num_steps=200)
+)
+```
+
+### 5. Chain-of-Thought Generation
+
+Iteratively refine protein designs using ESM3's chain-of-thought generation approach.
+
+```python
+from esm.sdk.api import GenerationConfig
+
+# Multi-step refinement
+protein = ESMProtein(sequence="MPRT" + "_" * 100 + "KEND")
+
+# Step 1: Generate initial structure
+config = GenerationConfig(track="structure", num_steps=50)
+protein = model.generate(protein, config)
+
+# Step 2: Refine sequence based on structure
+config = GenerationConfig(track="sequence", num_steps=50, temperature=0.5)
+protein = model.generate(protein, config)
+
+# Step 3: Predict function
+config = GenerationConfig(track="function", num_steps=20)
+protein = model.generate(protein, config)
+```
+
+### 6. Batch Processing with Forge API
+
+Process multiple proteins efficiently using Forge's async executor.
+
+```python
+from esm.sdk.forge import ESM3ForgeInferenceClient
+import asyncio
+
+client = ESM3ForgeInferenceClient(model="esm3-medium-2024-08", token="<token>")
+
+# Async batch processing
+async def batch_generate(proteins_list):
+    tasks = [
+        client.async_generate(protein, GenerationConfig(track="sequence"))
+        for protein in proteins_list
+    ]
+    return await asyncio.gather(*tasks)
+
+# Execute
+proteins = [ESMProtein(sequence=f"MPRT{'_' * 50}KEND") for _ in range(10)]
+results = asyncio.run(batch_generate(proteins))
+```
+
+See `references/forge-api.md` for detailed Forge API documentation, authentication, rate limits, and batch processing patterns.
+
+## Model Selection Guide
+
+**ESM3 Models (Generative):**
+- `esm3-sm-open-v1` (1.4B) - Open weights, local usage, good for experimentation
+- `esm3-medium-2024-08` (7B) - Best balance of quality and speed (Forge only)
+- `esm3-large-2024-03` (98B) - Highest quality, slower (Forge only)
+
+**ESM C Models (Embeddings):**
+- `esmc-300m` (30 layers) - Lightweight, fast inference
+- `esmc-600m` (36 layers) - Balanced performance
+- `esmc-6b` (80 layers) - Maximum representation quality
+
+**Selection criteria:**
+- **Local development/testing:** Use `esm3-sm-open-v1` or `esmc-300m`
+- **Production quality:** Use `esm3-medium-2024-08` via Forge
+- **Maximum accuracy:** Use `esm3-large-2024-03` or `esmc-6b`
+- **High throughput:** Use Forge API with batch executor
+- **Cost optimization:** Use smaller models, implement caching strategies
+
+## Installation
+
+**Basic installation:**
+
+```bash
+uv pip install esm
+```
+
+**With Flash Attention (recommended for faster inference):**
+
+```bash
+uv pip install esm
+uv pip install flash-attn --no-build-isolation
+```
+
+**For Forge API access:**
+
+```bash
+uv pip install esm  # SDK includes Forge client
+```
+
+No additional dependencies needed. Obtain Forge API token at https://forge.evolutionaryscale.ai
+
+## Common Workflows
+
+For detailed examples and complete workflows, see `references/workflows.md` which includes:
+- Novel GFP design with chain-of-thought
+- Protein variant generation and screening
+- Structure-based sequence optimization
+- Function prediction pipelines
+- Embedding-based clustering and analysis
+
+## References
+
+This skill includes comprehensive reference documentation:
+
+- `references/esm3-api.md` - ESM3 model architecture, API reference, generation parameters, and multimodal prompting
+- `references/esm-c-api.md` - ESM C model details, embedding strategies, and performance optimization
+- `references/forge-api.md` - Forge platform documentation, authentication, batch processing, and deployment
+- `references/workflows.md` - Complete examples and common workflow patterns
+
+These references contain detailed API specifications, parameter descriptions, and advanced usage patterns. Load them as needed for specific tasks.
+
+## Best Practices
+
+**For generation tasks:**
+- Start with smaller models for prototyping (`esm3-sm-open-v1`)
+- Use temperature parameter to control diversity (0.0 = deterministic, 1.0 = diverse)
+- Implement iterative refinement with chain-of-thought for complex designs
+- Validate generated sequences with structure prediction or wet-lab experiments
+
+**For embedding tasks:**
+- Batch process sequences when possible for efficiency
+- Cache embeddings for repeated analyses
+- Normalize embeddings when computing similarities
+- Use appropriate model size based on downstream task requirements
+
+**For production deployment:**
+- Use Forge API for scalability and latest models
+- Implement error handling and retry logic for API calls
+- Monitor token usage and implement rate limiting
+- Consider AWS SageMaker deployment for dedicated infrastructure
+
+## Resources and Documentation
+
+- **GitHub Repository:** https://github.com/evolutionaryscale/esm
+- **Forge Platform:** https://forge.evolutionaryscale.ai
+- **Scientific Paper:** Hayes et al., Science (2025) - https://www.science.org/doi/10.1126/science.ads0018
+- **Blog Posts:**
+  - ESM3 Release: https://www.evolutionaryscale.ai/blog/esm3-release
+  - ESM C Launch: https://www.evolutionaryscale.ai/blog/esm-cambrian
+- **Community:** Slack community at https://bit.ly/3FKwcWd
+- **Model Weights:** HuggingFace EvolutionaryScale organization
+
+## Responsible Use
+
+ESM is designed for beneficial applications in protein engineering, drug discovery, and scientific research. Follow the Responsible Biodesign Framework (https://responsiblebiodesign.ai/) when designing novel proteins. Consider biosafety and ethical implications of protein designs before experimental validation.