Combinatorial (search-engine-like) proteoform generation in ProForma

[levitsky]

cc @mobiusklein

I have a use case for generation of all versions of a peptidoform with and without variable modifications applied, same way as parser.peptidoforms does for modX. We touched on this briefly in #190. I was looking into the ProForma machinery to see if I can make use of the classes there. It appears that we would need to add a switch in ProteoformCombinator.generate() to do this, where instead of going over itertools.product(*position_choices) we would go over the product of all possible subsets of each item in position_choices item. Does it sound right?

Another question is the user-facing API for this. As far as I understand, the user can encode the rules into the sequence itself with something like '[Oxidation|Position:M]?PEMPTIMDE', and that would work for ProteoformCombinator (assuming we implement the new iteration logic). However, no clean way seems to exist to pass external variable_rules to the constructor. So if I have a list of unmodified sequences and a set of modification settings, I need to either slap an unlocalized_modifications list onto each ProForma object, or manually create the rules for ProteoformCombinator like this:

from pyteomics.proforma import (
    UnimodModification, ModificationRule, ModificationTarget,
    GeneratorModificationRuleDirective, ProteoformCombinator, ProForma
)

oxidation = UnimodModification('35')
rule = ModificationRule(oxidation, ModificationTarget('M'))
directive = GeneratorModificationRuleDirective(rule)
sequence = ProForma.parse('PEMPTIMDE')
combinator = ProteoformCombinator(sequence)
combinator.variable_rules = [directive]

for pf in combinator.generate(all_combinations=True):  # not implemented yet
   print(pf)

Is it the case that there is no friendlier way to set up ProteoformCombinator ? Do you think we can create some reasonable shortcut?

Potential ideas would be:

• document a way to instantiate a rule from a string, like '[Oxidation|Position:M]', or just accept a mapping like parser.peptidoforms, creating the ModificationTarget and ModificationRule objects from keys and values;
• a way to pass a list[GeneratorModificationRuleDirective] to ProteoformCombinator constructor, or perhaps implicitly create them from ModificationRules;
• a way to reuse a ProteoformCombinator instance for multiple sequences, or maybe an alternative class that only applies external modification rules/directives. Alternatively, we can just have a user-facing function encapsulating the code above. Then it doesn't really matter if it's slightly longer or shorter, although it would be nice to avoid any repeated parsing or cache its results.

I can try to put together an implementation but I wanted to hear your thoughts.

On a related note, currently if you specify Position for an unlocalized modification, ProteoformCombinator places this modification on possible sites and it still has the same Position modifier there. Is this desirable?

[mobiusklein]

On a related note, currently if you specify Position for an unlocalized modification, ProteoformCombinator places this modification on possible sites and it still has the same Position modifier there. Is this desirable?

I didn't think about that. I am inclined to save myself some effort and declare that a feature, not a bug, since it lets you trace where that modification came from. It is relatively straight-forwards to strip out if it is an eye sore, just strip all the TagTypeEnum.position_modifier tags from the list of tags at each position.

As to the main topic here, this is probably easy enough to do, it'd just be a matter of wiring up the machinery to preprocess the input. Additionally, there's probably room for optimization to eventually avoid re-parsing the rules on each peptide, but that's worth optimizing when it becomes an issue.

def _coerce_string_to_modification(item) -> TagBase:
    if isinstance(item, TagBase):
        return item.copy()
    elif isinstance(item, str):
        return TagParser(item)()[0]
    else:
        raise TypeError(f"Don't know how to coerce {item} of type {type(item)} to a modification")


def modify_with(peptide: ProForma,
                variable_modifications: Optional[Union[List[TagBase], dict[str, TagBase]]] = None,
                fixed_modifications: Optional[Union[List[TagBase], dict[str, TagBase]]] = None,
                include_unmodified: bool = True, include_labile: bool = False):
    template = peptide.copy()
    if variable_modifications:
        if isinstance(variable_modifications, list):
            template.unlocalized_modifications.extend(map(_coerce_string_to_modification, variable_modifications))
        elif isinstance(variable_modifications, dict):
            extra_rules = []
            for target, tag in variable_modifications.items():
                if isinstance(target, str):
                    target = PositionModifierTag(target)
                tag = _coerce_string_to_modification(tag)
                tag.extra.append(target)
                extra_rules.append(tag)
            template.unlocalized_modifications.extend(extra_rules)
        else:
            raise TypeError(f"Expected variable_modifications to be a list or a dict, got {type(variable_modifications)}")
    if fixed_modifications:
        if isinstance(fixed_modifications, list):
            template.fixed_modifications.extend(map(_coerce_string_to_modification, fixed_modifications))
        elif isinstance(fixed_modifications, dict):
            extra_rules = []
            for target, tag in fixed_modifications.items():
                if isinstance(target, str):
                    target = PositionModifierTag(target)
                tag = _coerce_string_to_modification(tag)
                tag.extra.append(target)
                extra_rules.append(tag)
            template.fixed_modifications.extend(extra_rules)
        else:
            raise TypeError(
                f"Expected fixed_modifications to be a list or a dict, got {type(fixed_modifications)}"
            )

    return template.generate_proteoforms(include_unmodified=include_unmodified, include_labile=include_labile)

And some usage:

isos = list(proforma.modify_with(
    ProForma.parse("EMEVTESPEK"),
    variable_modifications=[proforma.GenericModification("Oxidation")]
))

for i in isos:
    print(i)

EMEVTESPEK
E[Oxidation]MEVTESPEK
EM[Oxidation]EVTESPEK
EME[Oxidation]VTESPEK
EMEV[Oxidation]TESPEK
EMEVT[Oxidation]ESPEK
EMEVTE[Oxidation]SPEK
EMEVTES[Oxidation]PEK
EMEVTESP[Oxidation]EK
EMEVTESPE[Oxidation]K
EMEVTESPEK[Oxidation]

isos = list(proforma.modify_with(
    ProForma.parse("EMEVTESPEK"),
    variable_modifications={"M": "Oxidation"}
))

for i in isos:
    print(i)

EMEVTESPEK
EM[Oxidation|Position:M]EVTESPEK

isos = list(proforma.modify_with(
    ProForma.parse("EMEVTESPEK"),
    variable_modifications=["Oxidation|Position:M"]
))

for i in isos:
    print(i)

EMEVTESPEK
EM[Oxidation|Position:M]EVTESPEK

[levitsky]

Thank you for writing this! This is very helpful as a starting point. I would probably flip keys and values in the dict input to allow for different modifications occurring on the same amino acids, but otherwise this looks great.

We would still need to update the guts of ProteformCombinator to make it exhaustively go over all isoforms, but I can give it a try.

[mobiusklein]

Oh good catch. I have a small changeset that I'll open a PR with to start with.

…

On Wed, Mar 11, 2026 at 5:29 PM Lev Levitsky ***@***.***> wrote: *levitsky* left a comment (levitsky/pyteomics#194) <#194 (comment)> Thank you for writing this! This is very helpful as a starting point. I would probably flip keys and values in the dict input to allow for different modifications occurring on the same amino acids, but otherwise this looks great. We would still need to update the guts of ProteformCombinator to make it exhaustively go over all isoforms, but I can give it a try. — Reply to this email directly, view it on GitHub <#194 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAK4E6J4V6GHBIKKUDZDCRL4QHLDPAVCNFSM6AAAAACWL7B7UWVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DANBSGMZTEMJZG4> . You are receiving this because you were mentioned.Message ID: ***@***.***>