@bgicli/bgicli 2.1.0 → 2.2.0

package/data/skills/bio-immunoinformatics-tcr-epitope-binding/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: bio-immunoinformatics-tcr-epitope-binding
+description: Predict TCR-epitope specificity using ERGO-II and deep learning models for T-cell receptor antigen recognition. Match TCRs to their cognate epitopes or predict TCR targets. Use when analyzing TCR repertoire specificity or identifying antigen-reactive T-cells.
+tool_type: python
+primary_tool: ERGO-II
+---
+
+## Version Compatibility
+
+Reference examples tested with: MiXCR 4.6+, numpy 1.26+, pandas 2.2+, scikit-learn 1.4+, scipy 1.12+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# TCR-Epitope Binding
+
+**"Predict which epitopes my TCRs recognize"** → Match T-cell receptors to their cognate epitopes using deep learning models for TCR antigen specificity prediction.
+- Python: ERGO-II model for TCR-epitope binding prediction
+
+## ERGO-II Model
+
+```python
+# ERGO-II uses deep learning to predict TCR-epitope binding
+# GitHub: https://github.com/IdoSpringer/ERGO-II
+
+def setup_ergo():
+    '''Setup ERGO-II for TCR-epitope prediction
+
+    Requirements:
+    - PyTorch
+    - Pre-trained models from ERGO-II repository
+
+    ERGO-II features:
+    - Uses both CDR3 alpha and beta chains
+    - Incorporates MHC context
+    - Trained on VDJdb and IEDB data
+    '''
+    print('ERGO-II setup:')
+    print('1. Clone: git clone https://github.com/IdoSpringer/ERGO-II')
+    print('2. Install: pip install torch pandas scikit-learn')
+    print('3. Download models from repository')
+```
+
+## TCR Input Format
+
+```python
+def parse_tcr_data(tcr_file):
+    '''Parse TCR sequence data
+
+    Required columns:
+    - cdr3_beta: CDR3 beta chain sequence (most informative)
+    - cdr3_alpha: CDR3 alpha chain (optional, improves accuracy)
+    - v_beta: V gene usage (optional)
+    - j_beta: J gene usage (optional)
+
+    CDR3 is the primary determinant of antigen specificity.
+    Alpha chain provides ~20% additional specificity.
+    '''
+    import pandas as pd
+
+    df = pd.read_csv(tcr_file, sep='\t')
+
+    # Validate CDR3 sequences
+    valid_aa = set('ACDEFGHIKLMNPQRSTVWY')
+
+    def is_valid_cdr3(seq):
+        if pd.isna(seq):
+            return False
+        return all(aa in valid_aa for aa in seq.upper())
+
+    df['valid_beta'] = df['cdr3_beta'].apply(is_valid_cdr3)
+
+    return df[df['valid_beta']]
+```
+
+## Predict TCR-Epitope Binding
+
+```python
+def predict_binding_simple(cdr3_beta, epitope):
+    '''Simple TCR-epitope compatibility score
+
+    This is a simplified heuristic. For accurate predictions,
+    use ERGO-II or other deep learning models.
+
+    Features considered:
+    - CDR3 length compatibility
+    - Amino acid composition
+    - Hydrophobicity matching
+    '''
+    # Length compatibility
+    # TCRs recognizing similar epitopes often have similar CDR3 lengths
+    optimal_length = len(epitope) + 5  # Rough heuristic
+    length_score = 1 - abs(len(cdr3_beta) - optimal_length) / 10
+
+    # Charge complementarity
+    positive = set('RKH')
+    negative = set('DE')
+
+    tcr_charge = sum(1 if aa in positive else -1 if aa in negative else 0
+                    for aa in cdr3_beta)
+    epitope_charge = sum(1 if aa in positive else -1 if aa in negative else 0
+                        for aa in epitope)
+
+    # Opposite charges suggest complementarity
+    charge_score = 0.5 + (tcr_charge * -epitope_charge) / 20
+
+    return {
+        'cdr3_beta': cdr3_beta,
+        'epitope': epitope,
+        'length_score': max(0, min(1, length_score)),
+        'charge_score': max(0, min(1, charge_score)),
+        'combined': (length_score + charge_score) / 2
+    }
+```
+
+## Match TCRs to Known Epitopes
+
+```python
+def match_to_vdjdb(tcr_sequences, vdjdb_path='vdjdb.tsv'):
+    '''Match TCRs to known epitopes in VDJdb
+
+    VDJdb is a curated database of TCR-epitope pairs.
+    Download from: https://vdjdb.cdr3.net/
+
+    Matching approaches:
+    - Exact CDR3 match
+    - Similar CDR3 (edit distance ≤1)
+    - Cluster-based (group similar TCRs)
+    '''
+    import pandas as pd
+    from difflib import SequenceMatcher
+
+    vdjdb = pd.read_csv(vdjdb_path, sep='\t')
+
+    matches = []
+    for tcr in tcr_sequences:
+        # Exact match
+        exact = vdjdb[vdjdb['cdr3'] == tcr]
+        if len(exact) > 0:
+            matches.append({
+                'query_tcr': tcr,
+                'match_type': 'exact',
+                'epitopes': exact['antigen.epitope'].tolist(),
+                'species': exact['antigen.species'].tolist()
+            })
+            continue
+
+        # Fuzzy match (1 mismatch)
+        for _, row in vdjdb.iterrows():
+            similarity = SequenceMatcher(None, tcr, row['cdr3']).ratio()
+            if similarity > 0.9:  # >90% similar
+                matches.append({
+                    'query_tcr': tcr,
+                    'match_type': 'similar',
+                    'similarity': similarity,
+                    'db_tcr': row['cdr3'],
+                    'epitope': row['antigen.epitope'],
+                    'species': row['antigen.species']
+                })
+
+    return pd.DataFrame(matches)
+```
+
+## TCR Clustering
+
+**Goal:** Group TCRs that likely recognize the same epitope based on CDR3 sequence similarity, enabling specificity group discovery from large repertoire datasets.
+
+**Approach:** Compute pairwise Levenshtein distances between CDR3 sequences, apply hierarchical clustering with average linkage, and cut the dendrogram at a maximum edit distance threshold to define specificity groups.
+
+```python
+def cluster_tcrs_by_specificity(tcr_sequences, method='levenshtein'):
+    '''Cluster TCRs likely to share specificity
+
+    TCRs recognizing the same epitope often have:
+    - Similar CDR3 length
+    - Shared motifs
+    - Similar V gene usage
+
+    Methods:
+    - levenshtein: Edit distance clustering
+    - tcrdist: TCRdist3 distance metric
+    - deep: Deep learning embeddings
+    '''
+    from scipy.cluster.hierarchy import linkage, fcluster
+    from scipy.spatial.distance import pdist, squareform
+    import numpy as np
+
+    def levenshtein_distance(s1, s2):
+        if len(s1) < len(s2):
+            return levenshtein_distance(s2, s1)
+        if len(s2) == 0:
+            return len(s1)
+
+        previous_row = range(len(s2) + 1)
+        for i, c1 in enumerate(s1):
+            current_row = [i + 1]
+            for j, c2 in enumerate(s2):
+                insertions = previous_row[j + 1] + 1
+                deletions = current_row[j] + 1
+                substitutions = previous_row[j] + (c1 != c2)
+                current_row.append(min(insertions, deletions, substitutions))
+            previous_row = current_row
+
+        return previous_row[-1]
+
+    # Calculate pairwise distances
+    n = len(tcr_sequences)
+    distances = np.zeros((n, n))
+    for i in range(n):
+        for j in range(i + 1, n):
+            d = levenshtein_distance(tcr_sequences[i], tcr_sequences[j])
+            distances[i, j] = distances[j, i] = d
+
+    # Cluster
+    condensed = squareform(distances)
+    Z = linkage(condensed, method='average')
+    clusters = fcluster(Z, t=3, criterion='distance')  # Max 3 edits
+
+    return dict(zip(tcr_sequences, clusters))
+```
+
+## Analyze Repertoire Specificity
+
+```python
+def analyze_repertoire_specificity(tcr_df, epitope_db):
+    '''Analyze antigen specificity of TCR repertoire
+
+    Reports:
+    - Fraction matching known epitopes
+    - Epitope diversity
+    - Potential public TCRs (shared across individuals)
+    '''
+    results = {
+        'total_tcrs': len(tcr_df),
+        'unique_cdr3': tcr_df['cdr3_beta'].nunique(),
+        'matched_epitopes': 0,
+        'epitope_distribution': {}
+    }
+
+    # Match to database
+    matched = match_to_vdjdb(tcr_df['cdr3_beta'].unique(), epitope_db)
+
+    if len(matched) > 0:
+        results['matched_epitopes'] = len(matched['query_tcr'].unique())
+        results['epitope_distribution'] = matched['epitope'].value_counts().to_dict()
+
+    return results
+```
+
+## Related Skills
+
+- tcr-bcr-analysis/mixcr-analysis - TCR repertoire sequencing analysis
+- immunoinformatics/mhc-binding-prediction - Epitope context
+- single-cell/clustering - Single-cell TCR analysis

package/data/skills/bio-isoform-switching/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: bio-isoform-switching
+description: Analyzes isoform switching events and functional consequences using IsoformSwitchAnalyzeR. Predicts protein domain changes, NMD sensitivity, ORF alterations, and coding potential shifts between conditions. Use when investigating how splicing changes affect protein function.
+tool_type: r
+primary_tool: IsoformSwitchAnalyzeR
+---
+
+## Version Compatibility
+
+Reference examples tested with: Salmon 1.10+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- R: `packageVersion('<pkg>')` then `?function_name` to verify parameters
+
+If code throws ImportError, AttributeError, or TypeError, introspect the installed
+package and adapt the example to match the actual API rather than retrying.
+
+# Isoform Switching Analysis
+
+Identify isoform switches and predict their functional consequences on protein structure and function.
+
+## IsoformSwitchAnalyzeR Workflow
+
+**Goal:** Identify genes where the dominant isoform switches between conditions.
+
+**Approach:** Import Salmon quantification, filter low-expression isoforms, and test for isoform usage changes with DEXSeq-based statistics.
+
+**"Analyze isoform switching"** -> Import transcript quantification, test for dominant isoform changes, and assess functional consequences.
+- R: `IsoformSwitchAnalyzeR` (importRdata + isoformSwitchTestDEXSeq)
+
+```r
+library(IsoformSwitchAnalyzeR)
+
+# Import transcript quantification from Salmon
+salmonQuant <- importIsoformExpression(
+    parentDir = 'salmon_quant/',
+    addIsofomIdAsColumn = TRUE
+)
+
+# Create switch analysis object
+switchAnalyzeRlist <- importRdata(
+    isoformCountMatrix = salmonQuant$counts,
+    isoformRepExpression = salmonQuant$abundance,
+    designMatrix = data.frame(
+        sampleID = colnames(salmonQuant$counts),
+        condition = c('control', 'control', 'control', 'treatment', 'treatment', 'treatment')
+    ),
+    isoformExonAnnoation = 'annotation.gtf',
+    isoformNtFasta = 'transcripts.fa'
+)
+
+# Filter lowly expressed isoforms
+switchAnalyzeRlist <- preFilter(
+    switchAnalyzeRlist,
+    geneExpressionCutoff = 1,  # Minimum TPM
+    isoformExpressionCutoff = 0,
+    removeSingleIsoformGenes = TRUE
+)
+
+# Test for isoform switches
+switchAnalyzeRlist <- isoformSwitchTestDEXSeq(
+    switchAnalyzeRlist,
+    reduceToSwitchingGenes = TRUE
+)
+```
+
+## Functional Annotation
+
+**Goal:** Predict how isoform switches alter protein domains, coding potential, and localization.
+
+**Approach:** Extract isoform sequences, run external annotation tools (CPC2, Pfam, SignalP, IUPred2), and import results back into the switch analysis object.
+
+```r
+# Extract sequences for external analysis
+switchAnalyzeRlist <- extractSequence(
+    switchAnalyzeRlist,
+    pathToOutput = 'sequences/',
+    writeToFile = TRUE
+)
+
+# Run external tools and import results:
+# - CPC2 for coding potential
+# - Pfam for protein domains
+# - SignalP for signal peptides
+# - IUPred2 for intrinsic disorder
+
+# After running external tools, import results
+switchAnalyzeRlist <- analyzeCPC2(
+    switchAnalyzeRlist,
+    pathToCPC2resultFile = 'cpc2_results.txt',
+    removeNoncodinORFs = TRUE
+)
+
+switchAnalyzeRlist <- analyzePFAM(
+    switchAnalyzeRlist,
+    pathToPFAMresultFile = 'pfam_results.txt'
+)
+
+switchAnalyzeRlist <- analyzeSignalP(
+    switchAnalyzeRlist,
+    pathToSignalPresultFile = 'signalp_results.txt'
+)
+
+switchAnalyzeRlist <- analyzeIUPred2A(
+    switchAnalyzeRlist,
+    pathToIUPred2AresultFile = 'iupred2_results.txt'
+)
+```
+
+## Consequence Analysis
+
+**Goal:** Determine which isoform switches cause functional changes (NMD, domain loss, coding potential shifts).
+
+**Approach:** Run analyzeSwitchConsequences across multiple consequence types and extract switches with confirmed functional impact.
+
+```r
+# Analyze functional consequences of switches
+switchAnalyzeRlist <- analyzeSwitchConsequences(
+    switchAnalyzeRlist,
+    consequencesToAnalyze = c(
+        'intron_retention',
+        'coding_potential',
+        'ORF_seq_similarity',
+        'NMD_status',
+        'domains_identified',
+        'signal_peptide_identified'
+    ),
+    dIFcutoff = 0.1,  # Minimum isoform fraction change
+    showProgress = TRUE
+)
+
+# Extract significant switches
+significantSwitches <- extractSwitchSummary(
+    switchAnalyzeRlist,
+    filterForConsequences = TRUE
+)
+
+print(significantSwitches)
+```
+
+## Visualization
+
+**Goal:** Visualize isoform switch events and summarize functional consequence patterns.
+
+**Approach:** Generate per-gene switch plots showing isoform usage changes, and create global summaries of consequence enrichment.
+
+```r
+# Plot individual gene switches
+switchPlot(
+    switchAnalyzeRlist,
+    gene = 'GENE_OF_INTEREST',
+    condition1 = 'control',
+    condition2 = 'treatment'
+)
+
+# Summary of consequence types
+extractConsequenceSummary(
+    switchAnalyzeRlist,
+    consequencesToAnalyze = 'all',
+    plotGenes = FALSE
+)
+
+# Enrichment of consequences
+extractConsequenceEnrichment(
+    switchAnalyzeRlist,
+    consequencesToAnalyze = 'all'
+)
+```
+
+## Significance Thresholds
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| Switch q-value | < 0.05 | Significance of isoform switch |
+| dIF (delta isoform fraction) | > 0.1 | Minimum usage change |
+| Consequence q-value | < 0.05 | Significance of consequence |
+
+## Consequence Types
+
+| Consequence | Impact |
+|-------------|--------|
+| NMD sensitive | Transcript targeted for degradation |
+| Domain loss/gain | Altered protein function |
+| ORF disruption | Truncated/altered protein |
+| Signal peptide loss | Changed localization |
+| Coding potential loss | Switch to non-coding |
+
+## Related Skills
+
+- differential-splicing - Identify differential events first
+- splicing-quantification - PSI-level analysis
+- pathway-analysis/go-enrichment - Pathway enrichment of switching genes