Issues with backward compatibility for results files [Mascot results file module]

Matrix Science endeavours not to make changes to the Mascot search results files that would 'break' 3^rd party applications. In general, any application that uses Mascot Parser will be safe when a new version of Mascot Server is released -- even if that software is not re-built (or re-linked) with the latest version of Mascot Parser. There are some exceptions to this, and these are listed below.

Increase in the number of variable modifications

From Mascot version 1.5 to 2.1, the limit on the number of variable modifications is 9. The variable modification string returned by ms_peptide::getVarModsStr() is of the form 0110030. One digit is used for the N terminus, one for each residue and one for the C terminus. Each digit specifies the modification used to obtain the match: 0 indicates no modification, 1 indicates delta1, 2 indicates delta2, etc., in the masses section of the results file. An 'X' is used to indicate an error tolerant modification that can be retrieved using ms_peptidesummary::getErrTolModName.

Mascot Server 2.2 and later still limit the number of variable modifications specified in the search form to 9 per search. However, 'exclusive' modifications are supported in quantitation methods, and these are reported using the same variable modifications string. It is possible that the number of modifications could then exceed 9. To support numbers greater than 9, the letters A..W are permitted, with A being 10 and W being 32. In Mascot Parser 2.2 and later, the method ms_mascotresults::getReadableVarMods() will return the correct modifications for values A to W. Earlier versions of Parser ignore any non numeric value apart from X. Any third party client software that parses the string returned from ms_peptide::getVarModsStr() will need to be modified to support A to W, and convert these to the numbers 10 to 32.

Separation between form-level and query-level modifications

Mascot 2.2 introduced query-level modifications, which are modifications speficied locally in an MS/MS peak list in a Mascot Generic Format (MGF) input file, using the IT_MODS parameter. Mascot 2.2, 2.3 and 2.4 combine search form-level modifications, exclusive modifications and all query-level modifications into a master list before the search starts. The master modification list is saved in the search parameters section, as above, available via ms_searchparams. The modifications string of a peptide match, getVarModsStr(), always refers to the indices of the master list.

Mascot 2.5 and later treat form-level and query-level modifications separately. The master list contains only form-level modifications and no query-level modifications. If query X has a local IT_MODS parameter and its rank Y match uses at least one local modification, Mascot writes a new parameter to the results file, called qX_pY_local_mods. The variable modifications string getVarModsStr() continues to refer to the master modification list, while the new query-level modifications string is available as getLocalModsStr(). The latter is a string of 1-based indices to the IT_MODS parameter of the corresponding input query. The Unimod section lists the equivalent of the master list of modifications, including all query-level modifications used in the search.

Most Parser functionality remains unaffected by the changes. For example, getReadableVarMods() takes the local modifications string automatically into account, and the duplicatedness status of peptide matches within a protein hit takes both form-level and query-level modifications into account when comparing peptide modifications. This means that for most common tasks, or if you do not use query-level modifications, you do not need to change anything in your program. In particular, Parser 2.5 and later fully support Mascot 2.4 and earlier results files.

If you do use query-level modifications, note that Parser 2.4 and earlier are not aware of the new qX_pY_local_mods strings in Mascot 2.5 and later results files. You can extract the raw values using getSectionValueStr(), but Parser 2.4 and earlier will not parse the values or include the query-level mods internally in getReadableVarMods() or elsewhere.

See Accessing query-level modification information for more details on query-level modifications in Mascot 2.5 and later results files.

Monolink deltas in crosslinked searches

Mascot 2.7 introduced intact crosslinks and cleavable crosslinks. Both types can produce monolinks, which are variable modifications. However, the monolinks of a linker usually have deltas different from the intact linker mass. Monolinks share the same variable mod number in the variable mods string and are differentiated by the monolink number in ms_peptide::getMonoLinkStr().

Parser 2.6 and earlier are not aware of the monolink string and will report incorrect deltas for monolinks.

Parser 2.7 and later automatically inspect the monolink string where relevant, for example in getReadableVarMods(). If you're processing the variable mods string manually, you must use the new API described in Crosslinked search results.