Accessing query-level modification information

This section describes accessing and handling of query-level modifications in Mascot 2.5 and later results files. Query-level modifications were handled as part of the master variable modification list in Mascot 2.4 and earlier, so this information is only useful if you use query-level modifications in Mascot 2.5 or later. See also the section on backwards compatibility.

For simplicity, we will refer to variable modifications specified at search form level or in the quantitation method as form-level modifications, and variable modifications specified in an individual query as query-level or local modifications.

1. Extracting variable modifications of a match

Suppose the search has form-level modifications IT_MODS=Oxidation (M),Acetyl (N-term), and that there is a peptide match to query 1, which has the query-level modifications IT_MODS=Phospho (ST). The form-level modification numbers are 1=Oxidation (M) and 2=Acetyl (N-term), while the query-level modifications of query 1 have 1=Phospho (ST).

To find the modifications of the peptide match, fetch the peptide's variable mods string getVarModsStr() and the query-level mods string getLocalModsStr(). In this case, the variable mods string could be 20100000 and the query-level mods string 00001000. We can decode the strings in two steps:

Using each non-zero digit in the variable mods string 2010000, look up the modification name using ms_searchparams::getVarModsName(). We find the peptide is acetylated at the N-terminus and oxidised at the second residue.
Using each non-zero digit in the query-level mods string 00001000, look up the modification name using ms_inputquery::getLocalVarModName(). We find the peptide is phosphorylated at the fourth residue.

Points to note:

Query-level modification numbering is independent of both form-level modifications and other queries. That is, query-level modification numbers are 1-based, starting at 1, no matter how many form-level modifications there are.
Form-level modification names are stored in the masses section of the results file, accessible via ms_searchparams, as in Mascot 2.4 and earlier.
All versions of Mascot since 2.2 save query-level modification names as the IT_MODS parameter in the query section, which can be accessed with ms_inputquery::getIT_MODS(). Parser 2.5 and later parse the value of IT_MODS and make it available via ms_inputquery::getLocalVarModName(). In Parser 2.4 and earlier, you would need to split the unescaped IT_MODS manually to find the query-level modification names.
The local mods string getLocalModsStr() can be empty in Mascot 2.4 and earlier results files, and it can consist of only zeroes. If you need to test whether a peptide match uses query-level modifications, test that the string is non-empty and contains at least one non-zero digit.

In general, modification number for a residue can be non-zero only in one mods string at a time; that is, a residue cannot have a modification in both the variable mods string and the local mods string. The only exception is when support for multiple modifications on the same site is explicitly enabled, as described in section 3 below.

2. Extracting neutral losses

The neutral loss information of form-level and query-level modifications is encoded in two strings: ms_peptide::getPrimaryNlStr() and ms_peptide::getLocalModsNlStr(). The data format and numbering is analogous to variable modifications.

For form-level mods, use ms_searchparams::getVarModsNeutralLosses() to load the neutral loss vector of the variable modification. If a digit in getPrimaryNlStr() is non-zero, it refers to an element in the neutral loss vector. The vector is 0-based, so digit 2, for example, is the second element, at index 1.

For query-level mods, you need to locate the modification object first; see getLocalModsStr() for an example workflow. The correct neutral loss vector can then be loaded with ms_modification::getNeutralLoss(). As above, the non-zero digits in getLocalModsNlStr() refer to elements in the neutral loss vector.

3. More than one modification on the same site when MULTI_SITE_MODS=1

Mascot 2.4 added support for Multiple modifications for the same site in certain quantitation configurations, which is triggered when the search is run with the MULTI_SITE_MODS=1 parameter. In this mode, getVarModsStr() describes the exclusive modifications defined in the quantitation method, and getSummedModsStr() describes variable modifications occuring at the same sites as the exclusive modifications.

For example, suppose you have a results file using the SILAC quantitation method, which specifies Label:13C(6)15N(2) (K) as an exclusive modification. Suppose you also specify variable modification Acetyl (K) in the search form, so that the form-level modifications are 1=Acetyl (K) and 2=Label:13C(6)15N(2) (K). When MULTI_SITE_MODS=1, a peptide match could have getVarModsStr() == 00020000 and getSummedModsStr() == 00010000 That is, the former contains the (exclusive) SILAC label on K and the latter the variable modification (acetylation) on the same residue.

Now suppose the input query has also the query-level modifications IT_MODS=Methyl (KR), so that 1=Methyl (KR). Peptide matches to the query could have the following combinations of mods strings:

	Rank 1	Rank 2	Rank 3
getVarModsStr()	`00020000`	`00020000`	`00020000`	exclusive mods
getSummedModsStr()	`00010000`	`00000000`	`00010000`	variable mods
getLocalModsStr()	`00000000`	`00010000`	`00000010`	variable mods
	`123456`	`123456`	`123456`	(residue number)

In this case, the rank 1 match has acetylation and SILAC label on K (residue 3), while the rank 2 match has methylation and SILAC label on K (residue 3). The rank 3 match has acetylation and SILAC label on K (residue 3), and methylation on K or R at the C terminus (residue 6). Observe that in the rank 2 match, the summed mods string is empty and both the variable mods string and the local mods string contain a non-zero value for the third residue. This is the only case where getVarModsStr() and getLocalModsStr() can report a non-zero digit at the same site.

As a mnemonic, the summed and local modifications are always in addition to ("summed with") the exclusive modifications, which are recorded in getVarModsStr().

4. Using ms_aahelper to fragment peptide matches with query-level modifications

ms_aahelper::calcFragments() and ms_aahelper::calcFragmentsEx() are used for generating the fragment masses of a peptide match. The functions take an ms_peptide object as the first argument.

The peptide match object can have query-level modifications (a non-empty getLocalModsStr()). In this case, the query-level modifications are only included in fragment mass calculation if the peptide object is directly related to the results file with which the ms_aahelper object was initialised. That is, to calculate the right fragments for peptide matches with query-level modifications:

Open the results file using ms_mascotresfile_msr or ms_mascotresfile_dat.
Create an ms_aahelper object using the ms_mascotresfile object.
Create an ms_peptidesummary object using the same ms_mascotresfilebase object.
Find the peptide you want to fragment using e.g. ms_peptidesummary::getPeptide().
Pass the peptide object to ms_aahelper::calcFragmentsEx().

If the peptide object comes from a different file or if you initialise ms_aahelper without a results file, fragmentation will not take query-level modifications into account and some of the fragment masses will be incorrect.