Institute for Advanced Biosciences Keio University
MathDAMP Mathematica package for differential analysis of metabolite profiles
Home Overview Examples Downloads TriDAMP References Contact
MathDAMP > Examples > MathDAMP source > Core Functionality > Plotting Density Plots

Plotting Density Plots

The functions in this section facilitate the visualization of msdata on density plots. The axes represent the retention/migration time and m/z values. The peaks appear as colored spots. The color is assigned to a signal intensity value from a color gradient. The color is not calculated for each intensity during the generation of the plot but taken from a pre-generated palette instead. In other words, the pure function passed via the ColorFunction option of the ListDensityPlot function does not compute the color value but picks it from a pre-generated palette. This speeds up the process considerably.
DAMPGradient
returns a function which calculates the color parameters for the Hue directive corresponding to a relative position within the color gradient (the returned function takes this position as the only parameter <0;1>) . The gradient consists of three subgradients: backgroundgraylevel (at relative position 0) to color1 (at pos1), color1 (at pos1) to color2 (at pos2), and color2 (at pos2) to darkened color2 (at relative position 1). The pos1 and pos2 parameters represent the relative positions of the endpoints of the middle gradient (0;1); color1 and color2 parameters represent the hue specification <0;1> of the endpoints of the middle gradient; and the backgroundgraylevel parameter specifies the color (graylevel) of the background area <0;1> (black to white scale). The returned function is probably compiled for historical reasons only. Faster possibilities for the plot generation were investigated by increasing the speed of the function which was used as a color function in the ListDensityPlot function. The speed was not satisfactory, so a switch to pre-generating the color palette was made so that now the colorfunction just picks the appropriate color from the palette and does not calculate the color every time. The DAMPGradient still returns a compiled function although it does not make a significant difference in the current context.
DAMPGradientPalette uses the DAMPGradient function to generate a palette of two adjacent gradients (intended for positive and negative range). The palette will be used by the colorfunction of the ListDensityPlot to assign appropriate colors to signal intensities and to draw a legend. The option ColorPositions determines the relative position of gradient endpoints and is used for both positive and negative ranges (default: {.075,.4}). PositiveColors and NegativeColors hold the hue color specifications for the endpoints of the middle gradients in both positive and negative ranges (defaults: {1/6,0} - yellow to red; {1/2,2/3} - cyan to blue). BackgroundGrayLevel specifies the graylevel of the background area (default: 0.7 - 30% gray). PaletteSize specifies the number of palette entries (subdivisions) for both positive and negative range color gradients, entry for value 0 is shared between the two ranges.

DAMPGradient[pos1_, pos2_, color1_, color2_, backgroundgraylevel_] := Compile[{col}, {If[col ...  + ((1 - backgroundgraylevel) col)/pos1, If[col<pos2, 1, 0.2 + (0.8 (1 - col))/(1 - pos2)]]}]

Options[DAMPGradientPalette] = {Global`ColorPositions {0.075, 0.4}, Global`PositiveC ... eColors {1/2, 2/3}, Global`BackgroundGrayLevel.7, Global`PaletteSize200}

DAMPGradientPalette[opts___] := Module[{bgl, palsize, colposs, negfunc, posfunc}, bg ... erse[negfunc[#] &/@Drop[#, 1]], posfunc[#] &/@#] &[Range[0, 1, 1/palsize]] ]

DAMPDrawAnnotation[atdata,options] is used by the DAMPDensityPlot function to annotate the density plots of datasets and allow easier identification of peaks. The annotation table is passed via the atdata parameter. For the annotation table format, please refer to the description preceding the DAMPLoadAnnotationTable in the Annotation Table Manipulation subsection of the Core Functionality section. The TimeRange and mzs options determine the selection of annotation table items and their proper positioning on the density plots. The Resolution option specifies the m/z dimension coverage of each electropherogram on the density plot. To ensure the proper selection and display of the annotation labels, the m/z values in the annotation table are rounded to the resolution. Usually, the data are binned to 1 m/z resolution, so the default value for the Resolution option is set to 1. The option ScaleCoefficients ensures the correct positioning of the labels and their size reproducibility. The ScaleCoefficients are used for the scale conversion to the scale of the ListDensityPlot where the time scale is numbered sequentially for every datapoint. The positioning along the m/z dimension is done according to the respective m/z value's position within the mzs list, so the second element in the ScaleCoefficients is not relevant at the moment and is set to 1 by default. The scale conversion value for the time dimension is calculated in the DAMPDensityPlot function according to the msdata's timepoints. The option TextStyle determines the appearance of the annotation label's text, it is set to DAMPTextStyle by default, the FontSize is overriden to a smaller size (4) to fit better into the crowded density plots. The LabelStyle and LabelSize options determine the label mark's appearance and size. The size units are relative, {1,1} by default. The LabelShape option specifies a pure function for drawing the annotation label symbol. Two parameters are passed to the function, the first is the position on the ListDensityPlot's coordinate system {retention/migration time,m/z value} and the second the size of the size {xsize,ysize} in the same units. The scale conversion is set so, that the default relative size of the annotation label (LabelSize->{1,1}) draws an ellipse which appears to properly mark the peaks on the density plot. The {xsize,ysize} correspond to the ellipse's radii in this case.

Options[DAMPDrawAnnotation] = {Global`TimeRange {0, 50}, Global`MZsRange[50. ... ness[.25]}, Global`LabelShape (Circle[#1, #2] &), Global`LabelSize {1, 1}} ;

DAMPDrawAnnotation[atdata_, opts___] := Module[{at, timerange, mzrange, resol, scalecoefs, l ... le, {labelshape[position, {.2, .8} labelsize scalecoefs]}]}) &/@annottoshow ; tmpgr]

DAMPDensityPlot plots msdata using the ListDensityPlot function. The axes are intended to represent the migration/retention time and m/z. Signal intensities are encoded by colors. The color palette is generated using the DAMPGradientPalette function. The ColorFunction of the ListDensity plot then picks the closest palette entry for a given signal intensity. This implementation improves the speed of the plot generation (compared to calculating the color for every signal intensity by the color function). The plot legend is drawn explicitly and placed below the plot. Options for the ListDensityPlot may be passed via the option PlotOptions. The option MaxScale determines the size of the signal intensity scale. It is Automatic by default meaning the signal intensity scale is determined by the dataset's biggest positive or negative signal intensity value. The option FrameTickFreq determines the frequency of frameticks on the time and m/z axes. The value for the time axis specifies the frequency of tickmarks in minutes, for the m/z axis the frequency in the number actual m/z values from the dataset's m/z list. Default is {1,1} meaning a frametick will be placed for every minute on the time axis and for every single m/z value from the msdata's m/z list. FrameTickOffsets option specifies from which position to start to place the tickmarks on both axes. The mzTickShift option specifies the shift of every tickmark along the m/z axis. ListDensityPlot places the tickmarks at the beginning of the colored rectangle not in its middle. The -.5 shift places the tickmark in the middle of the colored rectangle. It may seem redundant with the FrameTickOffsets, but the functions of the two are different. mzTickShift can be used to appropriately place the tickmarks on the parallel plots where it is desirable to place the tickmark in the middle of the multiple parallel lanes corresponding to the same m/z. For this reason, the shifting on the m/z axis is not fixed to -.5 as is the case for the tickmarks on the time axis. The options mzGridLineFreq and mzGridLineStyle specify the distribution and appearance of horizontal gridlines. The horizontal gridlines are intended for better orientation on the plots in terms of estimating the m/z values of peaks/spots. Solid gridlines alternate with dashed ones by default. More complex patterns are possible by entering multiple style specifications in the mzGridLineStyle option. AnnotationTables option specifies the list of annotation tables and AnnotationOptions can be used to pass lists of options to the DAMPDrawAnnotation function and control the appearance of annotation labels for each annotation table. The signal intensities can be displayed using a logarithmic scale by setting the LogScale option to True.
mzFrameTicks option was added to facilitate easier display of asymmetric tickmarks on the m/z axis. This is used by the DAMPParallelPlot function if datasets of non-perfect overlap in terms of their m/z values are displayed. mzTickShift may be becoming obsolete due to this.

Options[DAMPDensityPlot] = {Global`MaxScaleAutomatic, Global`FrameTickFreqs  ... AMPTextStyle}, Global`AnnotationOptionsAutomatic, Global`LogScaleFalse} 

DAMPDensityPlot[msdata_, opts___] := Module[{tmax, gridfreq, palette, pallen, frametickfreq, ... ] &[(DisplayFunction/.{plotoptions}/.{DisplayFunction$DisplayFunction})])] ]

DAMPParallelPlot plots multiple msdatas in a parallel format. The datasets are interlaced into one dataset so that chromatograms/electropherograms corresponding to the same m/z value appear next to each other on the density plot. The chromatograms/electropherograms do not have to correspond to an identical set of m/z values in every dataset. The corresponding chromatograms/electropherograms are paired automatically and horizontal gridlines separate lanes of parallel chromatograms/electropherograms corresponding to the same m/z value. Some lanes may be narrower/wider depending on the presence of data corresponding to the particular m/z value in all datasets. Although aligned datasets are most appropriate to plot using DAMPParallelPlot, unaligned datasets may be plotted as well. In this case, the time axis is labeled according to the first dataset in msdatas and the chromatograms/electropherograms from the remaining datasets are simply concatenated or extended with 0 signal intensities to accommodate them to the dimensions of the first dataset. Please note that the time axis may be misleading in this case. The possibility to plot unaligned datasets is granted in spite of this to allow quick parallel visualizations of initial data prior to processing.

DAMPParallelPlot[msdatas_, opts___] := Module[{mzs, tplen, mzitm, msdataitm, mesodata, parda ... a, opts, Global`mzFrameTicksmzticks, Global`mzGridLineFreqmzgridlines] ]