feat(mzid): DirectPinWriter + -outputFormat 3 (pin) (Q7)

[ypriverol]

Summary

Emits a Percolator .pin file directly from the in-memory result list, bypassing the separate msgf2pin converter. Closes one of the long-standing MS²Rescore / Percolator integration gaps in the landscape review (Q7 in .claude/investigations/msgfplus_research_report.md §0, and §5 Priority 3).

Invocation

java -Xmx8G -jar MSGFPlus.jar -s spectra.mzML -d db.fasta -outputFormat 3 ...

Output path is the same as the mzid but with .pin extension. All other search flags behave identically.

Column layout

SpecId  Label  ScanNr  ExpMass  CalcMass
RawScore  DeNovoScore  lnSpecEValue  lnEValue  IsotopeError
PepLen  dM  absdM
Charge{min..max}           (one-hot over the search's charge range)
NumMatchedMainIons  ExplainedIonCurrentRatio  NTermIonCurrentRatio
CTermIonCurrentRatio  MS2IonCurrent  IsolationWindowEfficiency
MeanErrorTop7  StdevErrorTop7  MeanRelErrorTop7  StdevRelErrorTop7
Peptide  Proteins

• Label: +1 when any target protein matches, -1 when every match is a decoy — Percolator uses -1 rows as the null distribution, so we emit them rather than drop them.
• Peptide: Percolator's pre.PEPTIDE.post flanking format with inline mod masses (+nnn.mmm / -nnn.mmm) matching MS-GF+'s TSV output.
• Proteins: tab-separated after Peptide, so Percolator's "read all remaining columns" rule works as-is.
• Additional-feature columns are zero-filled when -addFeatures 1 is off, so the column count stays stable across runs.

Touched

• DirectPinWriter.java (new, ~353 lines) — writer + peptide formatter duplicated from DirectTSVWriter (extracting a shared PeptideFormatter is a clean follow-up; kept verbatim here so review is self-contained).
• ParamManager.java — registers pin as enum index 3 on -outputFormat.
• SearchParams.java — new writePin() getter.
• MSGFPlus.java — wire call site in runMSGFPlus next to the existing writeTsv / writeMzid blocks.

Test plan

• mvn -B verify — 145 tests pass (was 141 on dev; +4 new Q7 cases).
• TestDirectPinWriter covers flag acceptance, the writePin getter's flip behaviour, index stability vs pre-existing enum entries (mzid/tsv/both/pin = 0/1/2/3), and header shape (verifying all Percolator-required column names appear).
• No behaviour change for existing -outputFormat 0/1/2 users — the new enum entry is appended at the end, no existing index shifted.

Not in this PR

• Q6 (Pr(G|P) / Pr(G|O) as separate columns) — deliberately deferred; requires decomposing the log-ratio score on the hot path (2-3 day effort with PSM@1%FDR parity risk after the PRs perf(msgf): CSR graph + streaming GF merge + drop Hashtable sync #15/perf(scorer): precompute log scores in NewRankScorer #16/feat: -minSpectraPerThread flag, MSGFLogger, and run-manifest sidecar (Q9/Q11/Q4) #18 perf stack).
• Q10 (-Xmx vs FASTA pre-flight warning) — queued behind PR feat: -minSpectraPerThread flag, MSGFLogger, and run-manifest sidecar (Q9/Q11/Q4) #18's MSGFLogger.
• Refactor formatPeptideWithMods into a shared PeptideFormatter used by both DirectTSVWriter and DirectPinWriter — clean follow-up.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a004741c-0b53-444c-8144-852ce57c828b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/direct-pin-writer

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}