@bgicli/bgicli 2.1.0 → 2.2.0

package/data/skills/bio-immunoinformatics-epitope-prediction/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: bio-immunoinformatics-epitope-prediction
+description: Predict B-cell and T-cell epitopes using BepiPred, IEDB tools, and structure-based methods for vaccine and antibody design. Identify immunogenic regions in antigens. Use when designing vaccines, mapping antibody binding sites, or predicting immunogenic peptides.
+tool_type: python
+primary_tool: BepiPred
+---
+
+## Version Compatibility
+
+Reference examples tested with: pandas 2.2+
+
+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.
+
+# Epitope Prediction
+
+**"Predict B-cell and T-cell epitopes in my protein"** → Identify immunogenic regions in antigens for vaccine design using sequence-based and structure-based prediction tools.
+- Python: IEDB API for B-cell epitope prediction (BepiPred)
+- Python: `mhcflurry` for T-cell epitope MHC binding prediction
+
+## B-Cell Epitope Prediction
+
+**Goal:** Predict linear B-cell epitopes from protein sequence using IEDB prediction tools.
+
+**Approach:** Submit sequence to IEDB B-cell prediction API with selectable method (BepiPred-2.0 recommended) and parse tab-separated results.
+
+### BepiPred-2.0 (Sequence-Based)
+
+```python
+import requests
+
+def predict_bcell_epitopes_iedb(sequence, method='bepipred2'):
+    '''Predict B-cell epitopes using IEDB API
+
+    Methods:
+    - bepipred2: Deep learning (recommended)
+    - bepipred: Original BepiPred
+    - emini: Surface accessibility
+    - kolaskar-tongaonkar: Antigenicity
+    - parker: Hydrophilicity
+
+    BepiPred-2.0 uses deep learning on crystal structures
+    Threshold: >0.5 predicted as epitope (default)
+    '''
+    url = 'http://tools-cluster-interface.iedb.org/tools_api/bcell/'
+
+    params = {
+        'method': method,
+        'sequence_text': sequence
+    }
+
+    response = requests.post(url, data=params)
+
+    # Parse response (tab-separated)
+    lines = response.text.strip().split('\n')
+    header = lines[0].split('\t')
+    data = [line.split('\t') for line in lines[1:]]
+
+    return header, data
+```
+
+### Parse BepiPred Results
+
+```python
+import pandas as pd
+
+def parse_bepipred_results(header, data, threshold=0.5):
+    '''Parse BepiPred output and identify epitope regions
+
+    Output columns:
+    - Position: Amino acid position
+    - Residue: Amino acid
+    - Score: BepiPred score (higher = more likely epitope)
+
+    Epitope threshold:
+    - >0.5: Default, balanced sensitivity/specificity
+    - >0.6: More stringent, fewer false positives
+    - >0.4: More sensitive, more candidates
+    '''
+    df = pd.DataFrame(data, columns=header)
+    df['Score'] = df['Score'].astype(float)
+    df['Position'] = df['Position'].astype(int)
+
+    # Identify epitope regions
+    df['is_epitope'] = df['Score'] > threshold
+
+    # Find continuous epitope regions
+    epitopes = []
+    current_epitope = []
+
+    for _, row in df.iterrows():
+        if row['is_epitope']:
+            current_epitope.append(row)
+        else:
+            if len(current_epitope) >= 5:  # Minimum epitope length
+                epitopes.append({
+                    'start': current_epitope[0]['Position'],
+                    'end': current_epitope[-1]['Position'],
+                    'sequence': ''.join(r['Residue'] for r in current_epitope),
+                    'avg_score': sum(r['Score'] for r in current_epitope) / len(current_epitope)
+                })
+            current_epitope = []
+
+    return df, epitopes
+```
+
+## T-Cell Epitope Prediction
+
+**Goal:** Predict T-cell epitopes by MHC-I binding across multiple HLA alleles.
+
+**Approach:** Query IEDB MHC-I API for each allele-sequence combination and aggregate predictions.
+
+```python
+def predict_tcell_epitopes_iedb(sequence, alleles, method='recommended'):
+    '''Predict T-cell epitopes using IEDB
+
+    MHC-I methods:
+    - recommended: Consensus of methods
+    - netmhcpan_ba: NetMHCpan binding affinity
+    - netmhcpan_el: NetMHCpan eluted ligand
+
+    MHC-II methods:
+    - recommended
+    - netmhciipan
+    '''
+    url = 'http://tools-cluster-interface.iedb.org/tools_api/mhci/'
+
+    results = []
+    for allele in alleles:
+        params = {
+            'method': method,
+            'sequence_text': sequence,
+            'allele': allele,
+            'length': '9'  # Most common for MHC-I
+        }
+
+        response = requests.post(url, data=params)
+        # Parse results...
+
+    return results
+```
+
+## Linear vs Conformational Epitopes
+
+**Goal:** Classify epitopes as linear (continuous) or conformational (discontinuous) and predict structure-based epitopes.
+
+**Approach:** Distinguish by residue continuity in primary sequence; for conformational epitopes, use structure-based tools (DiscoTope, ElliPro) via web servers.
+
+```python
+def classify_epitope_type(epitope_info):
+    '''Classify epitope as linear or conformational
+
+    Linear (continuous) epitopes:
+    - Consecutive amino acids in primary sequence
+    - ~10% of B-cell epitopes
+    - Easier to predict from sequence
+
+    Conformational (discontinuous) epitopes:
+    - Non-consecutive residues brought together by folding
+    - ~90% of B-cell epitopes
+    - Requires structure for prediction
+    '''
+    pass
+
+
+def predict_conformational_epitopes(pdb_file, chain='A'):
+    '''Predict conformational B-cell epitopes from structure
+
+    Uses surface accessibility and protrusion index.
+    Requires 3D structure (PDB/mmCIF).
+
+    Tools:
+    - DiscoTope 2.0 (structure-based)
+    - ElliPro (protrusion)
+    - SEPPA 3.0
+    '''
+    # Structure-based prediction requires specialized tools
+    # Usually accessed via web servers
+
+    print('For conformational epitopes:')
+    print('- DiscoTope: http://tools.iedb.org/discotope/')
+    print('- ElliPro: http://tools.iedb.org/ellipro/')
+    pass
+```
+
+## Combine Multiple Predictions
+
+**Goal:** Improve epitope prediction reliability by combining multiple methods into a consensus score.
+
+**Approach:** Run each method independently, threshold per method, then count agreements per position and assign confidence levels.
+
+```python
+def consensus_epitope_prediction(sequence, methods=['bepipred2', 'emini', 'parker']):
+    '''Combine multiple prediction methods
+
+    Consensus approach improves reliability:
+    - Regions predicted by multiple methods more reliable
+    - Different methods capture different properties
+
+    Scoring:
+    - 3/3 methods: High confidence
+    - 2/3 methods: Moderate confidence
+    - 1/3 methods: Low confidence
+    '''
+    all_results = {}
+
+    for method in methods:
+        header, data = predict_bcell_epitopes_iedb(sequence, method)
+        df = pd.DataFrame(data, columns=header)
+        all_results[method] = df
+
+    # Combine scores
+    consensus = all_results[methods[0]][['Position', 'Residue']].copy()
+
+    for method in methods:
+        threshold = 0.5 if method == 'bepipred2' else 0  # Method-specific thresholds
+        all_results[method]['is_epitope'] = all_results[method]['Score'].astype(float) > threshold
+        consensus[method] = all_results[method]['is_epitope'].astype(int)
+
+    consensus['consensus_score'] = consensus[methods].sum(axis=1)
+    consensus['confidence'] = consensus['consensus_score'].map({
+        3: 'high', 2: 'moderate', 1: 'low', 0: 'none'
+    })
+
+    return consensus
+```
+
+## Epitope Mapping from Experimental Data
+
+**Goal:** Map epitope regions from overlapping peptide array binding data.
+
+**Approach:** Process signal intensity values from overlapping peptide arrays and identify continuous high-signal regions as epitopes.
+
+```python
+def map_epitopes_from_peptide_array(array_results, overlap=11):
+    '''Map epitopes from peptide array experiments
+
+    Peptide arrays test binding of overlapping peptides
+    covering the entire antigen sequence.
+
+    Args:
+        array_results: Dict mapping peptide -> signal intensity
+        overlap: Overlap between consecutive peptides
+
+    Returns:
+        Epitope map with per-residue scores
+    '''
+    # Implementation would process experimental binding data
+    pass
+```
+
+## Related Skills
+
+- immunoinformatics/mhc-binding-prediction - T-cell epitope prediction
+- immunoinformatics/immunogenicity-scoring - Epitope ranking
+- structural-biology/geometric-analysis - Structure-based epitopes

package/data/skills/bio-immunoinformatics-immunogenicity-scoring/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: bio-immunoinformatics-immunogenicity-scoring
+description: Score and prioritize neoantigens and epitopes for immunogenicity using multi-factor models combining MHC binding, processing, expression, and sequence features. Rank candidates for vaccine design. Use when prioritizing epitopes for vaccine development or identifying the most immunogenic neoantigens.
+tool_type: python
+primary_tool: mhcflurry
+---
+
+## Version Compatibility
+
+Reference examples tested with: MHCflurry 2.1+, numpy 1.26+, pandas 2.2+
+
+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.
+
+# Immunogenicity Scoring
+
+**"Rank my neoantigen candidates by immunogenicity"** → Score and prioritize epitopes using multi-factor models combining MHC binding, proteasomal processing, expression level, and sequence foreignness for vaccine candidate selection.
+- Python: `mhcflurry` for binding + processing predictions, custom scoring pipeline
+
+## Multi-Factor Scoring
+
+**Goal:** Calculate a composite immunogenicity score from multiple weighted factors (binding, agretopicity, processing, expression, clonality, foreignness).
+
+**Approach:** Score each factor on a 0-1 scale, then combine via weighted sum with domain-informed weights.
+
+```python
+import pandas as pd
+import numpy as np
+
+def calculate_immunogenicity_score(peptide_data):
+    '''Calculate composite immunogenicity score
+
+    Factors considered:
+    1. MHC binding affinity (IC50)
+    2. Agretopicity (MT vs WT binding ratio)
+    3. Proteasomal processing
+    4. TAP transport
+    5. Expression level
+    6. Clonality (VAF for neoantigens)
+    7. Self-similarity (avoid tolerance)
+
+    Each factor scored 0-1, then weighted and combined.
+    '''
+    scores = {}
+
+    # 1. Binding affinity (lower IC50 = better)
+    # Transform to 0-1: 1 at 0nM, 0 at 5000nM
+    ic50 = peptide_data.get('ic50_nM', 500)
+    scores['binding'] = 1 - min(ic50 / 5000, 1)
+
+    # 2. Agretopicity (MT binds better than WT)
+    # Ratio of WT/MT IC50, capped at 10
+    agretopicity = peptide_data.get('agretopicity', 1.0)
+    scores['agretopicity'] = min(agretopicity / 10, 1)
+
+    # 3. Processing score (from MHCflurry)
+    processing = peptide_data.get('processing_score', 0.5)
+    scores['processing'] = processing
+
+    # 4. Expression (log scale, capped)
+    expression = peptide_data.get('expression_tpm', 10)
+    scores['expression'] = min(np.log10(expression + 1) / 3, 1)
+
+    # 5. Clonality (for neoantigens)
+    vaf = peptide_data.get('vaf', 0.5)
+    scores['clonality'] = vaf
+
+    # 6. Self-similarity (lower = better, less tolerance)
+    self_sim = peptide_data.get('self_similarity', 0.5)
+    scores['foreignness'] = 1 - self_sim
+
+    # Weighted combination
+    weights = {
+        'binding': 0.25,
+        'agretopicity': 0.20,
+        'processing': 0.10,
+        'expression': 0.15,
+        'clonality': 0.15,
+        'foreignness': 0.15
+    }
+
+    total = sum(scores[k] * weights[k] for k in weights)
+
+    return total, scores
+```
+
+## Processing Prediction
+
+**Goal:** Predict proteasomal cleavage and TAP transport probability for candidate peptides.
+
+**Approach:** Use MHCflurry's Class1ProcessingPredictor to score peptide processing likelihood.
+
+```python
+from mhcflurry import Class1ProcessingPredictor
+
+def predict_processing_score(peptides):
+    '''Predict proteasomal cleavage and TAP transport
+
+    Processing score reflects probability that peptide will be:
+    1. Cleaved from protein by proteasome
+    2. Transported by TAP into ER
+    3. Loaded onto MHC
+
+    Higher processing score = more likely to be presented
+    '''
+    predictor = Class1ProcessingPredictor.load()
+
+    results = []
+    for peptide in peptides:
+        # Need surrounding sequence context for processing
+        # In practice, extract from protein context
+        pred = predictor.predict(peptides=[peptide])
+        results.append({
+            'peptide': peptide,
+            'processing_score': pred['processing_score'].values[0]
+        })
+
+    return pd.DataFrame(results)
+```
+
+## Self-Similarity Assessment
+
+**Goal:** Determine whether a candidate peptide resembles self-peptides, indicating potential T-cell tolerance.
+
+**Approach:** Compute pairwise sequence identity against a proteome peptide set and flag high-similarity matches.
+
+```python
+def calculate_self_similarity(peptide, proteome_peptides, threshold=0.8):
+    '''Check if peptide is similar to self-peptides
+
+    High similarity to self-peptides suggests:
+    - T-cells may be tolerized (deleted during development)
+    - Lower likelihood of immune response
+
+    Threshold 0.8 = 80% identity considered "self-like"
+    '''
+    def sequence_identity(seq1, seq2):
+        if len(seq1) != len(seq2):
+            return 0
+        matches = sum(1 for a, b in zip(seq1, seq2) if a == b)
+        return matches / len(seq1)
+
+    max_similarity = 0
+    most_similar = None
+
+    for self_peptide in proteome_peptides:
+        sim = sequence_identity(peptide, self_peptide)
+        if sim > max_similarity:
+            max_similarity = sim
+            most_similar = self_peptide
+
+    return {
+        'similarity': max_similarity,
+        'is_self_like': max_similarity >= threshold,
+        'closest_self': most_similar
+    }
+```
+
+## Hydrophobicity at Position 2
+
+**Goal:** Assess MHC anchor residue quality by checking hydrophobicity at key positions.
+
+**Approach:** Check whether position 2 and C-terminal residues fall within the hydrophobic amino acid set preferred by HLA-A*02:01-like alleles.
+
+```python
+def check_anchor_hydrophobicity(peptide):
+    '''Check hydrophobicity at MHC anchor positions
+
+    For HLA-A*02:01 and similar alleles:
+    - Position 2: Prefers hydrophobic (L, I, V, M)
+    - Position 9 (C-terminus): Prefers hydrophobic (L, V, I)
+
+    Strong anchors improve binding stability.
+    '''
+    hydrophobic = set('LIVMFYW')
+
+    pos2 = peptide[1] if len(peptide) > 1 else ''
+    pos_last = peptide[-1]
+
+    return {
+        'pos2_hydrophobic': pos2 in hydrophobic,
+        'pos_last_hydrophobic': pos_last in hydrophobic,
+        'anchor_score': (pos2 in hydrophobic) + (pos_last in hydrophobic)
+    }
+```
+
+## Rank Epitopes
+
+**Goal:** Rank epitopes by composite immunogenicity score and assign confidence tiers for prioritization.
+
+**Approach:** Score all candidates, sort by immunogenicity, and assign high/medium/low tiers based on percentile ranking.
+
+```python
+def rank_epitopes(epitope_df, top_n=20):
+    '''Rank epitopes by immunogenicity
+
+    Returns top candidates with scores and confidence tiers.
+
+    Confidence tiers:
+    - High: Top 5%, all factors favorable
+    - Medium: Top 20%, most factors favorable
+    - Low: Remaining, some factors favorable
+    '''
+    epitope_df = epitope_df.copy()
+
+    # Calculate scores
+    scores = []
+    factor_scores = []
+    for _, row in epitope_df.iterrows():
+        total, factors = calculate_immunogenicity_score(row.to_dict())
+        scores.append(total)
+        factor_scores.append(factors)
+
+    epitope_df['immunogenicity_score'] = scores
+    factor_df = pd.DataFrame(factor_scores)
+
+    # Combine
+    result = pd.concat([epitope_df, factor_df], axis=1)
+
+    # Rank
+    result = result.sort_values('immunogenicity_score', ascending=False)
+
+    # Assign tiers
+    n = len(result)
+    result['tier'] = 'low'
+    result.iloc[:int(n * 0.20), result.columns.get_loc('tier')] = 'medium'
+    result.iloc[:int(n * 0.05), result.columns.get_loc('tier')] = 'high'
+
+    return result.head(top_n)
+```
+
+## Compare Candidates
+
+**Goal:** Select a diverse set of vaccine candidates with broad HLA coverage and non-overlapping positions.
+
+**Approach:** Iterate through ranked candidates, selecting those with non-overlapping genomic positions to maximize epitope diversity.
+
+```python
+def compare_vaccine_candidates(candidates_df):
+    '''Compare and select vaccine candidates
+
+    Vaccine design typically selects:
+    - Multiple epitopes (5-20)
+    - Diverse HLA coverage
+    - High immunogenicity scores
+    - Non-overlapping sequences
+    '''
+    # Group by HLA coverage
+    hla_coverage = candidates_df.groupby('allele').size()
+
+    # Select diverse set
+    selected = []
+    used_positions = set()
+
+    for _, candidate in candidates_df.iterrows():
+        # Check for overlap with selected
+        pos = candidate.get('position', 0)
+        if not any(abs(pos - p) < 5 for p in used_positions):
+            selected.append(candidate)
+            used_positions.add(pos)
+
+        if len(selected) >= 20:
+            break
+
+    return pd.DataFrame(selected)
+```
+
+## Related Skills
+
+- immunoinformatics/mhc-binding-prediction - Binding affinity component
+- immunoinformatics/neoantigen-prediction - Input candidates
+- immunoinformatics/epitope-prediction - Epitope identification