Skip to content

Quick start

Quick Start

andes \
  --spectrum spectra.mzML \
  --database proteins.fasta \
  --output-pin out.pin

This runs a tryptic search with no configuration: for mzML, .raw and .d the model is chosen from the file metadata, and the precursor tolerance defaults to 20ppm. Feed out.pin to Percolator for q-values.

MGF has no instrument metadata. andes reads the fragment resolution from the peaks of the first 1,000 spectra (13C isotope pairs at 1.00335/z within 10 ppm, compared with chance) and selects the high-res HCD model when they show high resolution. When the peaks do not decide it assumes CID / low-res / 0.5 Da and warns. --fragmentation <CID\|ETD\|HCD\|UVPD> and --fragment-tol-ppm / --fragment-tol-da override the inference.

Each PIN row is one PSM. RankScore orders candidates within a spectrum; RawScore is the score Percolator weights most. All columns are in DOCS.md §3a. The final tolerances and a per-modification PSM tally go to stderr and <stem>.statistics.log (DOCS.md §3d).

Common workflows

Tryptic DDA + Percolator (default):

andes --spectrum spectra.mzML --database db.fasta --output-pin out.pin
docker run --rm -v $(pwd):/data biocontainers/percolator:v3.7.1_cv1 \
  percolator -X /data/weights.txt /data/out.pin

TMT 10-plex search with mods.txt (mods file format: DOCS.md §2):

andes \
  --spectrum tmt_spectra.mzML \
  --database hsapiens.fasta \
  --output-pin out.pin \
  --mods tmt_10plex_mods.txt \
  --protocol TMT

UniProt XML database. --database uniprot_sprot_human.xml.gz searches like the UniProt FASTA. It also offers opt-in uses of UniProt's annotation. A mod declared sites=annotated in the mods file is placed only where UniProt annotates that modification. --uniprot-variants searches natural sequence variants as their own entries, with the change in the accession. --uniprot-isoforms adds the described isoforms, and --uniprot-chains the peptides at the new termini of mature chains (after signal peptide or propeptide removal). Annotation is filtered by evidence (--uniprot-evidence); see DOCS.md §1a. With rescoring, variant calls are checked against knockoff variants (below).

andes --spectrum spectra.mzML --database uniprot_sprot_human.xml.gz \
  --mods phospho_annotated_mods.txt --uniprot-variants --output-pin out.pin

PEFF databases. --database x.peff reads a PSI Extended FASTA file. Its variant, modification and processing header keys become claims built like UniProt's (DOCS.md §1a).

Site claims (experimental). Annotated modification sites are checked against knockoff sites: the same modification on matched residues no annotation names. With rescoring, each site gets a site q-value and <stem>.sites.tsv lists the accepted ones. The estimate errs towards rejecting true claims; it is most useful with freely placed mods (DOCS.md §1a). Each site also gets its occupancy and the probability of each modification it may carry (acetyl 0.71, trimethyl 0.29), from the competing explanations of each spectrum, diagnostic ions and neutral losses (DOCS.md).

Annotation files. --annotations claims.annotations.parquet adds claims about the proteins of any database, FASTA included: sequence edits (variant entries), modification sites, mature chains. The claims can come from variant catalogues, a sample's own variant calls or site databases, one row per claim, with a checksum of the sequence each was written against. They are built into entries exactly like UniProt's own, so knockoffs, the class FDR and the proteoform table apply unchanged. The flag can be repeated, and equal claims are merged. The columns are listed in DOCS.md §1a.

andes --spectrum spectra.mzML --database human.fasta \
  --annotations cosmic.annotations.parquet --annotations sample.annotations.parquet \
  --rescore --output-pin out.pin

TSV and Parquet output:

# TSV for inspection; QPX .idparquet bundle for quantms
andes --spectrum spectra.mzML --database db.fasta \
  --output-pin out.pin --output-tsv out.tsv --output-parquet out.idparquet

In-process rescoring. --rescore runs Percolator (--percolator-bin, else percolator on $PATH, else the pinned Docker image). --rescore-native is a built-in cross-validated semi-supervised linear rescorer with target-decoy competition (Percolator's algorithm, as -Y), a fallback when Percolator is not available. Both add a q-value and PEP to the outputs and write <stem>.q<fdr>.tsv (targets at q ≤ --fdr, default 0.01, e.g. --rescore --fdr 0.01). --fdr and --pep do nothing without one of them.

Protein groups. Every rescored run also writes <stem>.protein_groups.tsv: protein groups by parsimony over protein families (a canonical entry with its isoform, variant and chain entries is one family), each with a protein q-value from picked target-decoy competition. --protein-fdr 0.01 keeps only PSMs of groups at that level in the filtered TSV, and only their families in the proteoform table; no quantification is needed (DOCS.md).

Quantification (--tmt, --lfq). andes quantifies the confident PSMs in the same run: --tmt tmt10 reads the reporter ions of every identified MS2 (or its SPS-MS3 with --tmt-level 3), applies the kit's impurity matrix (--tmt-correction) and reports the precursor isolation purity; --lfq integrates the isotope chromatograms of every identified precursor from the MS1 scans with an experimental decoy-based feature q-value estimate. Both write versioned Parquet tables (<stem>.tmt.parquet, <stem>.lfq.parquet) and, with --output-parquet, the QPX quantms.feature.parquet that quantms consumes. Normalization and protein roll-up stay downstream (DOCS.md §10). --lfq --mbr adds match between runs over two or more inputs: every confident precursor is measured in every run, and transfers carry an internal quant-quality q-value (<stem>.mbr.parquet). The same stages run one at a time with andes quant library|extract|finalize over a --quant-dir, for pipelines that spread runs over machines. On the ProteoBench label-free DDA modules (six runs each; measured 2026-10-23 at 2051616b with default settings), andes quantified 65,012 precursors in at least 3 runs on QExactive (PXD028735) at transfer q 0.01, with a median |ε| of 0.163 and a CV of 0.118 using quantity_normalized (71,243 at q 0.05; the default is 0.01; the raw quantity reads |ε| 0.228, CV 0.246). On the same module FragPipe 23.0 reports 63,701 at 0.200 / 0.156 and Sage 0.15.0-beta.2 81,933 at 0.388 / 0.393, without filtering transferred quantities. On Astral (PXD070049) andes quantified 37,352 at |ε| 0.193 and CV 0.113; FragPipe 23.0 reports 39,057 at 0.212 / 0.127, Sage 0.14.6 30,319 at 0.167 / 0.070 and DIA-NN 2.6.0 93,237 at 0.277 / 0.159. Leaderboard snapshot 2026-07-16, one andes seed. On a 500-run study (PXD042233) the per-run pipeline took 146 CPU hours end to end and quantified 243,895 precursors in at least 3 runs (benchmarks).

andes --spectrum tmt_run.mzML --database human.fasta --mods tmt10_mods.txt \
      --rescore --tmt tmt10 --tmt-correction lot.txt --output-parquet run.idparquet
andes --spectrum run1.mzML --spectrum run2.mzML --database human.fasta --rescore --lfq
andes --spectrum run1.mzML --spectrum run2.mzML --database human.fasta --rescore --lfq --mbr

quantms. Point the search step at andes. Use named flag values; legacy numeric values are rejected (DOCS.md §8).