proteomics-database-search-skill

name

proteomics-database-search-skill

description

Plan, run, resume, audit, and report proteomics database searches on Linux with FragPipe/MSFragger and compatible validation or quantification tools. Use for DDA or DIA, label-free or isobaric workflows, total proteome or PTM-enriched data, protein/peptide/PTM identification, targeted protein or residue checks, SSH/tmux execution, FASTA preparation, FDR review, quantification, and publication-ready tables, figures, and source-data packages. Includes PTM-specific branches without assuming any particular protein, gene, modification, organism, or sample design.

Run proteomics database search

Treat the user’s biological question, acquisition type, identification method, and quantification method as separate decisions. Never default to phosphorylation or to a specific target protein.

Classify the task

Establish the following before configuring a search:

1. Goal: global identification, protein quantification, peptide quantification, PTM discovery, PTM-site localization, spectral-library generation, or targeted confirmation.
2. Acquisition: DDA, DIA, PRM/SRM, or unknown.
3. Quantification: label-free, TMT/iTRAQ, SILAC/dimethyl, or identification only.
4. Material: total proteome, fractionated sample, affinity purification, PTM enrichment, immunopeptidome, or another preparation.
5. Chemistry: enzyme, fixed modifications, variable modifications, labeling reagents, and reduction/alkylation.
6. Instrument: vendor, model, fragmentation, mass analyzer, and resolution.
7. Search space: organism, FASTA source/date, isoforms, contaminants, decoys, and expected sequence variants.
8. Design: sample labels, biological groups, batches, replicates, and contrasts.

Do not infer biological groups from filenames. Grouping is not required for identification, but it is required for biological summaries and statistical contrasts.

Read references/workflow-selection.md before choosing a workflow. For phosphorylation or another PTM, also read references/ptm-workflows.md. For ubiquitin-remnant or palmitoylation/S-acylation experiments, additionally read references/ubiquitination-and-s-acylation.md; these chemistries are not interchangeable.

Create a run record

Before starting:

• record host, absolute project path, input count, file sizes, and free disk space;
• inventory files without moving or copying RAW data;
• record software versions and licenses without exposing license strings or tokens;
• record FASTA provenance and all search parameters;
• retain the exact workflow/configuration and logs;
• preserve completed searches and unrelated user files.

Never store credentials, SSH keys, proxy secrets, download tokens, or commercial license strings in the skill, project logs, or shared result package.

Select and configure the workflow

Use the current built-in workflow closest to the acquisition and study design, then verify every parameter.

Input	Starting workflow
DDA, label-free total proteome	FragPipe DDA LFQ
DDA, identification only	FragPipe DDA identification
DDA phospho-enriched	FragPipe DDA phospho plus PTMProphet and optional IonQuant
DDA ubiquitin-remnant enriched	FragPipe LFQ-ubiquitin or the matching isobaric ubiquitin workflow
DDA palmitoylation/S-acylation	Custom workflow matched to enrichment, derivatization, and fragmentation chemistry
DDA other PTM	Closed, mass-offset/labile, or open search according to PTM chemistry
DIA	MSFragger-DIA/DIA-NN-compatible workflow
TMT/iTRAQ	Isobaric workflow plus TMT-Integrator
SILAC/dimethyl	MS1-label workflow plus IonQuant
Targeted residue or peptide	Secondary targeted audit/search after the global FDR-controlled search

Verify:

• enzyme specificity, missed cleavages, peptide length, and charge range;
• fixed and variable modifications;
• precursor and fragment tolerances appropriate for the instrument;
• isotope-error handling;
• PSM rescoring and target-decoy filtering;
• protein inference;
• quantification and MBR settings;
• PTM localization or site-level reporting when applicable.

Avoid expanding variable modifications, missed cleavages, or enzyme rules solely to force a desired target. If a broader targeted search is justified, label it secondary and retain the global result as the primary inference.

Run remotely and preserve progress

Use SSH only on the host placed in scope. Run long jobs inside a named tmux session:

tmux new-session -d -s proteomics-search
tmux send-keys -t proteomics-search \
  'cd /absolute/project && COMMAND 2>&1 | tee logs/search.log' C-m
tmux capture-pane -pt proteomics-search -S -100

Report the tmux session and output path. A tmux session protects against SSH disconnection, not host power loss. After interruption, inspect logs and outputs before resuming or restarting.

Do not call a search complete until:

• the process exits successfully;
• all expected runs are represented;
• expected tables and logs exist;
• file timestamps and sizes are stable;
• the result passes the validation checks below.

Validate identification

Review separately:

• PSM FDR;
• peptide FDR;
• protein FDR and inference;
• decoys and contaminants;
• precursor and fragment mass errors;
• peptide length, charge, enzymatic termini, and missed cleavages;
• run-level identification yields and outliers;
• modification frequencies and localization when relevant.

A low PSM q-value supports the peptide-spectrum match. It does not by itself prove a PTM site, protein isoform, mutation, or biological contrast.

Validate quantification

Confirm:

• which level is quantified: ion, peptide, modified peptide, site, protein, or gene;
• normalization method;
• MBR or library-transfer contribution;
• missing-value rate by run and group;
• whether values are raw, normalized, log transformed, or row scaled;
• whether total-protein abundance is needed to interpret PTM abundance;
• whether the design supports inferential statistics.

MBR-only or transferred-library evidence can support quantification but is not the same as a direct MS/MS identification in that sample.

Audit a target protein, peptide, or residue

Determine the localization threshold before inspecting the target

For any site-localized PTM, make the threshold decision in this order:

1. define the reporting unit: PSM-site, peptidoform, unique protein site, or ambiguous site group;
2. use the FLR target required by the study protocol or journal; otherwise use estimated FLR <=1% for the primary conclusion-driving tier and <=5% only for a separately labelled exploratory tier;
3. derive the score/probability cutoff from the complete comparable dataset, after identification-FDR filtering, using a documented calibrated posterior, localization target-decoy/decoy-residue procedure, or matched ground truth;
4. apply the derived cutoff to the target only after it has been frozen;
5. if none of those FLR methods is valid for the data, retain exact scores and ambiguous site groups, label any workflow cutoff as operational, and do not call the resulting category error-controlled or high confidence.

The 1% and 5% values above are FLR targets, not localization-probability cutoffs. Never substitute a familiar probability such as 0.75 or 0.90. Record the calibration population, method, target FLR, derived cutoff, accepted count, estimated FLR, and threshold status in every site-level export. Follow the full decision procedure in references/ptm-workflows.md.

Use the generic audit script. The bundled scripts live beside this file, so invoke them through the skill's own directory rather than a path relative to the current working directory:

SKILL_DIR=/path/to/proteomics-database-search-skill

python3 "$SKILL_DIR"/scripts/audit_target_psms.py \
  --psm-root /path/to/results \
  --protein-id TARGET_ACCESSION \
  --residue 123 \
  --output-dir /path/to/audit

Filter by --gene or --peptide-regex when appropriate. The script produces a curated target-PSM table and per-sample summary without assuming a PTM.

For phosphorylation-specific site evidence, use:

python3 "$SKILL_DIR"/scripts/audit_phosphosites.py \
  --site-table /path/to/combined_site_STY_79.9663.tsv \
  --psm-root /path/to/results \
  --protein-id TARGET_ACCESSION \
  --gene TARGET_GENE \
  --target-flr 0.01 \
  --output-dir /path/to/audit

--target-flr derives the probability cutoff from all accepted phosphosite assignments under --psm-root, not from the requested target. Use --localization-threshold only when importing a justified cutoff from another validated FLR method or when an operational threshold must be reproduced; in that case also supply --threshold-status, record the basis, and supply the externally estimated FLR only for an error-controlled imported cutoff. An operational cutoff must not be reported as high confidence.

The script joins PSM evidence to the site table by matching each psm.tsv parent-directory name against the <sample> Localization Probability column prefixes. It fails when no name matches and warns on a partial match; resolve any reported mismatch before interpreting the output, because unmatched runs contribute PSM counts that cannot be assigned to a sample.

--reporting-unit selects the unit at which FLR is controlled: psm-site (default) or protein-site, which first collapses each unique site to its maximum residue probability. Match it to the unit of the list you publish. The protein-site collapse records its own caveat: selecting a maximum over repeated observations is optimistic and is not corrected for. A peptidoform or site-group list is a third unit that neither mode estimates; do not attach either FLR to it. See section 6.1 of references/ptm-workflows.md.

Review PTMs

For any PTM:

1. confirm the mass shift and allowed residues;
2. confirm whether sample preparation preserves the native PTM or replaces it with a tag/remnant;
3. separate protein enrichment, peptide identification, and modification localization;
4. inspect competing sites and localization distributions;
5. derive localization thresholds from the full comparable dataset at a predeclared FLR target; never choose a cutoff to recover the requested target;
6. report total site-assigned PSMs and thresholded localized PSMs, including the reporting unit, calibration population, FLR method, target, derived cutoff, and accepted count;
7. inspect representative spectra for site-determining ions;
8. distinguish direct evidence, ambiguous localization, transferred quantification, and absence;
9. use PTM-appropriate FDR, false-localization controls, and chemistry-specific negative controls when available.

Use phosphorylation-specific interpretation rules only for phosphorylation. Do not reuse an STY:79.9663 parser for acetylation, ubiquitination, glycosylation, oxidation, crosslinks, or sequence variants.

Report results

Read references/evidence-and-reporting.md before interpreting or exporting evidence. Read references/publication-output-standard.md before creating a final package, supplementary tables, or figures.

At minimum preserve:

• sample metadata;
• identification summaries;
• protein/peptide/PSM evidence tables;
• modification or site tables when applicable;
• quantification tables at the level being interpreted;
• figure source data;
• software versions, FASTA provenance, parameters, and logs;
• QC-only rejected candidates when a requested target is not confirmed.

Generate figures from versioned source-data tables rather than directly from intermediate search files. Every figure panel must have a machine-readable source table containing the plotted values, sample identifiers, transformations, missing-value status, and evidence class.

Do not show p-values or significance stars until the contrast, normalization, filtering, missing-value policy, and statistical model are specified.

Safety and completion

• Never delete RAW data.
• Never upload RAW data unless explicitly requested.
• Never overwrite a completed result without preserving or explicitly replacing it.
• Never expose licenses, tokens, credentials, or private download URLs.
• Never claim a protein, peptide, PTM, site, or differential result from a score that does not control the relevant error.
• Verify archives exclude RAW, mzML, proprietary result containers, credentials, and licenses.
• Verify local and remote hashes after transfer.
• Return exact output paths, run status, software versions, evidence limitations, and unresolved decisions.