@bgicli/bgicli 2.1.1 → 2.2.0

package/data/skills/bio-proteomics-differential-abundance/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: bio-proteomics-differential-abundance
+description: Statistical testing for differentially abundant proteins between conditions. Covers limma and MSstats workflows with multiple testing correction. Use when identifying proteins with significant abundance changes between experimental groups.
+tool_type: mixed
+primary_tool: MSstats
+---
+
+## Version Compatibility
+
+Reference examples tested with: R stats (base), ggplot2 3.5+, limma 3.58+, numpy 1.26+, pandas 2.2+, scipy 1.12+, statsmodels 0.14+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+- 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.
+
+# Differential Protein Abundance
+
+**"Find differentially abundant proteins between my conditions"** → Perform statistical testing on quantified protein intensities to identify proteins with significant abundance changes between experimental groups.
+- R: `MSstats::groupComparison()` for feature-level mixed models
+- R: `limma::eBayes()` for empirical Bayes moderated t-tests on protein-level data
+- Python: `scipy.stats.ttest_ind()` with `statsmodels` FDR correction
+
+## MSstats Group Comparison (R stats (base)+)
+
+**Goal:** Identify differentially abundant proteins between experimental conditions using feature-level mixed models or moderated t-tests.
+
+**Approach:** Define contrast matrices for pairwise comparisons, run MSstats groupComparison (or limma eBayes for protein-level data), then filter results by adjusted p-value and log2 fold change thresholds.
+
+```r
+library(MSstats)
+
+# After dataProcess()
+comparison_matrix <- matrix(c(1, -1, 0, 0,
+                               1, 0, -1, 0,
+                               0, 1, -1, 0),
+                             nrow = 3, byrow = TRUE)
+rownames(comparison_matrix) <- c('Treatment1-Control', 'Treatment2-Control', 'Treatment1-Treatment2')
+colnames(comparison_matrix) <- c('Control', 'Treatment1', 'Treatment2', 'Treatment3')
+
+results <- groupComparison(contrast.matrix = comparison_matrix, data = processed)
+
+# Significant proteins
+sig_proteins <- results$ComparisonResult[results$ComparisonResult$adj.pvalue < 0.05 &
+                                          abs(results$ComparisonResult$log2FC) > 1, ]
+```
+
+## limma for Proteomics (R stats (base)+)
+
+```r
+library(limma)
+
+# Log2 intensities matrix (proteins x samples)
+design <- model.matrix(~ 0 + condition, data = sample_info)
+colnames(design) <- levels(sample_info$condition)
+
+fit <- lmFit(protein_matrix, design)
+
+contrast_matrix <- makeContrasts(Treatment - Control, levels = design)
+fit2 <- contrasts.fit(fit, contrast_matrix)
+fit2 <- eBayes(fit2)
+
+results <- topTable(fit2, number = Inf, adjust.method = 'BH')
+sig_results <- results[results$adj.P.Val < 0.05 & abs(results$logFC) > 1, ]
+```
+
+## QFeatures/proDA (Modern Alternative)
+
+```r
+library(QFeatures)
+library(proDA)
+
+# proDA handles missing values probabilistically
+fit <- proDA(protein_matrix, design = ~ condition, data = sample_info)
+
+# Test differential abundance
+results <- test_diff(fit, contrast = 'conditionTreatment')
+results$adj_pval <- p.adjust(results$pval, method = 'BH')
+sig_results <- results[results$adj_pval < 0.05 & abs(results$diff) > 1, ]
+```
+
+## Python: scipy/statsmodels
+
+```python
+import pandas as pd
+import numpy as np
+from scipy import stats
+from statsmodels.stats.multitest import multipletests
+
+def differential_test(intensities, group1_cols, group2_cols):
+    results = []
+    for protein in intensities.index:
+        g1 = intensities.loc[protein, group1_cols].dropna()
+        g2 = intensities.loc[protein, group2_cols].dropna()
+
+        if len(g1) >= 2 and len(g2) >= 2:
+            stat, pval = stats.ttest_ind(g1, g2)
+            log2fc = g2.mean() - g1.mean()
+            results.append({'protein': protein, 'log2FC': log2fc, 'pvalue': pval})
+
+    df = pd.DataFrame(results)
+    df['adj_pvalue'] = multipletests(df['pvalue'], method='fdr_bh')[1]
+    return df
+
+# Significance thresholds
+sig = results[(results['adj_pvalue'] < 0.05) & (abs(results['log2FC']) > 1)]
+```
+
+## Visualization (R stats (base)+)
+
+```r
+# Volcano plot
+library(ggplot2)
+
+ggplot(results, aes(x = log2FC, y = -log10(adj.P.Val))) +
+    geom_point(aes(color = significant), alpha = 0.6) +
+    geom_hline(yintercept = -log10(0.05), linetype = 'dashed') +
+    geom_vline(xintercept = c(-1, 1), linetype = 'dashed') +
+    scale_color_manual(values = c('grey', 'red')) +
+    theme_minimal()
+```
+
+## Related Skills
+
+- quantification - Prepare normalized data for testing
+- differential-expression/deseq2-basics - Similar concepts for RNA-seq
+- data-visualization/specialized-omics-plots - Volcano plots, MA plots

package/data/skills/bio-proteomics-peptide-identification/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: bio-proteomics-peptide-identification
+description: Peptide-spectrum matching and protein identification from MS/MS data. Use when identifying peptides from tandem mass spectra. Covers database searching, spectral library matching, and FDR estimation using target-decoy approaches.
+tool_type: mixed
+primary_tool: pyOpenMS
+---
+
+## Version Compatibility
+
+Reference examples tested with: MSnbase 2.28+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+- 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.
+
+# Peptide Identification
+
+**"Identify peptides from my MS/MS spectra"** → Match tandem mass spectra against a protein database to identify peptide sequences, then control false discovery rate using target-decoy competition.
+- Python: `pyopenms` for in-memory database search and PSM handling
+- CLI: `comet`, `MSFragger`, `X!Tandem` for high-throughput database searching
+- R: `MSnbase::readMSData()` for importing search results
+
+## Database Search with pyOpenMS
+
+**Goal:** Identify peptide sequences from tandem mass spectra by matching against a protein database.
+
+**Approach:** Load a FASTA database, perform in-silico tryptic digestion to generate theoretical peptides, then match experimental spectra against theoretical fragment ion patterns to identify peptide-spectrum matches (PSMs).
+
+```python
+from pyopenms import MSExperiment, MzMLFile, FASTAFile, ProteaseDigestion
+from pyopenms import ModificationsDB, AASequence
+
+# Load FASTA database
+fasta_entries = []
+FASTAFile().load('uniprot_human.fasta', fasta_entries)
+
+# In-silico digestion
+digestion = ProteaseDigestion()
+digestion.setEnzyme('Trypsin')
+digestion.setMissedCleavages(2)
+
+peptides = []
+for entry in fasta_entries:
+    seq = AASequence.fromString(entry.sequence)
+    result = []
+    digestion.digest(seq, result)
+    peptides.extend([(entry.identifier, str(p)) for p in result])
+```
+
+## Working with Search Results (idXML)
+
+```python
+from pyopenms import IdXMLFile, ProteinIdentification, PeptideIdentification
+
+protein_ids = []
+peptide_ids = []
+IdXMLFile().load('search_results.idXML', protein_ids, peptide_ids)
+
+for pep_id in peptide_ids:
+    rt = pep_id.getRT()
+    mz = pep_id.getMZ()
+    for hit in pep_id.getHits():
+        sequence = hit.getSequence()
+        score = hit.getScore()
+        charge = hit.getCharge()
+```
+
+## FDR Estimation (Target-Decoy)
+
+```python
+def calculate_fdr(scores, is_decoy, score_threshold):
+    above_threshold = scores >= score_threshold
+    n_target = ((~is_decoy) & above_threshold).sum()
+    n_decoy = (is_decoy & above_threshold).sum()
+    fdr = n_decoy / n_target if n_target > 0 else 1.0
+    return fdr
+
+def find_score_at_fdr(scores, is_decoy, target_fdr=0.01):
+    sorted_scores = np.sort(scores)[::-1]
+    for threshold in sorted_scores:
+        fdr = calculate_fdr(scores, is_decoy, threshold)
+        if fdr <= target_fdr:
+            return threshold
+    return sorted_scores[-1]
+```
+
+## R: Search Result Processing
+
+```r
+library(MSnbase)
+
+# Read mzIdentML results
+psms <- readMzIdData('results.mzid')
+
+# Filter to 1% FDR
+psms_filtered <- psms[psms$qvalue <= 0.01, ]
+
+# Unique peptides per protein
+peptide_counts <- table(psms_filtered$accession)
+```
+
+## Spectral Library Search
+
+```python
+from pyopenms import SpectraSTSearchAlgorithm, MSExperiment
+
+# Load spectral library
+library = MSExperiment()
+MzMLFile().load('spectral_library.mzML', library)
+
+# Match query spectra against library
+# Returns similarity scores and library matches
+```
+
+## Related Skills
+
+- data-import - Load raw MS data before identification
+- protein-inference - Group peptides to proteins
+- ptm-analysis - Identify modified peptides

package/data/skills/bio-proteomics-protein-inference/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: bio-proteomics-protein-inference
+description: Protein grouping and inference from peptide identifications. Use when resolving protein ambiguity from shared peptides. Handles protein groups and protein-level FDR control using parsimony and probabilistic approaches.
+tool_type: mixed
+primary_tool: pyOpenMS
+---
+
+## Version Compatibility
+
+Reference examples tested with: pyOpenMS 3.1+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+- 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.
+
+# Protein Inference
+
+**"Resolve protein groups from my peptide identifications"** → Group peptide-spectrum matches into protein groups, resolving shared-peptide ambiguity using parsimony or probabilistic methods, then apply protein-level FDR.
+- Python: `pyopenms.ProteinInference()` for parsimony-based grouping
+- R: Bioconductor protein inference workflows
+
+## The Protein Inference Problem
+
+Peptides can map to multiple proteins (shared peptides), making protein identification ambiguous.
+
+```python
+# Example: Peptide mapping
+peptide_to_proteins = {
+    'PEPTIDEK': ['P12345', 'P67890'],      # Shared between paralogs
+    'UNIQUER': ['P12345'],                  # Unique to P12345
+    'ANOTHERONE': ['P12345'],               # Unique to P12345
+    'SHAREDK': ['P67890', 'P11111'],        # Shared
+}
+
+# P12345 has 2 unique peptides -> confident identification
+# P67890 has 0 unique peptides -> subset, may be grouped with P12345
+```
+
+## Parsimony Principle
+
+**Goal:** Resolve protein identification ambiguity from shared peptides by finding the minimal protein set explaining all observed peptides.
+
+**Approach:** Build a peptide-to-protein mapping, then greedily select proteins that cover the most unassigned peptides until all peptides are accounted for, producing a minimal explanatory protein list.
+
+```python
+def apply_parsimony(peptide_protein_map):
+    '''Find minimal set of proteins explaining all peptides'''
+    proteins = set()
+    for prots in peptide_protein_map.values():
+        proteins.update(prots)
+
+    protein_peptides = {p: set() for p in proteins}
+    for pep, prots in peptide_protein_map.items():
+        for p in prots:
+            protein_peptides[p].add(pep)
+
+    covered_peptides = set()
+    selected_proteins = []
+
+    # Greedy: select protein covering most uncovered peptides
+    while covered_peptides != set(peptide_protein_map.keys()):
+        best_protein = max(protein_peptides.keys(),
+                          key=lambda p: len(protein_peptides[p] - covered_peptides))
+        new_coverage = protein_peptides[best_protein] - covered_peptides
+        if not new_coverage:
+            break
+        selected_proteins.append(best_protein)
+        covered_peptides.update(new_coverage)
+
+    return selected_proteins
+```
+
+## Protein Groups
+
+```python
+def create_protein_groups(peptide_protein_map):
+    '''Group proteins with identical peptide evidence'''
+    protein_peptides = {}
+    for pep, prots in peptide_protein_map.items():
+        for p in prots:
+            protein_peptides.setdefault(p, set()).add(pep)
+
+    # Group by peptide set
+    peptide_set_to_proteins = {}
+    for protein, peptides in protein_peptides.items():
+        key = frozenset(peptides)
+        peptide_set_to_proteins.setdefault(key, []).append(protein)
+
+    groups = []
+    for peptides, proteins in peptide_set_to_proteins.items():
+        groups.append({
+            'proteins': proteins,
+            'peptides': list(peptides),
+            'n_peptides': len(peptides),
+            'is_group': len(proteins) > 1
+        })
+
+    return groups
+```
+
+## pyOpenMS Protein Inference
+
+```python
+from pyopenms import ProteinIdentification, PeptideIdentification
+from pyopenms import BasicProteinInferenceAlgorithm
+
+# Load identifications
+protein_ids = []
+peptide_ids = []
+IdXMLFile().load('search_results.idXML', protein_ids, peptide_ids)
+
+# Run inference
+inference = BasicProteinInferenceAlgorithm()
+inference.run(peptide_ids, protein_ids)
+
+# Results include protein groups and scores
+for protein_id in protein_ids:
+    for hit in protein_id.getHits():
+        accession = hit.getAccession()
+        score = hit.getScore()
+```
+
+## R: Protein Inference with ProteinInference
+
+```r
+library(ProteinInference)
+
+# From peptide-protein mapping
+protein_groups <- infer_proteins(
+    peptides = psm_data$peptide,
+    proteins = psm_data$protein,
+    method = 'parsimony'
+)
+
+# Count unique peptides per group
+protein_groups$n_unique <- sapply(protein_groups$peptides, function(p) {
+    sum(sapply(p, function(pep) length(peptide_to_protein[[pep]]) == 1))
+})
+```
+
+## Protein-Level FDR
+
+```python
+def protein_fdr(protein_groups, target_fdr=0.01):
+    '''Calculate protein-level FDR from group scores'''
+    sorted_groups = sorted(protein_groups, key=lambda x: x['score'], reverse=True)
+
+    target_count = 0
+    decoy_count = 0
+
+    for group in sorted_groups:
+        if group['is_decoy']:
+            decoy_count += 1
+        else:
+            target_count += 1
+        group['fdr'] = decoy_count / target_count if target_count > 0 else 1.0
+
+    # Q-value
+    min_fdr = 1.0
+    for group in reversed(sorted_groups):
+        min_fdr = min(min_fdr, group['fdr'])
+        group['qvalue'] = min_fdr
+
+    return [g for g in sorted_groups if g['qvalue'] <= target_fdr and not g['is_decoy']]
+```
+
+## Related Skills
+
+- peptide-identification - Input for protein inference
+- quantification - Quantify inferred proteins
+- database-access/uniprot-access - Protein annotations

package/data/skills/bio-proteomics-proteomics-qc/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: bio-proteomics-proteomics-qc
+description: Quality control and assessment for proteomics data. Use when evaluating proteomics data quality before downstream analysis. Covers sample metrics, missing value patterns, replicate correlation, batch effects, and intensity distributions.
+tool_type: mixed
+primary_tool: pandas
+---
+
+## Version Compatibility
+
+Reference examples tested with: ggplot2 3.5+, limma 3.58+, matplotlib 3.8+, numpy 1.26+, pandas 2.2+, scikit-learn 1.4+, scipy 1.12+, seaborn 0.13+
+
+Before using code patterns, verify installed versions match. If versions differ:
+- Python: `pip show <package>` then `help(module.function)` to check signatures
+- 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.
+
+# Proteomics Quality Control
+
+**"Check the quality of my proteomics data"** → Assess data quality through identification rates, missing value patterns, replicate correlation, intensity distributions, and batch effect detection before downstream analysis.
+- Python: `pandas` + `matplotlib`/`seaborn` for QC metrics and visualization
+- R: `limma::plotMDS()`, correlation heatmaps, CV distributions
+
+## Sample Quality Metrics
+
+```python
+import pandas as pd
+import numpy as np
+
+def sample_qc_metrics(intensity_matrix):
+    '''Calculate per-sample QC metrics'''
+    metrics = pd.DataFrame(index=intensity_matrix.columns)
+    metrics['n_proteins'] = intensity_matrix.notna().sum()
+    metrics['median_intensity'] = intensity_matrix.median()
+    metrics['mean_intensity'] = intensity_matrix.mean()
+    metrics['cv'] = intensity_matrix.std() / intensity_matrix.mean()
+    metrics['missing_pct'] = 100 * intensity_matrix.isna().sum() / len(intensity_matrix)
+    return metrics
+
+qc = sample_qc_metrics(log2_intensities)
+print(qc)
+```
+
+## Replicate Correlation
+
+```python
+import seaborn as sns
+import matplotlib.pyplot as plt
+from scipy.stats import pearsonr
+
+def replicate_correlation(intensity_matrix, sample_groups):
+    '''Calculate within-group correlations'''
+    corr_matrix = intensity_matrix.corr(method='pearson')
+
+    # Mask for within-group comparisons
+    results = []
+    for group in sample_groups.unique():
+        group_samples = sample_groups[sample_groups == group].index
+        for i, s1 in enumerate(group_samples):
+            for s2 in group_samples[i+1:]:
+                r = corr_matrix.loc[s1, s2]
+                results.append({'group': group, 'sample1': s1, 'sample2': s2, 'correlation': r})
+
+    return pd.DataFrame(results)
+
+# Heatmap
+sns.clustermap(intensity_matrix.corr(), cmap='RdBu_r', center=0, vmin=-1, vmax=1,
+               figsize=(10, 10), annot=False)
+plt.savefig('correlation_heatmap.pdf')
+```
+
+## Missing Value Patterns
+
+```python
+import missingno as msno
+
+def analyze_missing_patterns(intensity_matrix):
+    '''Analyze missing value patterns'''
+    # Missing value matrix visualization
+    msno.matrix(intensity_matrix, figsize=(12, 8))
+    plt.savefig('missing_pattern.pdf')
+
+    # Missing by sample
+    missing_per_sample = intensity_matrix.isna().sum() / len(intensity_matrix) * 100
+
+    # Missing by protein
+    missing_per_protein = intensity_matrix.isna().sum(axis=1) / intensity_matrix.shape[1] * 100
+
+    # Check for systematic patterns
+    return {'per_sample': missing_per_sample, 'per_protein': missing_per_protein}
+```
+
+## Batch Effect Detection with PCA
+
+**Goal:** Detect batch effects in proteomics data by testing whether processing batches explain significant variance in the principal components.
+
+**Approach:** Impute missing values, scale the intensity matrix, run PCA, then test the association of each top PC with batch labels using one-way ANOVA.
+
+```python
+from sklearn.preprocessing import StandardScaler
+from sklearn.decomposition import PCA
+
+def detect_batch_effects(intensity_matrix, sample_info, batch_col='batch'):
+    '''PCA to detect batch effects'''
+    # Impute for PCA (temporary)
+    imputed = intensity_matrix.fillna(intensity_matrix.median())
+    scaled = StandardScaler().fit_transform(imputed.T)
+
+    pca = PCA(n_components=5)
+    pcs = pca.fit_transform(scaled)
+    pc_df = pd.DataFrame(pcs, columns=[f'PC{i+1}' for i in range(5)], index=intensity_matrix.columns)
+    pc_df = pc_df.join(sample_info)
+
+    # Check batch association with PCs
+    from scipy.stats import f_oneway
+    for pc in ['PC1', 'PC2', 'PC3']:
+        groups = [pc_df[pc_df[batch_col] == b][pc] for b in pc_df[batch_col].unique()]
+        stat, pval = f_oneway(*groups)
+        print(f'{pc} ~ {batch_col}: F={stat:.2f}, p={pval:.4f}')
+
+    return pc_df, pca.explained_variance_ratio_
+```
+
+## R: QC with limma
+
+```r
+library(limma)
+library(ggplot2)
+
+# Intensity distribution
+plotDensities(protein_matrix, legend = FALSE, main = 'Intensity Distributions')
+
+# MA plots between samples
+for (i in 2:ncol(protein_matrix)) {
+    plotMA(protein_matrix[, c(1, i)], main = paste('MA:', colnames(protein_matrix)[i]))
+}
+
+# MDS plot (similar to PCA)
+plotMDS(protein_matrix, col = as.numeric(sample_info$condition))
+```
+
+## Coefficient of Variation
+
+```python
+def calculate_cv(intensity_matrix, sample_groups):
+    '''Calculate CV within groups'''
+    cv_results = []
+    for group in sample_groups.unique():
+        group_samples = sample_groups[sample_groups == group].index
+        group_data = intensity_matrix[group_samples]
+
+        # CV per protein
+        cv = group_data.std(axis=1) / group_data.mean(axis=1) * 100
+        cv_results.append({'group': group, 'median_cv': cv.median(), 'mean_cv': cv.mean()})
+
+    return pd.DataFrame(cv_results)
+
+# Technical replicates should have CV < 20%
+# Biological replicates typically 20-40%
+```
+
+## Digestion Efficiency
+
+```python
+def check_digestion(evidence_df):
+    '''Check digestion efficiency from MaxQuant evidence.txt'''
+    # Missed cleavages distribution
+    mc_dist = evidence_df['Missed cleavages'].value_counts(normalize=True) * 100
+    print('Missed cleavage distribution:')
+    print(mc_dist)
+
+    # Good digestion: >80% with 0 missed cleavages
+    if mc_dist.get(0, 0) < 80:
+        print('Warning: Poor digestion efficiency (<80% fully cleaved)')
+
+    return mc_dist
+```
+
+## QC Report Summary
+
+```python
+def generate_qc_report(intensity_matrix, sample_info):
+    '''Generate comprehensive QC summary'''
+    report = {
+        'n_samples': intensity_matrix.shape[1],
+        'n_proteins': intensity_matrix.shape[0],
+        'median_proteins_per_sample': intensity_matrix.notna().sum().median(),
+        'overall_missing_pct': 100 * intensity_matrix.isna().sum().sum() / intensity_matrix.size,
+        'median_correlation': intensity_matrix.corr().values[np.triu_indices_from(intensity_matrix.corr(), k=1)].mean(),
+    }
+
+    # Flags
+    report['flags'] = []
+    if report['overall_missing_pct'] > 30:
+        report['flags'].append('High missing values (>30%)')
+    if report['median_correlation'] < 0.9:
+        report['flags'].append('Low replicate correlation (<0.9)')
+
+    return report
+```
+
+## Related Skills
+
+- data-import - Load data before QC
+- quantification - Normalization after QC
+- differential-abundance - Analysis after QC passes
+- data-visualization/heatmaps-clustering - QC heatmaps