Named PTMs support

[gritukan]

Hello!

The current way of specifying PTMs is Proforma-compatible but not the most verbose since requires downstream applications to guess the specific PTM from only mass. I propose to add a support for named PTMs similarly to other search engines. The proposed configuration is following:

{
    "max_variable_mods": 3,
    "static_mods": {
        "C": 57.0215 // This is how it works now; simplest and backward-compatible
    }
    "variable_mods": {
        "M": {
            "UNIMOD:35": 15.9949,  // Will be shown as "PEM[UNIMOD:35]AT in the output
            "Some unimod name": 42.0 // Unimod / PSI-MOD names are supported according to Proforma; output is "PEM[Some unimod name]AT"
        }
    }
}

If this plan looks good to you, I'd be happy to bring a pull request implementing it.

[lazear]

I have been wanting to do an overhaul of the modification system for a while, it's probably the worst part of Sage in terms of code quality / performance.

How would you plan to implement this?

[gritukan]

For now I mostly have the API above in mind. The overall structure of the code would remain largely unchanged: PTMs can optionally be assigned a label, and this label is then used when reporting PSMs. If a PTM does not have a label, its mass is reported instead.

That said, I'd be interested to hear your thoughts about this. What were your improvement plans?

As a side note, we will probably start working on a project involving open search and some weird modifications so I'm quite interested in this subsystem becoming better :)

[lazear]

Probably to rip off Comet's new modification approach: https://github.com/UWPR/Comet/blob/master/CometSearch/CometModificationsPermuter.cpp

Essentially (my understanding, at least) there are a fixed number of possible modification combinations for any given set of modifications and max_variable_mods.

For instance, if you allow M[+15], S[+79] as variable mods:

Mod 1	Mod 2	Mod 3
M[+15]	-	-
M[+15]	M[+15]	-
M[+15]	M[+15]	M[+15]
M[+15]	S[+79]	-
M[+15]	S[+79]	S[+79]

And so on. Assign each one a unique combination ID. You can then represent modified positions using a bitmap, so memory required for a modified peptide is now O(n + u64) instead of O(2n) (no longer using Vec<f32> to represent mods at each position). Some clever bit twiddling/lookup tables could be done to make generating modified peptides from unmodified peptides much faster too.

This involves a major refactor/rewrite of the codebase (due to Rust ownership/lifetime rules getting involved) and substantially increases the complexity of the code, which is why I haven't undertaken it yet. Up to this point, I have tried to largely keep the code as simple as possible / reduce amount of Rust-specific knowledge necessary in order to make it more 'hackable' and easier for others to contribute

[gritukan]

Thank you for the explanation!

I checked the PTM-related code in Sage, and it seems feasible to implement something like you described in two stages: first, switch from mass deltas to PTM ids, and then introduce Comet-like combinatorics as a separate step.

For the first stage, we could introduce a library-wide PTM registry that stores all PTMs defined in the configuration. Each PTM would include its mass and optionally a label used for ProForma serialization. This would change the peptide representation: instead of storing mass deltas at each position, we would store optional PTM indices.

At this point, memory usage per peptide could be reduced to approximately O(n + u64 * max_modifications_count) by keeping a bitmask of modified positions together with a list of modifications. Alternatively, we could represent modifications simply as a list of (position, ptm_id) pairs, which would further reduce memory usage.

For me it seems like that without optimization code will stay pretty simple and hackable while optimization may make things slightly more complex since O(1) access to the PTMs will be lost.

The second stage can be discussed separately, but one possible approach is to indeed introduce "multi-PTM" in the library, allowing a single index to represent multiple modification combinations.

One thing that is still unclear to me is how open modification search is implemented in Sage. When using a wide precursor mass window, do you introduce a ephemeral PTM corresponding to the precursor mass error, or do you match spectra against unmodified theoretical b/y ions directly?

[lazear]

One thing that is still unclear to me is how open modification search is implemented in Sage. When using a wide precursor mass window, do you introduce a ephemeral PTM corresponding to the precursor mass error, or do you match spectra against unmodified theoretical b/y ions directly?

Just matched against unmodified theoretical b/y ions directly. (see https://www.nature.com/articles/s41467-020-17921-y for an alternative & more sensitive approach)