Fix ProForma charge_state#203
Conversation
|
Thank you! Looking at the example from the tests, I have a question: In [1]: from pyteomics.proforma import *
In [2]: seq = ProForma.parse("SEQUEN[Formula:Zn1:z+2]CE")
In [4]: seq.charge_state
Out[4]: ChargeState(2, [Adduct(name='H', charge=1, count=2)])Is the adduct name |
|
The specification isn't explicit here, looping in @douweschulte. For context, this changeset adds a number of protons proportional to the positive charge of a charged modification, and the question is, shouldn't it just treat the modification as the adduct. I don't think what I have is correct either after going back and doing some side-by-side comparisons. Quoting the spec at this time, from section 11.1
We can rewrite the example peptide Additionally, this strategy does not work when you have something that already has an unpaired hydrogen already baked into it like some acidic compounds. The one I'll use is actually the monosaccharide If we were to neutralize the formula and then specify the charge separately, I think we get from pyteomics import proforma, massprop = proforma.ProForma.parse("SEQUEN[Formula:Zn1:z+2]CE")prop.charge_stateadducted = proforma.ProForma.parse("SEQUENCE/[Zn:z+2]")adducted.massprop.massprop.mass - mass.Composition("Zn").mass()adducted.mz(), adducted.massneut = proforma.ProForma.parse("SEQUEN[Formula:Zn1H-2]CE/2")neut.mz(), neut.massprop.mass, adducted.mass + adducted.charge_state.for_mz_calculation()[0], neut.massprop.mz(), adducted.mz(), neut.mz()What's the right answer? I'm not sure yet. I'll think more about this after I get home. |
To me this reads that implicit protons should not be added to the charged formula. Indeed, there doesn't seem to be a way to tell the charged part of the formula, so the only thing to do seems to be to designate it all as the adduct. |
def neutral_mass(mz, z, charge_carrier=PROTON):
return (mz * abs(z)) - (z * charge_carrier)
def mass_charge_ratio(neutral_mass, z, charge_carrier=PROTON):
return (neutral_mass + (z * charge_carrier)) / abs(z)The equivalent modification is I think I am taking a shortcut during the neutral mass calculation because the proton mass constant already factors in the loss of an electron. Iff a charged formula is not supposed to be part of the neutral mass of the peptidoform, then it'd be rolled into the adduct and this'd be fine. If it were, which was what I had in mind when I suggested this feature a few years ago, then it doesn't make sense to have its mass differ from the neutralized version (subtract an equal number of protons). This part is where I think the spec might be imprecise, @douweschulte. If we follow the same logic here, I think that implies you must subtract the protons from the formula, and then add them back in as adducts OR include the lost protons as part of the charged formula, though these might be implementation details of how I built this in |
|
Something in this reasoning still evades me, to be honest. My understanding is that the |
|
Some more comments in no particular order:
|
|
What I had in mind when working on this, but note that I do not have extensive experience in seeing this in actual spectra, is that the localised charge sets the charge of the formula as specified. So In my own codebase I have not really figured out the exact semantics of neutral mass when these localised charges are present but for now I just return the entire thing without the global charge carriers (so including the localised charges) but this might be something that needs further deliberation. I follow your logic Joshua that the charged zinc should bind the amino acid replacing two hydrogens that then form two protons, I am unsure if this is true in the general case, but if it is we could adopt this as the standard way of calculating neutral masses and maybe add it to the spec. On your second comment Lev on the combination of local and global charges, we did define the global charge carrier definition to be independent of local charges. So a peptide On your fourth comment Lev, if a peptide indeed has a charge state of |
|
I comment regarding protonation/deprotonation and localized charges. In the end, it all boils down to which specific molecular structure is implied. For example, What molecular structure is implied for
The first case is likely the more natural to infer, since it is similar to PTM, i.e., the ion (defined as PTM bearing a fixed charge) "modifies" a specific amino acid. Note, however, that in many cases (including the case in question), the localization to a single amino acid is chemically unlikely - the modification "sits" on multiple positions - the charge is not really localized. Furthermore, the definition of neutral mass is also challenging. Strictly speaking, neutral mass will be the mass of the peptide itself - no charge carrier. The latter is not very useful for spectral annotation, however. If one considers the mass of the ion, i.e., The second case involves peptide deprotonation; thus, the molecule's charge is +1. Similarly, after double deprotonation of side chains, it is possible to form a salt-bridge-like structure. Note, however, that the charge again won't be localized to a single residue, and the molecule itself is neutral (undetectable in a mass spectrometer). Which structure is implied? For me, it seems that the main issue here is that fixed charge notation is often ambiguous. It can be that charge localiztion details are out of the scope of Proforma and are better described by SMILES or similar notation, if necessary. |
|
Some chemical modifications introduce a fixed charge localized to a specific amino acid that does not involve any ion or charge carrier (for example, https://pmc.ncbi.nlm.nih.gov/articles/PMC13047680/ Scheme 1). The accurate mass of such a modification should be the elemental formula mass minus the mass of an electron. What would be the correct way to represent these kinds of modifications in ProForma? |
|
Thank you @caetera, I didn't know to think of these different configurations. This idea was derived from the various metallic cation modifications in Unimod (https://www.unimod.org/modifications_list.php?a=search&value=1&SearchFor=Cation%3A&SearchOption=Contains&SearchField=). I spent a lot of time observing mixed protonated plus ammonium, sodium, iron, and calcium adducted peptidoforms at charges of 3-6+, but the total charge distribution of these precursor ions wasn't notably different from their purely protonated isoforms. Sometimes the cation adduct was detectable in product ions, some times not, on the same bond cleavage site, but the product ions with the cation on them tended to be higher charge state (self-citation: https://pubs.acs.org/doi/suppl/10.1021/acs.jproteome.0c00051/suppl_file/pr0c00051_si_001.pdf figure S2-d, but I could be over-analyzing this case). This idea might better be expressed via the small population of charged modifications in PSI-Mod like Unimod's cations are all effectively amino acid salts like https://github.com/HUPO-PSI/psi-mod-CV/blob/18013a3e6489b0e79ca9bd967bbd29334d372753/PSI-MOD.obo#L25760-L25779 now that I know to look for that word, which means I must apologize for calling them sloppy. ProForma started as a way to write down what you saw, with few semantics for what that translated to in terms of mass or m/z. If you observe a delta mass addition at a position, and you know from context that it is charged, and given the delta mass you believe it is a particular chemical composition, then writing the charged formula is reasonable. Because ProForma was originally meant to describe proteoforms, it's within scope to think about an intact protein where there are a lot of charges randomly assorting around the structure but some having higher affinity to a region, so their being "localizable" based upon observation across one or more spectra would make writing down a tagged region My thought process for implementation was naively just your first case, charged ion + "neutral" peptide. Since the salt explanation invalidates my belief in |
|
Hi Joshua, What do we need to do to arrive at a satisfactory implementation, and can I help with anything? I am open to leaving |
|
I'll synthesize the solution over the weekend. Thank you for tolerating the
discussion.
…On Fri, May 22, 2026, 8:05 AM Lev Levitsky ***@***.***> wrote:
*levitsky* left a comment (levitsky/pyteomics#203)
<#203 (comment)>
Hi Joshua,
What do we need to do to arrive at a satisfactory implementation, and can
I help with anything?
On the one hand, I get questions from users about release timeline, and on
the other, I have time to work on this until the end of next week, when I
go on vacation. Do you think it would be possible to have this finalized by
then?
I am open to leaving fragments for after the release, for example, and
just raising a warning there when localized charges or adducts are present.
—
Reply to this email directly, view it on GitHub
<#203 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAK4E6I4MCUOA3J5I6JUBHL44A7BFAVCNFSM6AAAAACYSETPRKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DKMJYGQ4DSMZXGI>
.
Triage notifications on the go with GitHub Mobile for iOS
<https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675>
or Android
<https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.
You are receiving this because you authored the thread.Message ID:
***@***.***>
|
…ion 11.5 of spec. Accept the assumption that charged formulae are part of the total mass of the ProForma peptide
|
I made two relatively large changes after accepting that for most users, a modification would be expected to be part of the peptide sequence, unlike the adduct. This is consistent with the discussion, and the notion that there are charged modifications in PSI-MOD. Again, thank you for the helpful discussion. Because we aren't trying to model a "distributed" charge, just mark a position, we don't need to make a change to The first was to update the handling of adducts and numerical charge states to match the wording in section 11.5. This required a small change to the parser, allowed the The second thing was to try to fix more (but not all) API compatibility issues that might appear after upgrading. Previously, |
|
Thank you! So the charged formula modifications now contribute to the charge state, but without an adduct: In [44]: seq = ProForma.parse("SEQUEN[Formula:Zn1:z+2]CE")
In [45]: seq.charge_state
Out[45]: ChargeState(2, None)What should it mean exactly? Right now it's hard to tell because there is no way to calculate m/z for a ProForma with this charge state, as I see that There was also a problem with m/z calculation for other ProForma sequences, where the protons were added twice. I tried to fix that. |
|
Thank you. I found another issue with compounding charge states as well, but that has been addressed. The tests I had written in my development notebook are now part of the unit tests as I should have made them in the first place. This module is complicated enough I should also have been testing with coverage reporting enabled too. I'll spend some time plugging those holes after this release. My intent is that charged formulae be treated like normal modifications for mass calculation and are indistinguishable from adducts for m/z calculation. This should now work and is tested explicitly. |
|
Thank you again. There is a lot of room for surprise with localized charges still, like: In [16]: seq = ProForma.parse("SEQUEN[Formula:Zn1:z+2]CE")
In [17]: seq.mz()
Out[17]: 526.0813711039506
In [18]: seq.mz(charge=2)
Out[18]: 527.0886475561111I can see this is probably intended behavior, but adding two more protons to an already 2+ charged species should not result in this m/z. I am noting this but I don't know if there should be a warning of some sort, or some charge arithmetics needs to happen (i.e. add As for fragments, you mentioned that they don't need to be changed; this is not entirely clear to me. They are also only calculated as (de-)protonated ions now, even if the ProForma string describes something that should not contain any protons, like the example with Zn we are working with. Singly-charged, singly-protonated fragments are the default, but presumably we would see none of those m/z in the spectrum. For the given species, I guess 1+ fragments would have to be deprotonated? |
|
Issuing a warning is reasonable for both The |
|
Thank you for pushing this forward. I think with the warnings in place we can ship this and then maybe get more feedback, and we can and should still get back to this area. |
4 participants
Closes #202
This changeset introduces an at-parse-time verification of tags' charge contribution so that they can be added to the total charge state. This found, while verifying, that XLMOD's prefix was incorrectly registered and that it wasn't properly handling composition loss syntax there. I also removed some tests that were using RESID modifications, which we don't support.
This might have a wider result where if you were previously tokenizing an invalid modification, it now fails early rather than silently waiting for the modification tag to be queried later.
One place this doesn't work yet is when you modify the modifications, it doesn't automatically refresh the view of the local charge. This life cycle management might be needed in the future, adding a bit more storage to the
ProFormainstance.