Tutorial Dashboard

This tutorial explains how to use the MASSTer dashboard for fast visual QA, feature inspection, and manual integration curation.

1. Launch the Dashboard

In a Python session, after building a Study, start the dashboard:

# Basic launch (blocking: returns after dashboard is closed)
mystudy.dashboard()

The dashboard will be accessible on any local browser at http://127.0.0.1:8050/. The corrent Python session will be blocked until the dashboard is closed.

2. Understand the Main Layout

The main screen is divided in two main panel:

• Data tables on the left, including samples, consensus features, sample features, MS2 data, library, identifications, and differential results.
• Analysis and interactive plots on the right.

Clicking on the data tables affects plots and data tables. For example, clicking on a row on the consensus tab determines what features or MS2 are available in the next tabs, or the plots that are shown in e.g. the Quant tab.

The division between the two panels can be dragged in both directions to expand the region of interest depending on the task.

The dashboard should be closed by clicking one of the two buttons in the header:

• The blue button Return and exit returns all changes to the python session. This is only relevant if the quantification/integration was adjusted manually.
• Exit w/o saving will close without updating the object. Both will stop the flask server. An empty tab will remain open in the browser. Unfortunately it's not possible to close it automatically.

3. Manage Data Table Columns

Not all columns are shown by default. The selection and order can be managed using the Columns widget on the right.

Additional options for sorting, filtering, copy-pasting, exporting, etc. are offered in the context menu. Use the table search box (Search...) to narrow the displayed rows by sample/feature keywords. Filters don't affect the underlying data.

In some cases, e.g. for sample_type, it is possible to directly edit the data. All modifications will be stored to the study object when leaving the dashboard.

Some of the plots in the right part, e.g. Consensus details and Feature details, display only the columns that are visible in the linked data table. By toggling column visibility, it is possible to fully customize the information that is shown.

4. QC samples

The first analysis tab QC Samples is meant to provide a view on the samples. A parallel coordinates plot shows all metadata visible in the Samples data table on the left side. Parallel coordinate plots can be reordered by dragging the axes. Dragging vertically on each axis allows to filter samples based on their properties.

Additionally, a principal component and hierarchical clustering provide a view on the underlying data.

5. 2D

Interactive scatter plot of consensus features. The plot can be customized to represent any data on axes, size, colors.

6. Consensus details

Parallel-coordinates details for consensus features. Drag axes to reorder and drag on an axis to filter.

7. Feature details

Detailed feature-level parallel coordinates (sample-linked). Useful to inspect within-consensus variability.

8. MS2

MS2 spectrum viewer. Select a row in the MS2 table to display the corresponding spectrum.

Up to 3 spectra will be shown at once:

• The "best" MS2 spectrum of the row that has been clicked in the Consensus data table
• The last clicked row in MS2 data table
• The last clicked row in Lib, if it is associated to a MS2 spectrum.

9. Quant

Quantification in masster is based on extracted ion chromatograms (EICs) of the precursor ion. This ensures results that are comparable to targeted workflows, in spite of deviations in peak shapes.

In study.integrate(), integration boundaries are extracted for each consensus feature. These are used a starting point to quantify the area for each sample. In practice, the start, end, and baseline are refined for every EICs, leading to slightly different values.

The Quant tab is divided in two panels.

• The top panel shows all EICs for one consensus feature, which can be selected by clicking on the Consensusdata table on the left. The upper panel also shows the start and end RT that are defined at consensus level, and are used as initial boundaries when analyzing a single EIC. Dragging the vertical bars (green and red) modifies their value. This has no consequence on the areas of the features, until they are reprocessed with one of the buttons located on the right of the panel.
• The lower panel shows the EIC of a single feature, i.e. the chromatogram of the same consensus feature shown above for a specific sample. The sample, or feature can be selected in the Features data table or using the drop down. In this panel, dragging boundaries or the baseline has an immediate effect on the integrated area.

A) Correct consensus integration settings

If you are not happy with the current boundaries shown in the upper plot, the first step is to adjust the consensus start and end points.

1. Optionally adjust Padding, Normalize, and y-log to obtain a clear picture of the location of the Start/End relative to all EICs.
2. drag the vertical boundary lines with the mouse to update consensus Start/End. Alternatively, you can type values in the boxes.
3. To apply the new settings to all sample EICs, hit the blue button Reintegrate all samples based on consensus to reanalyze the whole consensus with the new boundaries. After a few seconds, the lower plot will be updated with the new results:

B) Correct an individual sample peak integration

In some cases, single samples might require manual correction. The procedure is the same:

1. In the lower single-sample plot, choose a sample in the Sample dropdown.
2. Drag the integration boundary lines with the mouse to adjust Start and End only for that peak.
3. If needed, tune Baseline and verify the Area update.

11. Save and Exit Safely

Before closing, decide how changes should be handled:

• Save: persist changes to the current study.
• Save to new file: write curated results to a new study file.
• Return and exit: close and return control to Python.
• Exit w/o saving: close without persisting dashboard edits.

Recommendation: use Save to new file while iterating, so the original study remains unchanged.

12. Typical Curation Flow

1. Filter/select a consensus feature.
2. Inspect overlays and adjust integration boundaries if needed.
3. Re-check with normalized and/or log views.
4. Save curated results.
5. Continue with export/statistics in Python.

Related Tutorials

• Tutorial: Study Analysis
• Tutorial: Interpret Results
• Visualization tips