TopMSV

This manual describes the web pages of TopMSV and the operations available on each page. A dataset in TopMSV is a single SQLite file written by TopFD and TopPIC. TopFD stores the deconvoluted MS1 and MS/MS spectra and the MS1 3D peak tables in the file, and TopPIC appends its proteoform identifications and the protein sequence database. Which pages are available for a dataset depends on the tables in its file: the spectra browser and the visual inspection page work for every dataset, the identification pages need the TopPIC tables, and the MS1 3D view needs the 3D peak tables written by recent versions of TopFD. A step-by-step walkthrough with an example dataset is given on the tutorial page.

1. Home page

The home page is shown at the server address (by default http://localhost:3000). The TopMSV version is shown next to the title. The page has two panels.

Upload a dataset

Dataset name: an optional name for the dataset. When it is left empty, the name of the SQLite file is used.
TopFD / TopPIC sqlite file: click "Choose File" to select the SQLite file written by TopFD and TopPIC.
Upload: uploads the file. The server checks the file and, when identifications are present, reads and matches them once. The message "Dataset ... is ready" is shown when the dataset can be opened. Uploading a large file may take a moment.

Datasets

The table lists all uploaded datasets with the columns Name, Created, Proteins, Proteoforms, PrSMs, MS1 / MS2 scans, and Open. A dash is shown in the three identification columns when the file has no TopPIC tables, and the name is followed by "(spectra only)" in that case, or by "(no database)" when the file has no protein sequence database.

Identifications: opens the list of identified proteins. The link is shown only when the file holds TopPIC identifications.
Spectra: opens the raw-spectra browser.
MS1 3D: opens the MS1 3D view. The link is shown only when the file holds the MS1 3D peak tables.
Delete: permanently removes the dataset from the server after a confirmation.

When the server is started in view-only mode (see the tutorial), the upload panel and the Delete buttons are hidden, so existing datasets can be shared without the risk of changes.

2. Navigation bar

Every dataset page has a navigation bar with the entries Home, Protein Identifications, Spectrum Identifications, Visual Inspection, Spectra, and MS1 3D. The entry of the current page is highlighted. The two identification entries are disabled when the dataset has no TopPIC identification tables, and the MS1 3D entry is disabled when the dataset has no MS1 3D peak tables. Hovering over a disabled entry shows the reason.

3. Protein identifications

3.1 Protein list

The page lists all identified proteins. The heading gives the number of proteins. Each entry shows the protein name and description, which link to the protein page, followed by a sentence with the E-value of the best PrSM (proteoform-spectrum-match) of the protein and the number of identified proteoforms. The "best PrSM" link opens the PrSM page of the best match.

3.2 Protein page

The page shows all proteoforms identified for one protein. For each proteoform, the heading gives the proteoform number and its feature intensity, followed by the E-value and precursor mass of its best PrSM, the number of PrSMs (a link to the proteoform page), and the annotated sequence of the best PrSM. The annotated sequence is drawn in the same way as on the PrSM page (Section 4.2): matched cleavage sites are marked by blue brackets, and mass shifts are shown above the shifted residues. Hovering over a bracket shows the matched fragment ions. The "All proteins" link returns to the protein list.

3.3 Proteoform page

The page lists all PrSMs of one proteoform in a table with the columns Scan, Protein, E-value, # all masses, # matched masses, # matched fragment ions, and Link. Click the link in the last column to open the PrSM page. The links at the top and the bottom of the page lead back to the protein page and the protein list.

4. PrSM page

The page shows one proteoform-spectrum-match. The links at the top and the bottom lead to the protein list, the protein page, and the proteoform page.

4.1 Summary table

The table below the heading lists the PrSM ID, the scan number(s), the precursor charge, the precursor m/z and monoisotopic mass, the proteoform mass, the numbers of matched deconvoluted masses and matched fragment ions, the number of unexpected modifications, the E-value, and the spectral Q-value. The precursor m/z value is a link that opens a popup window with the MS1 spectrum of the precursor (Section 4.4).

4.2 Annotated proteoform sequence

The proteoform sequence is drawn with the residue numbers at the left and the right of each row. Red brackets mark the first and the last residue of the proteoform when it covers only part of the protein sequence. Blue brackets mark cleavage sites with matched fragment ions; the shape of a bracket tells whether N-terminal ions, C-terminal ions, or both are matched. Mass shifts are written above the shifted residues, which are drawn on a colored background. Fixed, variable, and unexpected modifications are also listed as text below the sequence.

Hover over a cleavage site: a tooltip shows the fragment ions matched at the site.
Click a cleavage site: the mass table (Section 4.5) is filtered to the masses matched at the site.
Save PrSM: opens a dialog for saving the annotated sequence as a PNG or SVG image. The dialog has the settings "Amino acids per row", "Letter width", "Row height", "Gap between blocks", "Gap between num and seq", "Show numbers", and "Show skipping information". Click "Redraw" to preview the settings and "PNG" or "SVG" to save the image.

4.3 Spectrum views

Click Show Spectrum to show the spectrum views; the button then changes to "Hide Spectrum". There are two tabs for each MS/MS scan of the PrSM.

Scan N: the MS/MS spectrum with its peaks. Circles mark the peaks of theoretical isotopic envelopes reported by TopFD, and the circles of one envelope have the same color. Matched envelopes are labeled with their fragment ion names.
Scan N masses: the deconvoluted monoisotopic masses of the spectrum. The proteoform sequence and its theoretical fragment masses are drawn above the mass spectrum, matched masses are labeled with ion names, and an error plot at the bottom shows the mass error of each matched mass. The checkbox Show annotation lines toggles the dashed lines connecting the matched masses to the sequence.

The spectrum views support dragging and zooming with the mouse; see Section 9. The buttons next to the mass filters are shown while the spectrum is visible.

Help: shows the mouse operations of the spectrum views.
Save Spectrum: opens a dialog for saving the current view as a PNG or SVG image, with the options "Show envelopes", "Show ions", and "Show error plot".

4.4 MS1 spectrum popup

Clicking the precursor m/z value in the summary table opens a draggable popup window with the MS1 spectrum. The isolation window of the precursor is highlighted, and the envelopes in the window are marked by circles. The popup has "PNG" and "SVG" buttons for saving the spectrum image.

4.5 Mass table

The table lists the deconvoluted masses of the MS/MS spectrum with the columns Scan, Mass ID, Mono mass, Mono m/z, Ref m/z, Intensity, Charge, Theoretical mass, Ion, Pos, Mass error, and PPM error. The theoretical mass, ion name, position, and errors are filled in only for matched masses. Ref m/z is the m/z value of the most abundant isotope of the envelope; the column is empty for SQLite files written by older versions of TopFD.

All masses, Matched masses, Not matched masses: the links above the table filter the rows. The number of masses in each group is given in parentheses.
Sort: click a column heading to sort the table by the column.
Click a Ref m/z value: shows the spectrum view of the scan and centers it at the m/z value.

4.6 Inspect

The Inspect button at the top right opens a menu with one entry per MS/MS scan of the PrSM. Clicking an entry opens the visual inspection page (Section 6) in a new tab with the peaks, masses, sequence, modifications, and precursor mass of the PrSM filled in.

5. Spectrum identifications

The page lists all identified MS/MS spectra. Each entry shows the MS/MS scan number, the scan number of its precursor MS1 spectrum, the protein name, and the proteoform sequence with its modifications in brackets. Fixed modifications are written by name, and unexpected mass shifts by their mass. Clicking a sequence opens the PrSM page.

6. Visual inspection

The visual inspection page matches a list of deconvoluted masses against a protein sequence with user-selected ion types, modifications, and mass tolerance, and draws the result. The page can be opened from the navigation bar with empty inputs, from the Inspect menu of a PrSM page, or from the Inspect button of the spectra browser. All computations run in the web browser.

6.1 Inputs

Load from this dataset: fills the inputs from the dataset. Choose "PrSM ID", "Spectrum ID", or "MS2 scan" in the dropdown, type the number, and click "Load". Loading a PrSM fills the peaks, masses, ion types, sequence, modifications, and precursor mass. Loading a spectrum or a scan fills the peaks, masses, and ion types only; the sequence and the precursor mass are left unchanged. The page address is updated after each load, so it can be bookmarked or reloaded.
Peaks: the peaks of the MS/MS spectrum, one peak per line with its m/z value and intensity. The list is optional; when it is empty, only the mass graph is drawn.
Masses & intensities: the deconvoluted masses, one mass per line with its monoisotopic mass, intensity, and charge. Additional columns are ignored.
Ion types: checkboxes for the ion types a, b, c, x, y, z, and z° and their water and ammonia losses. By default b and y ions are selected.
Fixed PTMs: click "Add a PTM" to add a fixed modification. The dialog offers carbamidomethylation (C: 57.021464) and carboxymethylation (C: 58.005479) of cysteine, and "Custom PTM" for a modification with a user-given residue, mass, and name. Each added PTM is shown as an editable residue and mass pair with a remove button.
Precursor mass: the monoisotopic precursor mass. After "Submit" is clicked, the molecular mass of the proteoform and the difference between the two masses are shown next to it.
Protein sequence: the protein or proteoform sequence. Mass shifts can be written in the sequence in brackets, such as MPRS[79.9663]LKKGPF.
Mass error / PPM error: the error tolerance for matching masses, in Da (default 0.1) or in ppm (default 15).
Help: shows a description of the inputs.
Submit: matches the masses against the sequence and draws the results.

6.2 Results

After "Submit" is clicked, the following views are drawn below the inputs.

Annotated sequence: the sequence with matched cleavage sites and mass shifts, drawn as on the PrSM page. In addition, clicking a residue opens a dialog for adding a modification at the residue. The "Variable PTM" tab lists common PTMs, which can be filtered with the search box; clicking a PTM applies it. The "Unknown Mod" tab takes an arbitrary mass shift value. The matching is repeated after a modification is added. "Save PrSM" saves the annotated sequence as an image.
Graph tabs: the "Scan" tab shows the MS/MS spectrum built from the peak list with matched envelopes labeled by ion names, and the "Mass scan" tab shows the deconvoluted masses with the theoretical fragment masses and the error plot. When the peak list is empty, only the "Mass scan" tab is shown. The graphs support the mouse operations in Section 9. The "Hide Spectrum" button hides the graphs, and "Save Spectrum" saves the current graph as an image.
Mass table: the deconvoluted masses with the same columns as the mass table of the PrSM page, except that Ref m/z is not available and the Mono m/z value is the link that centers the spectrum. The links "All masses", "Matched masses", and "Not matched masses" filter the rows.
Theoretical fragment masses: a table with a row per residue and a column per selected ion type. A dash marks a fragment that does not exist, and matched fragments are highlighted. Clicking a matched cell switches to the "Mass scan" tab and centers the graph at the mass.

7. Spectra browser

The spectra browser shows all MS1 and MS/MS scans of a dataset. The bar below the navigation bar shows the dataset name and the numbers of MS1 and MS/MS scans. The page has four panels: MS1 Spectrum, MS2 Spectrum, MS1 Mass List, and MS2 Mass List. A panel can be moved by dragging its header and resized by dragging its bottom-right corner.

7.1 Spectrum panels

The header of a spectrum panel shows the index of the current spectrum, its scan number, the numbers of peaks and envelopes, and the retention time. The MS2 panel also shows the precursor m/z value. Circles in a spectrum mark the peaks of theoretical isotopic envelopes reported by TopFD. The MS1 panel also draws two red horizontal lines for the base intensity and the minimum reference intensity used in the deconvolution.

Go to scan: type a scan number and click "Go" (or press Enter) to show the scan.
Prev and Next: show the previous or the next scan of the same MS level.
Reset: restores the default zoom of the panel.
Help (MS1 panel): shows the mouse operations.
Inspect (MS2 panel): opens the visual inspection page in a new tab with the peaks and masses of the current MS/MS spectrum.
Linked navigation: when an MS1 spectrum is shown, its first fragmentation scan is shown in the MS2 panel, and when an MS/MS spectrum is shown, its precursor MS1 spectrum is shown in the MS1 panel.
Click an envelope circle: the row of the envelope in the mass list is highlighted and scrolled into view.

7.2 Mass lists

The mass lists show the envelopes of the current spectra with the columns Mass ID, Mono mass, Mono m/z, Ref m/z, Charge, Intensity, and Score. The score is the EnvCNN score reported by TopFD. Click a column heading to sort the list. Click a Ref m/z value to center the spectrum at the m/z value; the column is empty for SQLite files written by older versions of TopFD.

8. MS1 3D view

The MS1 3D view draws the MS1 peaks of the dataset in three dimensions: the x axis is the m/z value, the depth axis is the retention time in minutes, and the height of a peak is its intensity. The peaks are stored at several resolution levels, and the level matching the size of the current window is used; at most 4000 of the strongest peaks are drawn. The panels above the plot show the cursor position and the peaks on display, the window settings, and a summary of the mouse operations.

8.1 Window settings

Retention time (min) and m/z: the ranges of the window. The boxes are updated after every zoom and pan.
Intensity cutoff: peaks with a lower intensity are not drawn.
Peak colors: "Absolute intensity" colors peaks by their intensity in the whole dataset, and "Relative to the window" colors them relative to the highest peak in the window.
Intensity auto scaling: when checked, the peak heights are scaled to the highest peak in the window.
Highlight scan (ctrl + click): when checked, the selected MS1 scan is drawn as a pink line across the window and its peaks are highlighted.
Request: loads the peaks of the entered window. Pressing Enter in a text box does the same.
Reset: returns to the full data range and clears the cutoff, the manual intensity scale, and the highlighted scan.
Save image: saves the plot as a PNG file.
+ and −: enlarge or shrink the plot.
Full screen: shows the plot in full screen.

8.2 Mouse operations

Left drag: pans the window. The peaks are reloaded when the mouse button is released.
Right drag: rotates the view. When the view is rotated to look straight down, the peaks are drawn as a flat 2D map.
Mouse wheel inside the plot: zooms both axes around the cursor. Over the m/z margin or the retention time margin, only that axis is zoomed.
Ctrl + mouse wheel: scales the peak heights. The scale is kept while zooming and panning; "Reset" restores the default.
Ctrl + click: highlights the MS1 scan nearest to the cursor. While Ctrl is held, a tooltip shows the scan number, m/z value, and retention time at the cursor.

9. Operations of 2D spectrum views

The spectrum views on the PrSM page, the visual inspection page, and the spectra browser share the same operations.

Dragging: hold the left mouse button down and move the mouse to pan the view along the x axis.
Zooming of the x axis: place the mouse pointer below the x axis and use the mouse wheel to zoom the m/z or mass range in and out around the pointer.
Scaling peak intensities: place the mouse pointer above the x axis and use the mouse wheel to scale the intensities.
Hovering over a peak: the peak is highlighted in red and its m/z (or mass) value and intensity are shown.
Hovering over an envelope circle: the m/z value, intensity, monoisotopic mass, and charge of the envelope are shown.
Hovering over a theoretical fragment mass in a mass graph: the mass and the ion type are shown.
Envelope colors: the circles of one envelope have the same color, and envelopes within 2 m/z of each other are given different colors so that overlapping envelopes can be told apart.