MannLabs/proteomics-agent-skills

# Analyzing Proteomics Data with alphapepttools

alphapepttools is a Python package that provides search engine-agnostic proteomics analysis compatible with the scverse ecosystem.

## Structure

`alphapepttools` contains multiple subpackages:

`.io`: Read search engine outputs into standardized anndata format (see ./references/io-patterns.md)
`.pp`: Quality control and preprocess proteomics data
`.tl`: Statistical analysis of proteomics data (principal component analysis, differential expression)
`.pl`: Plotting and visualization functionalities
`.metrics`: Assess quality of analysis steps

# Applying Code Standards

Review checklist for ensuring analysis code meets quality standards for maintainability and reproducibility.
Covers project structure, readability, reproducibility, and documentation.

---

## Required Output Files (MANDATORY)

Your analysis MUST include these files. Do not consider the analysis complete without them:

1. **`config.py`** - All parameters with rationale comments explaining each threshold
2. **`requirements.txt`** - Pinned dependency versions (e.g., `pandas==2.0.3`)
3. **`README.md`** - Setup and usage instructions

# Batch Correction for Proteomics Data

Batch effects are systematic technical biases from sample preparation, instruments, or time points that obscure biological signals. Correction should only be applied on the protein level when diagnostics indicate necessity.

Commonly used batch effect correction algorithms include:

| Priority | Algorithm        | Description                          | When to Use                                |
| -------- | ---------------- | ------------------------------------ | ------------------------------------------ |
| 1        | ComBat           | Empirical Bayes shift+scale model    | Default choice, handles small batches well |
| 2        | Median centering | Equalizes batch-wise feature medians | Simple cases, interpretable                |
| 3        | Harmony          | Iterative mixing in PCA space        | Large datasets, many batches               |

## Workflow

# Formulating Biological Findings from Proteomics Data

This skill guides the transition from the analysis of differentially expressed proteins (upregulated and downregulated) to the synthesis of findings that highlight protein interactions, pathway cross-talk, or potential roles in disease.

## Use When

Use when all preprocessing steps (including data reading, QC, preprocessing, statistical testing) are complete, and only the biological/clinical interpretation remains.

# Workflow

## Checklist

Copy this checklist to track your progress:

# Imputing Proteomics Data

Impute missing values in protein intensity matrices for downstream analysis requiring complete data.

## When to Impute

**Impute when:**

- Downstream analysis requires complete data (e.g. PCA, COMBAT batch correction)
- Missingness rate is moderate (<30-50% per feature)

**Do NOT impute when:**

- Downstream methods handle missing data natively (mixed-effects models, limma)

# Interpreting biological results from omics analyses

This skill applies when an upstream analysis (differential expression, clustering, PCA, etc.) has generated:

- A list of significant features (a "hit list") OR
- A ranked or scored list of all features (e.g., by log2 fold-change or test statistic) OR
- Clusters or modules of co-expressed/co-regulated features OR
- A specific gene or small set of features they want to understand functionally

Features might be protein names or gene names encoding the observed proteins.

The goal of this analysis is to leverage biological knowledge databases in connection with appropriate statistical methods to find higher-order associations between individual proteins.

## Context and Definitions

# Normalizing Proteomics Data

Normalization makes samples comparable by aligning their overall intensity distributions. It serves three main goals:

- Aligning intensities across samples, which removes technical variation caused by differences in sample loading amounts or instrument behavior.
- Preserving feature ranks within each sample, so the relative ordering of features is not distorted.
- Stabilizing variance (i.e., addressing heteroscedasticity), which most downstream methods require because they assume homoscedastic noise.

After normalization, a feature's intensity should reflect its relative biological abundance within a sample and remain comparable across samples.

Common normalization methods include:

| Priority | Method                  | Input scale |
| --- | --- | --- | --- |

# Performing Proteomics Quality Control

Goal: Remove outlier samples and unsupported features from protein-level quantification matrices.

## Context and Definitions

### Key Metrics

- **Decoy prefixes**: `REV_`, `DECOY_`, or boolean decoy indicator column
- **Quality Control (QC) for technical replicates**: Remove technical replicates when coefficient of Variation (CV) > 20-30% or Pearson Correlation R < 0.9
- **Median absolute deviation (MAD)-based outlier detection**: An observation _x_ from a set of observations _X_ is flagged as an outlier when `|x - median(X)| > N × MAD(X)`, where _N_ is a user-defined factor. MAD is calculated as the median of absolute deviations from the median: `MAD(X) = median(|X - median(X)|)`.
- **Feature Completeness**: Feature-wise fraction of samples with non-missing values.

### Study Types

# Performing Proteomics Statistical Analysis
The goal of Differential Expression Analysis (DEA) is to identify proteins that change significantly between conditions.

## Context

### Experimental conditions
* **Pairwise (2 Groups):** Explicitly define "Control" vs. "Treatment"
* **Multi-Group (>2 Groups):**
    * *Reference-based:* Compare every condition against a universal control (e.g., `Drug_A vs Ctrl`, `Drug_B vs Ctrl`).
    * *All-vs-All:* Compare every permutation (e.g., `Drug_A vs Drug_B`).
    * *Global:* Use ANOVA to detect if *any* change exists across groups.

### Statistical models
* **t-test**: The default for pairwise comparisons. With small sample sizes (typically n < 5 per group), use moderated t-tests (e.g., limma's eBayes), which borrow variance information across proteins to stabilize estimates.

# Reading Proteomics Search Engine Outputs

## 1. Context

### Table Types

| Type                                   | Format                    | Feature level                                              | Use When                                         |
| -------------------------------------- | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------ |
| **Peptide spectrum match (PSM) table** | Long (one row per match)  | Precursor, Peptides (optional), Proteins, Genes (optional) | Peptide-level analysis, PTMs, custom aggregation |
| **Protein Group (PG) matrix**          | Wide (proteins × samples) | Proteins, Genes (Optional)                                 | Protein-level analysis                           |

**Use PG matrices** for protein- and gene-level analyses, if available

### Engine Detection Signatures

# Using Proteomics Skills

This is the **meta-skill** that governs how all other proteomics skills are discovered, sequenced, and applied. Each specialized skill encodes the process an expert proteomics analyst would follow for one phase of work. This skill maps an incoming task to the right phase, routes to the corresponding skill, and keeps the overall analysis on track.

When a proteomics task arrives, identify the current **phase** and apply the corresponding skill. Do not improvise a phase that a dedicated skill already covers.

## Skill Discovery

Route the task using the decision logic below:

- **Don't know what the data is or which engine produced it yet?** → `reading-proteomics-data`
- **Have a matrix but unsure if samples/features are trustworthy?** → `performing-proteomics-quality-control`
- **Need to make samples comparable / stabilize variance?** → `normalizing-proteomics-data`
- **Missing values blocking a method that needs a complete matrix?** → `imputing-proteomics-data`