Feature request: per-modification occurrence limits and a total variable-mod combination cap

[pgarrett-scripps]

Summary

Two opt-in controls on variable modification generation:

• Per-mod occurrence limits: cap how many times a single variable mod can appear on one peptide (e.g. "acetyl at most once"), independent of max_variable_mods.
• max_combinations: a hard cap on the total number of modified variants generated per peptide, preferring fewer-PTM forms.

Both default to off, so existing search behavior is unchanged.

Motivation

For PTM-heavy samples (histones especially), the variable-mod search space explodes combinatorially. max_variable_mods is the only current lever, but it's coarse. It can't express "allow up to 2 mods, but never two of the same mod on one peptide," and it can't bound the per-peptide variant count.

In practice, not all mods occur at the same frequency, so a single max_variable_mods lever is too coarse. Per-mod occurrence limits let the user say "this mod is rare, allow it at most once" while leaving common mods unrestricted, and max_combinations bounds the total variant count per peptide. This is especially important for histone data, where many residues are modifiable and the search space explodes combinatorially. Both are opt-in. MSFragger exposes similar controls.

Proposed config

variable_mods entries accept either a bare mass (unchanged) or a [mass, max_count] tuple, plus a new top-level max_combinations:

"database": {
  "variable_mods": {
    "M": [15.9949],
    "K": [[42.0106, 1], 14.0157]
  },
  "max_variable_mods": 2,
  "max_combinations": 8
}

Acetyl on K is capped at one occurrence per peptide; methyl on K has no per-mod cap (still bounded by max_variable_mods); and no peptide produces more than 8 modified variants total.

I have a working implementation with unit tests and can open a PR if such a feature would be a useful addition.

[lazear]

I like it, I wonder if we should just change the format of the config to something like:

"database": {
  "variable_mods": {
    "M": [{"mass":  15.9949, "max_count": 1}],
  },
  "max_variable_mods": 2,
  "max_combinations": 8
}

Then if we want to add modifications with neutral losses/labile, etc should be easier to extend

[pgarrett-scripps]

Yeah, I think that's the way to go. Definitely much more extensible.

So would this new dict layout be optional (users would still be able to specify mods the previous way)?

I already have a branch with the mod limits implemented, so if the new format looks good I can update it to use this and open a PR.

---

Going off your neutral losses and labile mods suggestion, do you think this is an appropriate way to specify them? And I guess while adding these it might also be a good idea to add a naming parameter for specifying UNIMOD or PSIMOD names.

I'm happy to also look into adding the other features brought up, though they might need more discussion. If you'd rather tackle all or some of them yourself, that works too, just let me know.

The labile mods flag and mod name should be pretty straightforward additions. I imagine that neutral losses could introduce scoring issues, since peptides with mods containing losses would have more fragments than others. Sage's Poisson score should catch this, but I'm not sure if it'd be a problem for preliminary/hyperscore-based scoring, or how it'd affect b/y ion series calculation.
The losses might also cause issues with FDR, since some of the LDA inputs would be inflated by having more fragments to draw on, like longest b/y chain and other features like that. I know some search engines get around this by calculating FDR separately for the different distributions (like calculating FDR independently for tryptic/semi-tryptic peptides), or maybe adding an LDA feature specifying whether a peptide has neutral losses would be sufficient.

"database": {
    "static_mods": {
      # same dict as in variable_mods but no max_count param
      "C": {"mass":  57.0215, "neutral_losses": [5.0000], "labile": false, "name": Carbamidomethylation}
    },
  "variable_mods": {
    "M": [{"mass":  15.9949, "max_count": 1, "neutral_losses": [1.0087], "labile": true, "name": Oxidation}],
  },
  "max_variable_mods": 2,
  "max_combinations": 8
}