Optional modes¶
Chimeric / co-isolated peptides (--chimeric, experimental)¶
With --chimeric (mzML or Thermo .raw), pass 1 is the normal search, keeping the same top-N
candidates per scan (--top-n, default 10); pass 2 takes the best one as the primary peptide,
finds co-isolated precursors in the MS1 isolation window and searches the residual spectrum for
a second peptide. Keeping the alternatives (rather than only the best candidate) took Astral from
60,435 to 66,405 PSMs and 26,717 to 29,400 peptides at an equal entrapment true FDP of 1%. On
phospho the alternatives first cost about 1% of peptides (15,084 → 14,904): most of them were the
same phosphopeptide with the phosphate on another site. The PIN now keeps one row per peptide and
modification multiset per precursor (see DOCS.md §3a), and phospho with --chimeric
reaches 39,470–39,592 PSMs and 15,107–15,156 peptides, above top-1 (39,404–39,489 / 15,046–15,084).
On UPS1 (with entrapment) PSMs at q ≤ 0.01 rose from 15,838 to 17,112 (+8.0%) with entrapment
hits flat (166 → 167). On high-res data --chimeric runs on the default out-of-core path with
fragment-ion retrieval. On Astral with an entrapment database (Percolator, three seeds), at an
equal 1% true FDP, it gives 60,403–60,435 PSMs against 43,076–43,145 without --chimeric
(+40%) and 57,003–57,054 with --chimeric on the former in-RAM candidate path. Distinct peptides stay flat
(26,432–26,454 vs 26,513–26,534): the second-peptide rows mostly re-identify peptides found
elsewhere, which deepens PSM counts rather than coverage. At nominal q ≤ 0.01 the true FDP is
1.18% (1.05% without --chimeric).
Secondary modifications (--refine, experimental)¶
--refine searches the spectra pass 1 missed against confident proteins with a fixed tier of
five chemistries (oxidation, deamidation, two pyro-Glu losses, protein N-terminal acetyl). It
does not discover new modifications and runs on high-resolution data only. On Astral it gives
40,028 PSMs (+4.3%), but its Pass-2 PSMs (IsRefinement = 1) sit at ~2.8% FDP under a
merged 1% threshold; threshold them separately for 1% on modified PSMs (DOCS.md).
Variant calls checked against knockoffs (--knockoffs, --proteoform-fdr)¶
Aim. A PSM on a UniProt variant entry claims that the sample carries that variant. Most false claims are not random matches. They are a canonical peptide that a common modification or an isotope error makes look like the variant: N→D and Q→E look like deamidation, G→A and D→E like methylation, and a one-isotope mis-pick fits a +1 Da substitution. Decoys model only random matches, so a decoy-based q-value does not see this error. Measured against donor genotypes, 65% of the variant PSMs accepted at a class q-value ≤ 0.01 were variants no donor carries, and 96% of the deamidation-like ones were. Knockoff variants give the variant claim a null that makes the same mistakes.
How it works.
1. Knockoff entries. Each single-residue variant X→Y of a canonical sequence, from
--uniprot-variants or --annotations, gets up to --knockoffs (default 4) knockoff entries. A knockoff is the same
substitution at another position of the same sequence that holds X, where:
- the next residue matches: the same residue when X is N, Q, K or R or either next residue is
P or G, otherwise the same residue class;
- the N-x-S/T sequon status is the same;
- the position lies in another enzymatic span whose length is within 3 residues of the real
one's and between 6 and 50;
- every variant UniProt lists for the protein is at least 10 residues away.
The positions are chosen at random but reproducibly, from the accession and the variant id.
A knockoff is almost certainly absent from the sample. A modification or an isotope error that
mimics the real substitution mimics the knockoff equally well. Knockoffs are variant entries:
they get decoys, PIN flags and Percolator scores exactly like real variants
(sp|P04637_KO1_D21H_VAR_005851_D7H|P53_HUMAN moves VAR_005851_D7H to position 21).
2. Knockoff q-value. After Percolator and the class FDR, variant-class PSMs are split by
substitution class (deamidation-like, methyl-like, oxidation-like, other). Within a class, the
knockoff PSMs above a score estimate how many real variant PSMs above it are false. A knockoff
PSM counts 1/k for a variant with k knockoffs, and the estimate starts at 1/K for a finite-sample
margin, with K the most knockoffs any variant has:
FDP(t) = (1/K + Σ 1/k over knockoff PSMs ≥ t) / (real PSMs ≥ t whose variant has knockoffs)
A real PSM's knockoff q-value is the smallest FDP over the thresholds at or below its score. Its
reported q-value is the largest of the global, class and knockoff q-values.
With claims from several sources, each substitution class is split further by prior tier
(sample, common, curated, catalogue; see
DOCS.md §1a), so a sample's own variants and
catalogue variants do not share one estimate.
3. Untested variants. A variant with no position that qualifies for a knockoff has no null, so
its PSMs are not accepted. Measured against genotypes, those variants are false several times
more often than the tested ones, so the tested variants' estimate cannot be lent to them.
4. Reporting. Variant-class PSMs (every protein a variant entry) are accepted at
--proteoform-fdr, every other PSM at --fdr. Knockoff PSMs stay in the PIN as targets; they
are left out of the QPX bundle. They are never in the filtered TSV, quantification, MBR or the
proteoform table, and knockoff accessions are dropped from other rows' protein lists.
Input and parameters. Variants from a UniProt XML database (--uniprot-variants) or from
annotation files (--annotations), and --rescore.
| Flag | Default | Effect |
|---|---|---|
--knockoffs |
4 |
Knockoffs per single-residue variant. 0 turns them off and leaves variant PSMs to the class FDR alone. |
--proteoform-fdr |
the larger of --fdr and 0.05 |
q-value cutoff for variant-class PSMs in the filtered TSV, the proteoform table and quantification. |
--uniprot-evidence |
experimental |
Minimum evidence for a variant to be searched (curated was used below). |
The run log gives, per substitution class, the knockoff entries made, the variant PSMs accepted before and after the knockoff q-values, how many were tested, and the estimated false share:
UniProt XML: 39142 knockoff variant entries (44773 single-residue variants with no position for a knockoff)
Rescore: variant PSMs at q<=0.05 per substitution class, before -> after knockoff q-values:
deamidation-like 1201 -> 0 (147 tested; knockoffs 150.6, false share 1.02), methyl-like 212 -> 89 ...
andes --spectrum run1.mzML --spectrum run2.mzML --database uniprot_sprot_human.xml.gz \
--uniprot-variants --uniprot-evidence curated --rescore --output-pin variants.pin
Current benchmark.
Genotype truth. PXD022787 (four donors, one TMT10 set, 69 runs, ion-trap MS2) was searched against reviewed human UniProt with curated variants. The donor-haplotype tags of the personal protein FASTA deposited with the dataset label each reported variant as carried or absent. The true FDP below counts the labelled PSMs whose variant no donor haplotype carries:
| Setting | Variant PSMs reported | Absent / labelled | True FDP | Variants reported (true FDP) |
|---|---|---|---|---|
| No knockoffs, class q ≤ 0.01 | 2,452 | 1,075 / 1,653 | 65% | 552 (33%) |
| No knockoffs, class q ≤ 0.05 | 3,886 | 1,872 / 2,622 | 71% | 840 (45%) |
Knockoffs, --proteoform-fdr 0.05 |
201 | 4 / 160 | 2.5% | 83 (3.4%) |
Knockoffs, --proteoform-fdr 0.10 |
307 | 14 / 233 | 6.0% | 126 (8.2%) |
Only 0.55% of the knockoffs turned out to be a real donor variant, so the null is clean.
Prior tiers. The same EN-TEx runs were searched against a FASTA of reviewed human UniProt plus
an annotation file holding UniProt's 83,472 single-residue variants. In one arm, the variants a
donor carries were given a sample genotype (tier sample), as a sample's own variant calls
would be. In the other, every variant was in one tier. At --proteoform-fdr 0.05:
| Setting | Carried variant PSMs (variants) | Donor-absent PSMs (variants) | True FDP, PSMs | True FDP, variants |
|---|---|---|---|---|
| One tier | 218 (83) | 13 (7) | 5.6% | 7.8% |
| Tiers split | 329 (122) | 8 (3) | 2.4% | 2.4% |
Separate tiers recover half again as many carried variants and stay below the 5% target, which
one shared tier does not. A variant peptide that a reference protein holds once I and L are taken
as equal (for example a V→L variant spelling a paralog's …VIDEVR as …VLDEVR) is reported for
that reference, not as the variant. Without that step, one such tubulin peptide alone gave 42
false variant PSMs here.
Cost on the rest of the search. Knockoffs grow the variant entries by about 60%. PSMs at
q ≤ 0.01 change by −0.43% on pooled Astral DDA (PXD070049, 21 runs: 1,003,367 → 999,103) and by
−0.30% on the TMT set. Search time is unchanged. On the Astral set, 129 variant-class PSMs are
reported at --proteoform-fdr 0.05.
Limits. - About 30% of single-residue variants can be given a knockoff, so most variants are not reported. - Multi-residue variants, indels, isoform-borne variants, isoforms and mature chains get no knockoffs. Variant-class PSMs of those are not accepted while knockoffs are on; isoform and chain PSMs keep the class FDR. - The calibration is measured on one genotyped dataset with low-resolution MS2. Small counts make the deamidation- and oxidation-like classes the least certain.
Intact N-glycopeptide search (--glyco, experimental)¶
--glyco identifies the backbone and the glycan composition from one MS2 scan.
andes --spectrum sample.mzML \
--database proteins.fasta \
--decoy-strategy sequon \
--glyco --glyco-species human \
--output-pin results.pin
- A glycan database is required:
--glyco-species(human,mouse,mouse-large,high-mannose) or your own.gdbwith--glyco-glycan-gdb. - Output is only
results.glyco.pin;--output-tsv,--output-parquet,--rescoreand--refineare rejected. Run Percolator on it with--trainFDR 0.05. - Use
--decoy-strategy sequon; the other generated decoys carry fewer sequons than their targets, which makes q-values anti-conservative. - Search each fraction separately, concatenate the
.glyco.pinfiles (one header) and run Percolator once: one fraction has too few decoys for a stable 1%. - HCD/CID and ETD/EThcD/AI-ETD are supported; c/z fragments localize the glycosite. The site is
reported as
@N<pos>only for a single N-X-S/T sequon, otherwise@N?.
On one mouse-liver fraction (PXD005553) andes reports 6,992–7,072 glycoPSMs at 1% at
0.61–1.35% true FDP (three peptide-level entrapment databases × three seeds, 2026-10-23),
confirming 88.2–88.4% of the depositors' (pGlyco2) and 89.3–89.7% of a reanalysis's
(MSFragger-Glyco) identifications, in about 6 minutes and 5.6 GB on 8 threads (docs/benchmarks/).
--glyco-peptide-first finds ~2% more at ~13x the run time.
Memory: --glyco runs on the out-of-core candidate index and holds in memory only the
candidates that carry an N-X-S/T sequon (3.2 of 28.0 million on the mouse fraction above), so
that run peaks at 4.5 GB with output identical to the former in-RAM path (20.0 GB). All flags:
DOCS.md §9.
Reading Thermo .raw files¶
Pass --spectrum sample.raw. Output is identical to the equivalent mzML (checked scan-for-scan
on a 2.4 GB Orbitrap Astral run). Release archives (macOS x64/arm64, Windows x64, Linux x64)
bundle a .NET 8 runtime. From source, install the
.NET 8 runtime and build with rustc ≥ 1.88:
RUSTUP_TOOLCHAIN=stable cargo build --release -p andes --features thermo.
andes uses a bundled dotnet/ next to the binary, else DOTNET_ROOT or a system install;
containers can start from mcr.microsoft.com/dotnet/runtime:8.0. RawFileReader is under
Thermo's license (crates/input/THERMO_LICENSE.txt).
Reading Bruker timsTOF .d files¶
Pass --spectrum sample.d (a directory). The pure-Rust
timsrust reader needs no vendor runtime; build with
--features timstof (rustc ≥ 1.88):
cargo build --release -p andes --features timstof
andes --spectrum sample.d --database human.fasta --output-pin out.pin
Scope: DDA-PASEF, MS2 only; ion mobility is not scored; --chimeric and --precursor-cal
fall back to a normal search.