Spectrum identifications in MasPy¶
In bottom up proteomic experiments proteins are analysed indirectly by peptides generated by proteolytic digestion. In most cases the resulting peptides are separated by liquid chromatography before they are ionized and subsequently analysed by the mass spectrometer in a setup called liquid chromatography-tandem mass spectrometry (LC-MS/MS). During the chromatographic separation the mass spectrometer records in certain intervals the mass to charge ratios (m/z) of all ions eluting at a given time point, which produces so called MS1 spectra. However, altough the m/z value of a peptide ion is known with very high accuracy, it is not possible to infer its amino acid sequence. This is because a huge number of theoretical peptides exist which have nearly or exactly the same mass but a different amino acid sequence. To solve this, ions present in the MS1 scan are isolated consequtively by a mass filter, fragmented and the m/z values of the resulting fragment ions are recorded, which generates an MS2 spectrum. It is also possible to isolate a fragment ion from an MS2 spectrum, fragment it again and measure the resulting ions, which is then called MS3. This procedure could be repeated multiple times and would result in consequent MSn scans, where “n” stands for the number of isolation and fragmentation cycles +1. Peptide sequence identification can now be inferred by comparing the observed MSn spectra with theoretical fragmentation spectra generated in silico. This procedure is called peptide spectrum matching. Another possibility is to compare the observed MS2 spectra with already identified observed fragmentation spectra from a library, which is called spectral library matching. For details see Protein Analysis by Shotgun/Bottom-up Proteomics #TODO: open access would be better, is it open?
The mzIdentML file format¶
#TODO: description of mzIdentML format
Representation of spectrum identifications in MasPy¶
Elements describing the identification of a peptide from a fragmentation
spectrum are called spectrum identification items (Sii
) in MasPy. The term Sii
is interchangeable with the more
commonly used term peptide spectrum match (PSM). However, we choose Sii
since it is in analogy to the mzIdentML format which we are planning to support
in the future.
The Sii
class has a very simple structure with all its variables being
directly stored as attributes of the class. The attributes id
and
specfile
are mandatory and used to unambiguously link the Sii
to a
Si
element of an MsrunContainer
. The Sii.id
is typically the scan
number of a spectrum and should be equal to the Si.id
entry, the
Si.specfile
refers to the specfile name which is used to identify a single
ms-run. Other attributes can be manipulated without restrictions and new
attributes can simply be added.
Further attributes which can be necessary for a reasonable utilization of
Sii
and their naming convention in MasPy:
peptide
the peptide sequence containing amino acid modifications in the MasPy format, see below.sequence
the plain amino acid sequence of the spectrum identification, does not contain modifications.score
or any other score attribute name which is used to rank the quality of a spectrum identifications. The name of this attribute and wheter a large or a small number indicates a higher confidence is specified inSiiContainer.info
.isValid
can be used to flag if a Sii has passed a given quality threshold or has been validated as correct.rank
the rank of this Sii compared to others for the same MSn spectrum. The rank is based on the specified score attribute.charge
the charge state of the identified precursor ion.rt
the retention time in seconds of the corresponding spectrum.obsMz
the experimentally observed mass to charge ratio of the precursor ion (Dalton / charge). Usually the monoisotopic ion.obsMh
the experimentally observed mass to charge ratio of the precursor ion, calculated for the mono protonated ion (Dalton / charge). Usually the monoisotopic ion.obsMass
the experimentally observed not protonated mass of precursor ion, calculated by using the mz and charge values (Dalton / charge). Usually the monoisotopic mass.excMz
the exact calculated mass to charge ratio of the peptide (Dalton / charge). Usually the monoisotopic ion.excMh
the exact calculated mass to charge ratio of the peptide, calculated for the mono protonated peptide (Dalton / charge). Usually the monoisotopic ion.excMass
the exact calculated mass of the not protonated peptide (Dalton / charge). Usually the monoisotopic mass.
Note
The amino acid sequence itself is commonly written in single letter code. However, there is no common style how to depict amino acid modifications in a linear string. Very often each modification is represented by a single symbol or a short string specifically highlighted for example by using brackets. This modification represenation is then written next to the modified amino acid residue, i.e. on the right side.
In MasPy we decided to highlight modifications by using square brackets
positioned right of the modified amino acid. It is possible to add
multiple modifications to one single residue by writing multiple bracket
pairs, eg PEP[mod1][mod2]TIDE
. This format allows simple parsing of
peptide strings to retrieve modifications and their position in the amino
acid sequence. In addition every character, except square brackets, could
be used as a symbol for an additional amino acid.
Unimod provides a comprehensive database of protein
modifications and is to our knowledge widely-used in the field of mass
spectrometry based proteomics. Therefore we decided to refer to the unimod
accession number whenever a modification is present in the database. Such
modifications are then written in the form of [u:X]
, where X is the
unimod accession number. Modifications not present in the database should be
represented by a short acronym, for example [DSS]
. Such additional
modifications have to be added to the MasPy modification database. (at the
moment this is only a dictionary maspy.constants.aaModComp
)
The spectrum identification item container (SiiContainer)¶
The SiiContainer
is used to store spectrum
identification results of one or multiple specfiles. The container allows saving
and loading of imported results and provides methods for convenient access to
the data.
Importing peptide spectrum matching results
During the import all PSMs have to be converted to Sii
and added to
SiiContainer.container
. Since for one spectrum multiple Sii
can exist,
they have to be ranked according to how well they can explain the observed
fragmentation ions, typically described by a score or the q-value. All Sii
of the same spectrum are put into a list, ranked and sorted according to a user
defined score. This sorted list is then stored in .container
, for details
see below. Only the Sii
at the first position of this list gets the
attribute .isValid
set to True
, this is even the case if multiple
Sii
with .rank == 1
exist. Afterwards all valid Sii
are additional
evaluated if they surpass a user defined quality threshold, typically this
threshold is a false discovery rate (FDR) of 1%.
The import routines currently provided by MasPy are not very extensive, covering only the import from percolator .tsv files of certain PSM search engines and mzIdentML files generated by MS-GF+. However, adjusting the existing methods to any .tsv file should be possible within minutes and will be added on demand. Two things are important to consider when doing this:
The spectrum identifier (scan number) is not always present in a separate field. It is very often part of a so called scan header string, which also contains the specfilename and sometimtes the precursor charge state. Thus it is necessary to provide a function which extracts the scan number.
For the import it is necessary to provide a function which translates a modification containing peptide string into the aforementioned MasPy representation. In most cases this can be achieved by a simple mapping function:
>>> def translatePeptide(peptide, modificationMapping): >>> for oldMod, maspyMod in modificationMapping: >>> peptide = peptide.replace(oldMod, '[' + maspyMod + ']') >>> return peptide >>> modificationMapping = [('#', 'u:21'), ('*', 'u:35')] >>> translatePeptide('S#PEPM*K', modificationMapping) u'S[u:21]PEPM[u:35]K'
Note
It might be necessary for the function that translates a modified peptide string into the MasPy format to be able to deal with modification strings which are a substring of another modification string, for example “ox” and “diox” in PoxEPdioxTIDE. In such a case if “ox” is simply converted both instances would be affected and the “di” would remain untreated. For most cases this can be solved by replacing the modifications which are a substring of another modification after the others.
The minimal information that should be imported from peptide spectrum matching
results are the scan identifier, modified peptide sequence and a
score, which can be used to apply a quality cut off. Other parameters can
either be generated from the modified peptide sequence (calculated mass, plain
amino acid sequence) or transferred from the MsrunContainer
Basic code examples¶
Importing spectrum identification results
A percolator tab separated file can be imported by using the function
maspy.reader.importPercolatorResults()
, the imported Sii
elements
are then added to the SiiContainer
instance passed to the function.
import maspy.core
import maspy.reader
siiContainer = maspy.core.SiiContainer()
maspy.reader.importPercolatorResults(siiContainer, 'filelocation/out.tsv',
'specfile_name_1', 'psmEngine')
If necessary, spectrum attributes can be added from the MsrunContainer
by
using the function SiiContainer.addSiInfo
. This adds the selected attributes to
all Sii
elements of the specified specfiles.
import maspy.core
import maspy.reader
mzmlfilepath = 'filedirectory/specfile_name_1.mzML'
msrunContainer = maspy.core.MsrunContainer()
maspy.reader.importMzml(mzmlfilepath, msrunContainer)
siiContainer.addSiInfo(msrunContainer, specfiles='specfile_name_1',
attributes=['obsMz', 'rt', 'charge']
)
It is also possible to calculate the exact mass for all Sii
elements of the
specified specfiles by using the function SiContainer.calcMz()
. The calculated mass to charge ratio is
written to the attribute .excMz
.
siiContainer.calcMz(specfiles='specfile_name_1')
Accessing data stored in a SiiContainer
There are multiple ways how to access single Sii
elements stored in a
SiiContainer
. The method SiiContainer.getValidItem()
can be used to directly access
Sii
which .isValid
argument is True
by using its specfile and
identifier. If no such Sii
exists for the specified identifier None
is
returned. In this example there is a valid entry for the identifier ‘10’, but
not for ‘11’.:
>>> sii = siiContainer.getValidItem('specfile_name_1', '10')
>>> sii.isValid
True
>>> sii == None
False
>>> sii = siiContainer.getValidItem('specfile_name_1', '11')
>>> sii == None
True
It is possible to access all Sii
elements of a given identifier by directly
accessing the container SiiContainer.container
. In this example, there are multiple Sii
elements
present for the same spectrum, but only one is valid.
>>> siiContainer.container['specfile_name_1']['10']
[<maspy.core.Sii at 0xb354a90>,
<maspy.core.Sii at 0xb354c50>,
<maspy.core.Sii at 0xb354b38>]
>>> for sii in siiContainer.container['specfile_name_1']['10']:
>>> print(sii.id, sii.rank, sii.isValid)
10 1 True
10 2 False
10 3 False
By using the function SiiContainer.getItems()
it is possible to iterate over all Sii
elements present in the SiiContainer
. Multiple arguments can be passed to
the function that allow selecting only a specific subset of items but also to
return the items in a sorted order. For details consult the docstring.
Depricated - work in progress¶
Outline
Typical MS/MS experimental setup: MS1 detection -> isolation -> fragmentation
Identification of MS/MS spectra -> assigning a peptide which generated the fragmentation spectrum
This process can be described as peptide spectrum matching and is done by three major methods:
- Comparison of theoretical spectra derived by an in silico digestion of a protein database
- Comparison of observed spectra with spectra of known peptide origin (spectral library search)
- De novo sequencing by comparing the mass differences of the observed ions to the actual mass differences of the peptide bulding blocks, amino acids and modified amino acids.
How well does the assigned peptide explain the spectrum, described by an arbitrary score or a probability that the match is wrong
What is the official format to record this identification information, mzIdentML. Not yet supported in MasPy
Represenation of PSMs in MasPy (How to depict amino acid modifications in maspy)
How are Sii stored in MasPy (SiiContainer), how to access Sii
Importing PSM results into Maspy - minimal requirements (peptide, scanId, score), a function to translate modifications.
From thermo homepage
Tandem mass spectrometry (MS/MS) offers additional information about specific ions. In this approach, distinct ions of interest are selected based on their m/z from the first round of MS and are fragmented by a number of methods of dissociation. One such method involves colliding the ions with a stream of inert gas, which is known as collision-induced dissociation (CID) or higher energy collision dissociation (HCD). Other methods of ion fragmentation include electron-transfer dissociation (ETD) and electron-capture dissociation (ECD).
From abc and xyz (link)
Having determined the m/z values and the intensities of all the peaks in the spectrum, the mass spectrometer then proceeds to obtain primary structure (sequence) information about these peptides. This is called tandem MS, because it couples two stages of MS. In tandem MS, a particular peptide ion is isolated, energy is imparted by collisions with an inert gas (such as nitrogen molecules, or argon or helium atoms), and this energy causes the peptide to break apart. A mass spectrum of the resulting fragments — the tandem MS (also called MS/MS or MS2) spectrum — is then generated (Fig. 3c). In MS jargon, the species that is fragmented is called the ‘precursor ion’ and the ions in the tandem-MS spectrum are called ‘product ions’ (more endearingly, but less politically correct, they used to be described as parent and daughter ions). Note that the MS2 spectrum is the result of an ensemble of one particular precursor ion fragmenting at different amide bonds. Throughout the chromatographic run, the instrument will cycle through a sequence that consists of obtaining a mass spectrum followed by obtaining tandem mass spectra of the most abundant peaks that were found in this spectrum.