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
Column Mapping References contain the mapping of search-engine columns to standardized columns. Multiple column names might map to the same standardized column name, depending on the search engine version
- references/psm-columns.md — PSM table mappings
- references/pg-columns.md — PG matrix mappings
| Engine |
Key Columns |
Typical Files |
| DIA-NN |
Precursor.Id, Protein.Group, Run |
pg_matrix.tsv, report.tsv |
| MaxQuant |
Raw file, Protein IDs |
proteinGroups.txt, evidence.txt |
| Spectronaut |
PG.ProteinGroups, R.FileName |
*_Report.tsv |
| AlphaDIA |
pg, precursor.idx, run |
pg_matrix.tsv |
| Sage |
filename, stripped_peptide, sage_discriminant_score |
results.sage.tsv |
| MSFragger |
Protein ID, Spectral Count |
combined_protein.tsv, psm.tsv |
| AlphaPept |
Unnamed: 0, _LFQ suffix |
results.hdf |
Intensity Types
| Type |
Use Case |
| LFQ/MaxLFQ |
Cross-sample comparison (preferred) |
| MS1 |
Precursor area (DIA/DDA) |
| MS2 |
Fragment-based quantification (DIA) |
Use LFQ-normalized intensities for inter-sample comparisons, if available.
2. Workflow Checklist
3. Troubleshooting
| Issue |
Solution |
MaxQuant decoy indicator Reverse uses + not boolean |
Filter: df['Reverse'] != '+' |
| Spectronaut column names vary by export schema |
Inspect actual columns |
| AlphaPept HDF5 requires key |
Use key='protein_table' |
| Zero values may mean "not detected" |
Treat 0 as NA before statistics |
| Decoy prefix is on protein ID, not sequence |
Check proteins/uniprot_ids column |
1---2name: reading-proteomics-data3description: Read proteomics search engine outputs (PSM tables, protein matrices) from search engines like DIA-NN, MaxQuant, Spectronaut, AlphaDIA, MSFragger, Sage. Use for ingesting data, mapping columns to standard names, and initial filtering.4---56# Reading Proteomics Search Engine Outputs78## 1. Context910### Table Types1112| Type | Format | Feature level | Use When |13| -------------------------------------- | ------------------------- | ---------------------------------------------------------- | ------------------------------------------------ |14| **Peptide spectrum match (PSM) table** | Long (one row per match) | Precursor, Peptides (optional), Proteins, Genes (optional) | Peptide-level analysis, PTMs, custom aggregation |15| **Protein Group (PG) matrix** | Wide (proteins × samples) | Proteins, Genes (Optional) | Protein-level analysis |1617**Use PG matrices** for protein- and gene-level analyses, if available1819### Engine Detection Signatures2021**Column Mapping References** contain the mapping of search-engine columns to standardized columns. Multiple column names might map to the same standardized column name, depending on the search engine version2223- [references/psm-columns.md](references/psm-columns.md) — PSM table mappings24- [references/pg-columns.md](references/pg-columns.md) — PG matrix mappings2526| Engine | Key Columns | Typical Files |27| ----------- | --------------------------------------------------------- | ----------------------------------- |28| DIA-NN | `Precursor.Id`, `Protein.Group`, `Run` | `pg_matrix.tsv`, `report.tsv` |29| MaxQuant | `Raw file`, `Protein IDs` | `proteinGroups.txt`, `evidence.txt` |30| Spectronaut | `PG.ProteinGroups`, `R.FileName` | `*_Report.tsv` |31| AlphaDIA | `pg`, `precursor.idx`, `run` | `pg_matrix.tsv` |32| Sage | `filename`, `stripped_peptide`, `sage_discriminant_score` | `results.sage.tsv` |33| MSFragger | `Protein ID`, `Spectral Count` | `combined_protein.tsv`, `psm.tsv` |34| AlphaPept | `Unnamed: 0`, `_LFQ` suffix | `results.hdf` |3536### Intensity Types3738| Type | Use Case |39| -------------- | ----------------------------------- |40| **LFQ/MaxLFQ** | Cross-sample comparison (preferred) |41| **MS1** | Precursor area (DIA/DDA) |42| **MS2** | Fragment-based quantification (DIA) |4344**Use LFQ-normalized intensities** for inter-sample comparisons, if available.4546## 2. Workflow Checklist4748- [ ] **Identify format:** `.tsv`/`.csv`/`.parquet`/`.hdf`, search engine (based on signature columns), and table type (PSM table vs. PG table, based on long vs. wide format)49- [ ] **Read file:** Use appropriate table parsing engine50- [ ] **Map columns:** See [references/psm-columns.md](references/psm-columns.md) or [references/pg-columns.md](references/pg-columns.md)51- [ ] **Filter (PSM only):** Remove rows where `fdr > 0.01`52- [ ] **Remove decoys:** Filter by decoy indicator column OR protein ID prefix (`REV_`, `DECOY_`)53- [ ] **Remove contaminants:** Filter protein ID prefix (`CON_`, `contaminant_`)54- [ ] **Pivot and transpose** Validate that table is in wide format with samples as rows and features as columns (scikit-learn convention)55- [ ] **Validate:** Confirm that table contains numeric intensities5657## 3. Troubleshooting5859| Issue | Solution |60| ------------------------------------------------------- | ------------------------------------- |61| MaxQuant decoy indicator `Reverse` uses `+` not boolean | Filter: `df['Reverse'] != '+'` |62| Spectronaut column names vary by export schema | Inspect actual columns |63| AlphaPept HDF5 requires key | Use `key='protein_table'` |64| Zero values may mean "not detected" | Treat 0 as NA before statistics |65| Decoy prefix is on protein ID, not sequence | Check `proteins`/`uniprot_ids` column |
MannLabs