Intenenal ions squared

[trishorts]

Summary

Adds internal fragment ion prediction and analysis to mzLib. Internal fragments arise from two simultaneous backbone cleavages, producing an ion that contains neither terminus of the peptide (annotated here as bIb[start-end]+charge, e.g. bIb[3-7]+1 spans residues 3–7). Standard prediction models (Prosit, ms2pip, …) only model the terminal b/y series; this PR contributes the internal series so a predicted spectral library can include both.

The work has three independent pieces:

1. InternalFragmentIntensityModel — a local ONNX model that predicts internal-ion intensities.
2. MixedModels framework — merges a primary (Koina) model's b/y ions with the internal model's ions into one LibrarySpectrum per peptide.
3. InternalIons analysis pipeline — post-search extraction of observed internal ions from PSMs, with feature engineering and TSV output (used to train/validate the model).

---

1. InternalFragmentIntensityModel (local ONNX)

PredictionClients/LocalModels/InternalFragmentIntensityModel.cs + shipped model InternalFragmentScorer_v3_AllProteases.onnx.

Predicts TIC-normalized intensity (TicNI) for internal-fragment candidates of length 3–9. It is protease-agnostic (trained on LysC, Trypsin, ArgC, GluC, AspN, Chymotrypsin) and NCE-agnostic (collision energy is not an explicit input). The model scores 18 engineered features per candidate (fragment length, basic-residue counts, terminal-ion support, proline/aspartate flags, hydrophobicity, etc.), keeps the top N per peptide (default 20), and normalizes intensities to max = 1.0. Each surviving ion becomes a Product with SecondaryProductType/SecondaryFragmentNumber set, which is how mzLib marks an ion as internal (MatchedFragmentIon.IsInternalFragment == true).

using PredictionClients.LocalModels;

var peptides = new List<string> { "PEPTIDEK", "ELVISLIVESK" };
var charges  = new List<int>    { 2, 2 };
var rts      = new List<double?>{ 30.1, 42.5 };

// onnxModelPath is resolved automatically next to the assembly if omitted
var model = new InternalFragmentIntensityModel(
    peptides, charges, rts, out var warnings,
    minIntensityFilter: 0.002,
    maxInternalIonsPerPeptide: 20);

await model.RunInferenceAsync();          // single-shot; disposes itself afterward
var spectra = model.PredictedSpectra;     // List<LibrarySpectrum>, internal ions only

Pass spectralLibrarySavePath: to also write the library to an MSP file.

---

2. MixedModels — combine primary + internal ions

PredictionClients/MixedModels/ (CombinedLibraryModel, PrimaryIntensityComponent / InternalIntensityComponent, LibrarySpectrumMerger, MixedModelResult, IMixedModelComponent).

CombinedLibraryModel runs each component in parallel and unions their fragment ions per peptide (keyed by sequence/charge), so the merged spectrum carries both b/y and internal ions. A failing component (e.g. a Koina outage) is captured rather than aborting the run, so you still get an internal-only library.

using PredictionClients.MixedModels;
using PredictionClients.Koina.SupportedModels.FragmentIntensityModels;

var internalModel = new InternalFragmentIntensityModel(peptides, charges, rts, out _);
var primaryModel  = new Prosit2020IntensityHCD();   // any Koina FragmentIntensityModel

var combined = CombinedLibraryModel.WithPrimaryAndInternalFragments(
    primaryModel, internalModel,
    collisionEnergy: 30,                        // passed to the primary model
    spectralLibrarySavePath: "combined.msp");   // optional

var warning  = await combined.RunAsync();
var spectra  = combined.PredictedSpectra;       // primary b/y + internal ions, merged

The factory derives the primary model's inputs and aligned retention times from the internal model (both operate on the same peptide set). For full control, construct the component list directly via the general CombinedLibraryModel(IReadOnlyList<IMixedModelComponent>, …) constructor.

---

3. InternalIons analysis pipeline (observed ions)

Readers/InternalIons/ (InternalFragmentIon, InternalFragmentFeatureExtractor, InternalFragmentAnalysisRunner, InternalFragmentTsvWriter). Independent of the Koina/prediction code.

Given a search result and the raw files, it extracts the internal fragments that were actually matched, computes the same 18 features the model uses, and writes a TSV — the data behind training/validating the ONNX model.

using Readers.InternalIons;

var ions = InternalFragmentAnalysisRunner.Run(
    psmTsvPath:       @"…\AllPSMs.psmtsv",
    rawFileFolder:    @"…\rawfiles",
    outputDirectory:  @"…\out");          // writes InternalFragmentIons.tsv

---

Notes

• This branch was merged up to current master and the prediction/MixedModels code was re-ported onto the rewritten Koina FragmentIntensityModel API (Predict(inputs) + GenerateLibrarySpectraFromPredictions(alignedRetentionTimes, …)); behavior is preserved.
• The internal-ion MSP round-trip is supported by the additions to LibrarySpectrum and SpectralLibrary.ReadFragmentIon (parses/writes bIb[start-end] annotations).
• Live-Koina and machine-specific evaluation tests are categorized/[Explicit] and excluded from normal runs.

[codecov]

Codecov Report

❌ Patch coverage is 39.23648% with 573 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.39%. Comparing base (92be818) to head (b3bf111).

⚠️ Current head b3bf111 differs from pull request most recent head f03ec80

Please upload reports for the commit f03ec80 to get more accurate results.

Files with missing lines	Patch %	Lines
...s/InternalIons/InternalFragmentFeatureExtractor.cs	0.00%	277 Missing ⚠️
mzLib/Readers/InternalIons/InternalIon.cs	0.00%	118 Missing ⚠️
.../Readers/InternalIons/InternalFragmentTsvWriter.cs	0.00%	79 Missing ⚠️
...ers/InternalIons/InternalFragmentAnalysisRunner.cs	0.00%	58 Missing ⚠️
...nts/LocalModels/InternalFragmentIntensityModel .cs	90.36%	26 Missing and 6 partials ⚠️
mzLib/Readers/SpectralLibrary/SpectralLibrary.cs	84.31%	5 Missing and 3 partials ⚠️
mzLib/Omics/SpectralLibrary/LibrarySpectrum.cs	96.42%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1022      +/-   ##
==========================================
- Coverage   81.63%   80.39%   -1.25%     
==========================================
  Files         369      302      -67     
  Lines       47605    42640    -4965     
  Branches     5649     4824     -825     
==========================================
- Hits        38863    34281    -4582     
+ Misses       7643     7512     -131     
+ Partials     1099      847     -252     

Files with missing lines	Coverage Δ
mzLib/Omics/SpectralLibrary/LibrarySpectrum.cs	95.55% <96.42%> (+1.49%)	⬆️
mzLib/Readers/SpectralLibrary/SpectralLibrary.cs	85.49% <84.31%> (+0.11%)	⬆️
...nts/LocalModels/InternalFragmentIntensityModel .cs	90.36% <90.36%> (ø)
...ers/InternalIons/InternalFragmentAnalysisRunner.cs	0.00% <0.00%> (ø)
.../Readers/InternalIons/InternalFragmentTsvWriter.cs	0.00% <0.00%> (ø)
mzLib/Readers/InternalIons/InternalIon.cs	0.00% <0.00%> (ø)
...s/InternalIons/InternalFragmentFeatureExtractor.cs	0.00% <0.00%> (ø)

... and 150 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.