NAME
MSMSOutput - An object implementing common display/output methods for masses
SYNOPSIS
use MSMSOutput;
DESCRIPTION
MSMSOutput Perl object is intended to support common display and output methods for masses as obtained by mass spectrometry-related computations.
It is released under the LGPL license (see source code).
ATTRIBUTES
- spectrum
-
A reference to a hash such as computed by MassCalculator::getFragmentMasses or an object of class MSMSTheoSpectrum.
- expSpectrum
-
A reference to an experimental spectrum such as required by MassCalculator::matchClosest or an object of class ExpSpectrum. When this parameter is specified the constructor will assume that the hash spectrum contains data about the match with this experimental spectrum.
- massIndex
-
The mass index in the experimental peak vectors, default 0. If expSpectrum parameter is an ExpSpectrum object this index is read from the object directly.
- intensityIndex
-
The intensity index in the experimental peak vectors, default 1. If expSpectrum parameter is an ExpSpectrum object this index is read from the object directly.
- tol
-
Relative mass error tolerance; this parameter is optional. When not specified, the matched masses found by the match algorithm are all preserved. When specified, the new tolerance is applied.
This parameter is mainly useful for match obtained via matchSpectrumClosest that does not apply any mass tolerance.
- minTol
-
Absolute mass error, default value 0.2 Da. This parameter is used only in case tol parameter is specified, see above.
- intSel
-
This parameter controls how the peak intensities are normalized, see function normalizeIntensities.
Parameter intSel is used provided expSpectrum was set.
- prec
-
The number of digits after the decimal points for the masses. Default precision is 3 digits.
- modifLvl
-
Controls how the modifications are highlighted in the vector splitPept defined below, see also function annotatePept.
- cmp
-
This parameter is a reference to a comparison function used for sorting fragment names. If cmp is not set, the function cmpFragTypes is used instead.
METHODS
new(%h|$MSMSOutput)
Constructor. %h is a hash of attribute=>value pairs and $MSMSOutput is a InSilicoSpectro::InSilico::MSMSOutput object, from which the attributes are copied.
To prepare for actual output - through specialized methods - the constructor builds a dedicated data structure. In case users want to create new methods via inheritance or code modification, we describe hereafter this data structure:
my $table = new InSilicoSpectro::InSilico::MSMSOutput(...);
$table->{peptideMass} is the precursor peptide mass.
$table->{peptide} is the precursor peptide sequence.
$table->{modif} is the precursor peptide modification string.
$table->{splitPept} is a reference to a vector of the same length
as the peptide sequence that contains each
amino acid with annotated modifications (see
parameter modifLvl above).
$table->{intSel} is the value of the intSel parameter.
$table->{mass}{term} contains the terminal fragments.
$table->{mass}{intern} contains the internal fragments.
$table->{mass}{term}[i][0] contains the name of the ith fragment type.
$table->{mass}{term}[i][j] contains the mass of the jth fragment of type i.
$table->{mass}{intern}[i][0] contains the name of the ith fragment type
$table->{mass}{intern}[i][j,j+1] contains a description of the internal
fragment followed by its mass, j>0.
$table->{match} has the same structure as $table->{mass} but it
contains the matched experimental masses. How the
masses are matched depends on the match function
that was called.
$table->{intens} has the same structure as $table->{match} but it
contains the normalized intensities of the matched
experimental peaks.See also the code of the method tabSepSpectrum for a simple example of how this data structure can be used.
tabSepSpectrum($nColIntern)
This method returns a string containing a tab-separated tabular representation of the theoretical spectrum. Matched masses, if present, are ignored.
As it is certainly more appropriate to instantiate the object with modifLvl set to 1 (or 0) before calling this method, we also include in the output table a string giving the peptide modifications as obtained with modifLvl set to 2. Peptide mass is included as well.
The string computed by tabSepSpectrum is appropriate for loading in a spread sheet or is usable as an intermediary format for a custom output format. For the latter reason, we try to make it simple to parse and, in particular, we add a 'TERMINAL' tag at the beginning of the N-/C-terminal fragment masses and an 'INTERNAL' tag at the beginning the internal ones. Moreover, if match data are available, the matched theoretical masses are followed by the matched experimental masses and intensities in parentheses (should be easy to read and parse via elementary regular expressions).
The only parameter is:
- $nColIntern
-
Number of groups of 3 columns in the second table for the internal fragments. Default is 2.
Example:
my $msms = new InSilicoSpectro::InSilico::MSMSOutput(...);
print $msms->tabSepSpectrum();latexSpectrum($nColIntern)
This method returns a simple latex table in a string containing a tabular representation of the tabular structure generated by tabSpectrum. This table should be fairly easy to edit afterwards to meet specific style requirements. Matched masses, if present, are ignored.
Internal fragments (only immonium ions for the time being) are output in a separated table since their number is different from the peptide length.
The only parameter is:
- $nColIntern
-
Number of groups of 3 columns in the second table for the internal fragments. Default is 2.
Example:
my $msms = new InSilicoSpectro::InSilico::MSMSOutput(...);
print $msms->latexSpectrum(3);htmlTerm(%h)
This method returns a string containing the lines of an HTML table representing a tabular structure such as generated by tabSpectrum; only the N-/C-terminal fragments are considered, see the sister function htmlIntern for the internal fragments.
Since this method is susceptible to be used for generating HTML pages automatically, we give the user some flexibility to change the aspect of the output table (manual editing is not an option). Moreover, the <table> tag is not included in the returned string such that you can choose the table styles you want.
The named parameters are:
- colLineFunc
-
A reference to a function aimed at changing the line colors in the table to make it more readable. This package export two functions for this purpose: chooseColorLineNum and chooseColorFrag (see their respective descriptions).
You can define your own function if you need another logic. Such a function has four parameters: fragment type for the current line, fragment type of the previous line, a reference to color 1 and another to color 2 to exchange them.
The default function is chooseColorFrag.
- css
-
If css is defined then CSS are used instead of old fashioned in situ color and font specifications. See function htmlCSS.
- lineCol1, lineCol2
-
The two colors used for the lines, default colors are '#DDFFFF' and '#EEEEEE'.
- boldTitle
-
Peptide sequence in bold if set to any value.
- bgTitle
-
Background color for the peptide sequence, default '#CCFFCC'.
- boldFrag
-
Fragment names in bold if set to any value.
- bgFrag
-
Background color for the fragment names, default '#FFFFBB'.
Example :
my $msms = new InSilicoSpectro::InSilico::MSMSOutput(...);
print "<html><head></head><body><table border=0 cellspacing=5>\n";
print "\n",$msms->htmlTerm(boldTitle=>1, bgFrag=>'#FFFFBB', bgTitle=>'#99CCFF',
colLineFunc=>\&chooseColorFrag);
print "</table></html>\n";htmlIntern(%h)
This method returns a string containing the lines of an HTML table representing a tabular structure such as generated by tabSpectrum; only internal fragments are considered, see the sister function htmlTerm for the N-/C-terminal fragments.
Since this method is susceptible to be used for generating HTML pages automatically, we give the user some flexibility to change the aspect of the output table (manual editing is not an option). Moreover, the <table> tag is not included in the returned string such that you can choose the table styles you want.
The named parameters are:
- css
-
If css is defined then CSS are used instead of old fashioned in situ color and font specifications. See function htmlCSS.
- bgIntern
-
The color used for the lines, default '#EEEEEE'.
- boldTitle
-
Column titles in bold if set to any value.
- bgTitle
-
Background color for the column titles, default '#CCFFCC'.
- boldFrag
-
Fragment names in bold if set to any value.
- bgFrag
-
Background color for the fragment names, default '#FFFFBB'.
- nColIntern
-
Number of groups of 3 columns in the second table for the internal fragments. Default is 2.
Example:
my $msms = new InSilicoSpectro::InSilico::MSMSOutput(...);
print "<table border=0 cellspacing=5>\n";
print "\n",$msms->htmlIntern(boldTitle=>1);
print "</table>\n";plotSpectrumMatch(%h)
This method generates images to represent matches between theoretical and experimental spectra. Such images are intended to be used in user interface, typically web interfaces. To fit rather diverse requirements, a great number of parameters can be set to change colors and aspects of the plots.
The named parameters are:
- fname
-
The file name of the generated image.
- fhandle
-
An open file handle for writing the generated image. It has priority over parameter fname and the file handle will be set in binmode.
- format
-
The graphic file format. If not specified, the function will return the image object for further processing (see GD documentation). The supported file formats are the ones of GD.
- fontChoice
-
The size of the graphics is controlled via the choice of the font. The fontChoics parameter is a string 'class:size', where class selects the type of font and size its size.
The GD native fonts are selected by setting class equal to 'default'. The size the 'default' class must be one of 'Tiny', 'Small', 'MediumBold', 'Large', or 'Giant'. Default font is 'default:Large'.
Alternatively, it is possible give the name of a file containing the definition of a TrueType font for the class (absolute path) and size is the point size.
- inCellBorder
-
Number of pixels between lines and text, default 1.
- style
-
Two styles are supported for the match graphics: 'circle' and 'square'. Default is 'circle' except when modifLvl was 2 in tabSpectrum, where it is 'square'.
- plotIntern
-
If this parameter is set to any value, and at least one internal fragment mass exists, the internal fragments are represented in the graphics.
- nColIntern
-
Number of column to display internal fragments, default is 2.
- colorScale
-
This parameter is used for defining a list of intensities thresholds and corresponding colors used when highlighting the table cells to indicate fragment matches. Thresholds must be in increasing order of intensities.
colorScale is a reference to a vector of values, each threshold is associated with 8 values in the following order:
- threshold value
- red intensity (cell color)
- green intensity (cell color)
- blue intensity (cell color)
- legend text
- red intensity (legend text color)
- green intensity (legend text color)
- blue intensity (legend text color)
These eight data are repeated for each threshold and the number of threshold is not limited. The threshold values must be adapted to intensity normalization (see function tabSpectrum).
By default, plotSpectrumMatch generates a color scale that adapts to the normalization and contains 5 bins: blue (less intense), red, orange, yellow, green (most intense).
- legend
-
When this parameter is set to 'right', a legend is added at the right of the graphics. When it is set to 'bottom', a legend is added under the graphics.
The legend is made of the color scale and a count number of matched peaks versus number of experimental peaks in each intensity bin. This count informs on the quality of the match. It is important to note that it is not uncommon for an experimental peak to match several theoretical masses and therefore the count, which considers each mass once, may be slightly different from what is read from the graphics. The present two different point of views: theoretical and experimental masses point of views.
- changeColModifAA
-
Except when tabSpectrum was called with modifLvl equal to 2, plotSpectrumMatch displays one character per amino acid only, i.e. the asterisk indicating the presence of a modification is suppressed. When changeColModifAA is set to any value, plotSpectrumMatch display the modified amino acids in another color. If not set, the modified amino acids are over-lined.
- modifAAColor
-
A reference to a vector of three values (R, G, B) used to defined the color for modified amino acids, default blue.
- bgColor
-
A reference to a vector of three values (R, G, B) used to defined the graphics background color, default white.
- textColor
-
A reference to a vector of three values (R, G, B) used to defined the text color, default black.
- lineColor
-
A reference to a vector of three values (R, G, B) used to defined the line color, default black.
Example:
my $msms = new InSilicoSpectro::InSilico::MSMSOutput(spectrum=>\%spectrum, prec=>2, modifLvl=>1,
expSpectrum=>\@peaks, intSel=>'order', tol=>$tol, minTol=>$minTol);
$msms->plotSpectrumMatch(fname=>$peptide, format=>'png', fontChoice=>'default:Large',
changeColModifAA=>1, legend=>'bottom');FUNCTIONS
cmpFragTypes
This function can be used in a sort of fragment type names. Fragment type names are assumed to follow the rule:
- internal fragments
-
They are named after their generic name, only immonium ions are supported so far and they are named 'immo'.
- N-/C-terminal fragments
-
They must comply with the pattern
ion&charge - loss1 -loss2 - ...For instance, singly charged b ions are simply named 'b' and their doubly and triply counterparts are names 'b++' and 'b+++'. This is the ion&charge part of the pattern above.
The losses may occur once or several times, multiple losses are indicated in parentheses preceeded by multiplicity. Examples are:
b-H2O b-3(H2O) b++-H2O-NH3 b++-3(H2O)-NH3 y-H2O-2(H3PO4)-NH3
The order on fragment type names is defined as follows: (1) immonium ions always come after N-/C-terminal fragments; (2) N-/C-terminal fragment types are compared by doing a sequence of comparisons which continues as long as the compared values are equal. The first comparison is on the ion type (a,b,y,...) followed by a comparison on the charge. If ion types and charges are equal, comparisons are made on the losses. The fragment that has less loss types is considered smaller. If the two fragment types have the same number of loss types then the losses are sorted lexicographically and the first ones are compared on their name, if the names are the same then the comparison is on the multiplicity, if the multiplicities are the same then the second losses are compared, etc.
Asterisks that are used for signaling multiple possible losses are ignored in the comparisons.
Since this function is defined in package MSMSOutput and it is used in other packages with function sort (and predefined variables $a and $b), we had to use prototypes ($$). Therefore it can no longer be exported by the package MSMSOutput and you have to call it via MSMSOutput::cmpFragTypes.
Example:
foreach (sort MSMSOutput::cmpFragTypes ('y','b','y++','a','b-NH3','b-2(NH3)','b++-10(NH3)','b-H2O-NH3','immo(Y)', 'b++','y-NH3*','y-H2O*','z')){ print $_,"\n"; }
annotatePept($pept, $modif, $modifLvl)
Returns a vector whose cells contain each amino acid of the peptide sequence annotated with their eventual modifi- cations.
This function is exported for allowing users to prepare peptide sequences for display purposes. The parameters are:
- $pept
-
The peptide sequence.
- $modif
-
The modification string or the modification vector.
- $modifLvl
-
Controls how the modifications are highlighted in the returned vector.
If not set or set to 0, this parameter causes the modified amino acids not to be indicated. If set to 1, the modified amino acids are marked by an asterisk. If set to 2, the modified amino acids are followed by the name of the modification between curly brackets.
Example:
print join('', annotatePept('ACCTK', '::Cys_CAM:Cys_CAM:::', 2)), "\n";
normalizeIntensities($inSel, $expSpectrum, $normInt, [$massIndex, [$intensityIndex]])
Normalizes experimental peaks intensities. The parameters are:
- $intSel
-
This parameter controls how the peak intensities are normalized. Default choice is 'order' for relative order; other possible choices are 'relative' for relative intensity, 'original' for no normalization, and 'log' for logarithmic transform.
- $expSpectrum
-
The experimental spectrum.
- $normInt
-
A reference to a hash that will contain the normalized intensities (keys are the original intensities).
- massIndex
-
The mass index in the experimental peak vectors, default 0. If expSpectrum parameter is an ExpSpectrum object this index is read from the object directly.
- intensityIndex
-
The intensity index in the experimental peak vectors, default 1. If expSpectrum parameter is an ExpSpectrum object this index is read from the object directly.
htmlCSS(%h)
This function returns a string that can be used for defining a CSS, which is then used by the tables created by functions htmlTerm and htmlIntern. To give you more flexibility, we do not include the <style> tags in the string such that you can add the styles returned by htmlCSS where you like.
Alternatively, you can choose not to use this function and define totally different styles!
The named parameters are:
- lineCol1, lineCol2
-
The two colors used for the lines, default colors are '#DDFFFF' and '#EEEEEE'.
- boldTitle
-
Peptide sequence in bold if set to any value.
- bgTitle
-
Background color for the peptide sequence, default '#CCFFCC'.
- boldFrag
-
Fragment names in bold if set to any value.
- bgFrag
-
Background color for the fragment names, default '#FFFFBB'.
- bgIntern
-
The color used for the lines in the internal fragments table, default '#EEEEEE'.
Example :
my $msms = new InSilicoSpectro::InSilico::MSMSOutput(...);
print "<html>\n<head>\n<style type=\"text/css\">\n";
print InSilicoSpectro::InSilico::MSMSOutput::htmlCSS(boldTitle=>1);
print "</style>\n</head>\n<body><table border=0 cellspacing=5>\n";
print "\n",$msms->htmlTerm(css=>1);
print "</table><br><br><table border=0 cellspacing=5>\n";
print "\n",$msms->htmlIntern(css=>1);
print "</table></html>\n";chooseColorLineNum
Function for HTML output that alternates the line colors for every line.
chooseColorFrag
Function for HTML output that changes the line color when the type of fragment changes; b-H2O and b-2(H2O) are considered the same type by this function.
plotLegendOnly(%h)
This function plots the color scale only and should be used if you don not want to display it for each match plot. Note that the legend generated by PlotSpectrumMatch contains extra information that is specific to the match, i.e. the count of matched peaks per intensity bin. This information is not reported if you decide to save space and only display the color scale once.
The named parameters are (see plotSpectrumMatch for detailed explanations):
- fname
-
The file name of the generated image.
- fhandle
-
An open file handle for writing the generated image. It has priority over parameter fname and the file handle will be set in binmode.
- format
-
The graphic file format.
- fontChoice
-
The size of the graphics is controlled via the choice of the font.
- inCellBorder
-
Number of pixels between lines and text, default 1.
- colorScale
-
This parameter is used for defining a list of intensities thresholds and corresponding colors used when highlighting the table cells to indicate fragment matches.
- lineColor
-
A reference to a vector of three values (R, G, B) used to defined the line color, default black.
- intSel
-
In case no user-defined color scale is provided, a default color scale is used instead. To properly adjust this scale to the intensity normalization method it is important to indicate via parameter intSel which is this normalization. Possible values are listed in function normalizeIntensities.
EXAMPLES
See programs starting with testMSMSOut in folder InSilicoSpectro/InSilico/test/.
AUTHORS
Jacques Colinge, Upper Austria University of Applied Science at Hagenberg