PMSV: PARC Mass Spectrum Viewer

Preliminary. Last edit: 14 March 2005.
Send comments or suggestions to Russ Atkinson (atkinson@parc.com).

Introduction

The PARC Mass Spectrum Viewer (PMSV) is an experimental tool intended to view annotated mass spectrograph data for glycans as processed by tools produced by PARC/CSL. The annotation tool is known as Cartoonist, and is covered in separate documentation. PMSV is written entirely in Java (1.4 or later), and has been briefly tested on Sun Solaris, Apple Mac OS X, and Microsoft Windows platforms.

PMSV comes in two forms: an applet that provides a self-contained demonstration, and a full tool that allows examination of any of the files provided by Cartoonist. The applet form has a reduced command set and a fixed number of sample files.

Installing the full PMSV only requires storing the file called MassSpectrumViewer.jar to your preferred directory. Running the tool differs from platform to platform. Here are some known simple methods.

Solaris	java -Xmx200m -Xincgc -tar MassSpectrumViewer.jar
Mac OS X	double-click on MassSpectrumViewer.jar icon
Windows	double-click on MassSpectrumViewer.jar in browser window

Basic concepts

The purpose of Cartoonist is to match chemical structures with certain mass peaks observed in the spectrum. Each structure is indicated by a cartoon, which is a simple diagram for the chemical structure. There may be multiple cartoons for a given mass. Each cartoon has a demerit score, which may be used to determine cartoon display.

More information to be written.

Loading a file

When a directory is selected the file list is initially all files in the directory. A file browser allows the selection of a more limited list. Once the file list is established, the user can move forward or backwards in the list by using the next ([) and prev (]) submenus, or load any file in the list by the choose submenu.

Viewing data

Any rectangular portion of the graph can be magnified by selecting a rectangle using the mouse (with the familiar dragging selection method). The previous view can be restored using the undo operation (ESC). The undo can itself be undone by the redo operation (shift ESC).

Selecting a note is done by either clicking near a red box, or control-clicking near a red box. Either case selects the note, but control-clicking also automatically magnifies the note. On a Mac control-click is performed by option-click. A shift-click just reports the mass and intensity values associated with the point at the mouse position (useful for getting accurate readings of graph positions).

More information to be written.

Notes on display of cartoons

Even with the quality cutofff option, the cartoon display associated with a note can also get cluttered. The "only show best cartoons" option will restrict the displayed cartoons to the best, based on the demerit score for the cartoons. Multiple cartoons will still be displayed for tie scores.

There are 5 supported monosaccharide counts. In order, they are: GlcNAc+GalNAc (nac), Galactose+Glucose+Mannose (hex), Fucose (fuc), NeuAc, NeuGc. These counts are used to distiguish between notes, and can be displayed below cartoons and selected notes. For notes these counts are from the *.msa files, and for cartoons these counts are from the cartoons.txt file.

More information to be written.

CarbBank linkage

There is support for finding matching entrires in the CarbBank data base given a specific cartoon. In the second line of the cartoon display there are two numbers representing the rank and the demerit score. At the end of that line for each cartoon there may additional characters that indicate matching CarbBank entries. Cartoons that match the same mass monosaccharide counts are marked with a "c". If there are 10 or more matches it is a capital "C". Cartoons that do not match the same mass monosaccharide counts of any CarbBank entry are not marked.

To examine the matching CarbBank entries for a cartoon, just click on the cartoon. This will bring up a split window with a title describing the cartoon, followed by the names of the matching CarbBank entries, ranked with the best matches being first. Each entry can be expanded by clicking on it, which will show the full CarbBank entry in the lower part of the split window.

Each click on the cartoon will bring up another matching entry window, which can then be independent scrolled and examined. This facilitates comparison of CarbBank entries either between cartoons or for the same cartoon.

For some entries there may be only an approximate match in CarbBank. In many cases this is due to transpositions of parts of the structure, leaving the mass the same. The notation "h8" following the name indicates that there is some structural difference between the cartoon and the entry based on exact matches of the monosaccharides. The notation "h5" following the name indicates that there is some structural difference between the cartoon and the entry based on same mass matches of the monosaccharides. The notation "m8" following the name indicates that there is a difference in the monosccharide counts using exact equality of the monosccharides, although there is no difference in the counts based on the same mass.

The CarbBank structures may have repeats encoded in the structure. At this time those repeats are ignored and do not contribute to the mass.

The CarbBank structures may have unrecognized portions, including unrecognized monosaccharides. At this time those portions are ignored and do not contribute to the mass.

More information to be written. Details are likely to change

Option sets

There is an initial option set, named default, that is loaded (or created, if no option sets have been saved) when PMSV is initialized. This set can be modified, but cannot be removed.

Options are modified in the Options window. Option modifications take place immediately, and affect the display immediately, but only affect the current option set.

Any existing option set can be selected by clicking the choose button at the bottom of the Options window. The current option set will be highlighted in light green.

A new option set can be created using the "add" button at the bottom of the Options window. The user will be prompted for a name, and that name must not contain whitespace (blanks, tabs, newlines), and the name must not already exist as a named option set.

An existing option set can be removed using the "remove" button at the bottom of the Options window. The removable sets will be presented as a pop-up list. Click on a name to remove an indicated set, or click an empty area in the Options panel to dismiss the operation.

The named option sets can be saved and restored using the "save" and "restore" buttons at the bottom of the Options window.

The menus

Menu	submenu	action
File
	open	Opens a directory or set of files using a platform-dependent file chooser. Opening a directory is the same as choosing all of the files in the directory.
	fave dir	Allows selection from a list of favorite directories, taken from the file PMSV.roots in the user's home directory. The first file in the directory will be opened automatically.
	recent dir	Allows the selection of one of the most recently selected directories, most recent first. The first file in the directory will be opened automatically.
	type dir	Allows the typing of an explicit directory name. The first file in the directory will be opened automatically.
	choose	Allows selection of a single file from the current set of files.
	prev	Selects the next file from the current set. Typing the "[" key has the same effect.
	next	Selects the next file from the current set. Typing the "]" key has the same effect.
	new	Creates a new PMSV instance. The initial directory is the current directory, but no files will be loaded.
	clone	Creates a new PMSV instance. The new initial directory is the current directory, the new initial file list is the current file list, and the current file will be loaded automatically.
	print	Brings up a print dialog window, which allows the current graph to be printed. The printing may show additional detail for the graph, such as additional cartoons and finer detail for the spectra. To capture the exact graph (at screen resolution) one should use a platform-specific screen capture tool.
	quit	Quits the current program. No confirmation is requested.
	View
reset		Resets the view to the entire spectrum. Same as the R key.
expand		Doubles the current view in both directions. Same as the X key.
fit		Fits the current selected note to the entire window, attempting to get adjacent peaks viewable. Same as the F key.
undo		Undoes the most recent zoom/expand/fit command. Same as the ESC key.
redo		Reperforms the most recent command that was undone. Same as the Shift-ESC key.
Custom
	options	Bring up the Options window, which is used to edit options controlling the display.
	weights	Bring up the Cartoon Demerit Weights window, which is used to edit the demerit weights for cartoons. This feature is only useful for cartoons starting with version 4.
Info
	file	Shows information about the current file, including the title, the mass range, the intensity range, the number of pairs, and the number of notes.
	note all	Shows information about all notes with the same mass as the selected note.
	other	Shows other information for to the current running PMSV.
Help
	general	Views help about the application.
	keys	Views help about the single key commands.

The Options window

The slider lines permit adjustment of their values either by using the slider bar or by typing in a value. If typing a value, the value becomes active either when typing the ENTER (or RETURN) key, or when moving the focus to another value or window. If a typed value is syntactically incorrect or out of range then the typed value is ignored and the value gets a pink background.

The "min mass" and "max mass" values can only be typed. When these values change the display is reset to reflect the new bounds. The minimum displayed mass is the greater of the least mass value for the data and the "min mass" value. The maximum displayed mass is the lesser of the greatest mass value for data and the "max mass" value.

The check box lines permit changing some boolean options. The new values take effect immediately.

The line with "add", "remove", "choose", "save", and "restore" buttons allows the creating and removal of named option sets, the choosing of an existing set, and the ability to save and restore their values from a file (PMSV.options in the user's home directory).

Sliders
quality cutoff	The note cutoff slider controls the visibility of notes by specifying the least visible "quality" value for a note (smaller values indicate better fits to the measured data).
peak spacing	The peak spacing slider gives a mass range (in daltons) where the display of a peak will suppress the display of other peaks.
print scale	The print scale slider scales the cartoons and fonts used when printing. The default (print scale = 1.0) is the most detailed, and is suitable for a full page on a high resolution printer. Increasing the scale will produce larger fonts and cartoons when printing so the results will be acceptable when scaled down to fit a reduced figure on a page.
Switches
use bigger cartoons	Controls the cartoon display size (small/large). Toggle with C.
only show best cartoons	When true, cartoon display will only show the best cartoons for all notes of a given mass. Toggle with B.
show monosaccharide counts	When true the monosaccharide counts will be displayed directly below cartoon labels and selected note labels. Toggle with M.
show isotope weights	When true, pale blue circles indicate the positions of the predicted isotope counts for a selected note. Toggle with W.

The Cartoon Demerit Weights window

Each line has a value that can be changed by typing in a number from 0 to 99. The larger the number, the larger the demerit. Typing an invalid number colors the field pink. A change immediately recalculates the demerits of all cartoons and redisplays them. The cryptic description is intended to be understood by working geneticists.

At the bottom is the "default" button, which resets all of the weights to built-in default values (the ones used if the user has not saved option sets with a weight-supporting version of PMSV).

Plans for the future

I anticipate being able to edit note information and to save the edits in an additional file to supplement the notes file.

More information to be written.

Fine points

File names matching the following patterns should not be in the initial working directory for PMSV: cartoons.txt, cartoons.*.txt, isoTable.*.txt, nlinked.txt, olinked.txt, nlinked.index, olinked.index. These files are normally packaged with the MassSpectrumViewer.jar file, and local versions are supported for experimental reasons only. The use of inappropriate data files can lead to operational errors, or can simply lead to incorrect display.

The printing feature does not work for Solaris 7.x. It has been lightly tested for Solaris 8.x on UltraSparcs running Java 1.3.

More information to be written.

Recent changes