Quick Start

This page provides an overview of the functionalities of MassDash and shows a highlights a few convience functions to help you get started with the python interface. The python interface is designed to be run in a jupyter notebook so that plots can be reproducibly generated for a particular peptide of interest.

Plotting a Chromatogram

Here, we will demonstrate how to plot a chromatogram of the peptide NKESPT(UniMod:21)KAIVR(UniMod:267) with a charge state of 3 from multiple different file inputs. The general process is that first the loader object must be initiated and then we can call the plotChromatogram() method to fetch an interactive plot for a specified precursor.

SqMass Visualization

Running OpenSwath with a out_chrom filename.sqMass will output the extracted chromatograms alongside the OpenSwath results. Since extraction is already performed this is the quickest way to visualize plots.

Since the .sqMass file does not contain any metadata, to link chromatograms with their corresponding peptide sequence we must link an .osw file with the .sqMass file. In MassDash this is done by initiating a SqMassLoader as shown below.

from massdash.loaders import SqMassLoader
sqMassLoader = SqMassLoader(rsltsFile='osw/test_data.osw', dataFiles='xics/test_chrom_1.sqMass')

Initializing valid scores for selection

Now that the SqMassLoader is initiated we can use it to plot a chroamtogram. To plot a chromatogram, we use the plotChromatogram() function.

sqMassLoader.plotChromatogram("NKESPT(UniMod:21)KAIVR(UniMod:267)", 3)

Loading BokehJS ...

Figure(

id = '1003', …)

above = [Legend(id='1163', ...)],

align = 'start',

aspect_ratio = None,

aspect_scale = 1,

background = None,

background_fill_alpha = 1.0,

background_fill_color = '#ffffff',

below = [LinearAxis(id='1012', ...)],

border_fill_alpha = 1.0,

border_fill_color = '#ffffff',

center = [Grid(id='1015', ...), Grid(id='1019', ...)],

css_classes = [],

disabled = False,

extra_x_ranges = {},

extra_x_scales = {},

extra_y_ranges = {},

extra_y_scales = {},

frame_height = None,

frame_width = None,

height = 450,

height_policy = 'auto',

hidpi = True,

inner_height = 0,

inner_width = 0,

js_event_callbacks = {},

js_property_callbacks = {},

left = [LinearAxis(id='1016', ...)],

lod_factor = 10,

lod_interval = 300,

lod_threshold = 2000,

lod_timeout = 500,

margin = (0, 0, 0, 0),

match_aspect = False,

max_height = None,

max_width = None,

min_border = 5,

min_border_bottom = None,

min_border_left = None,

min_border_right = None,

min_border_top = None,

min_height = None,

min_width = None,

name = None,

outer_height = 0,

outer_width = 0,

outline_line_alpha = 1.0,

outline_line_cap = 'butt',

outline_line_color = '#e5e5e5',

outline_line_dash = [],

outline_line_dash_offset = 0,

outline_line_join = 'bevel',

outline_line_width = 1,

output_backend = 'canvas',

renderers = [GlyphRenderer(id='1042', ...), GlyphRenderer(id='1049', ...), GlyphRenderer(id='1056', ...), GlyphRenderer(id='1063', ...), GlyphRenderer(id='1070', ...), GlyphRenderer(id='1077', ...), GlyphRenderer(id='1090', ...), GlyphRenderer(id='1096', ...), GlyphRenderer(id='1102', ...), GlyphRenderer(id='1109', ...), GlyphRenderer(id='1115', ...), GlyphRenderer(id='1121', ...), GlyphRenderer(id='1128', ...), GlyphRenderer(id='1134', ...), GlyphRenderer(id='1140', ...), GlyphRenderer(id='1147', ...), GlyphRenderer(id='1153', ...), GlyphRenderer(id='1159', ...)],

reset_policy = 'standard',

right = [Legend(id='1036', ...)],

sizing_mode = 'scale_width',

subscribed_events = [],

syncable = True,

tags = [],

title = Title(id='1168', ...),

title_location = 'above',

toolbar = Toolbar(id='1028', ...),

toolbar_location = 'above',

toolbar_sticky = True,

visible = True,

width = 800,

width_policy = 'auto',

x_range = DataRange1d(id='1004', ...),

x_scale = LinearScale(id='1008', ...),

y_range = DataRange1d(id='1006', ...),

y_scale = LinearScale(id='1010', ...))

By default the plot is smoothed and the boundaries of the features found in the OpenSwath file are plotted. The length of the boundary lines is indicative of the intensity of the feature. These can be turned off as shown below.

sqMassLoader.plotChromatogram("NKESPT(UniMod:21)KAIVR(UniMod:267)", 3, includeBoundaries=False, smooth=False)

Loading BokehJS ...

Figure(

id = '1347', …)

above = [],

align = 'start',

aspect_ratio = None,

aspect_scale = 1,

background = None,

background_fill_alpha = 1.0,

background_fill_color = '#ffffff',

below = [LinearAxis(id='1356', ...)],

border_fill_alpha = 1.0,

border_fill_color = '#ffffff',

center = [Grid(id='1359', ...), Grid(id='1363', ...)],

css_classes = [],

disabled = False,

extra_x_ranges = {},

extra_x_scales = {},

extra_y_ranges = {},

extra_y_scales = {},

frame_height = None,

frame_width = None,

height = 450,

height_policy = 'auto',

hidpi = True,

inner_height = 0,

inner_width = 0,

js_event_callbacks = {},

js_property_callbacks = {},

left = [LinearAxis(id='1360', ...)],

lod_factor = 10,

lod_interval = 300,

lod_threshold = 2000,

lod_timeout = 500,

margin = (0, 0, 0, 0),

match_aspect = False,

max_height = None,

max_width = None,

min_border = 5,

min_border_bottom = None,

min_border_left = None,

min_border_right = None,

min_border_top = None,

min_height = None,

min_width = None,

name = None,

outer_height = 0,

outer_width = 0,

outline_line_alpha = 1.0,

outline_line_cap = 'butt',

outline_line_color = '#e5e5e5',

outline_line_dash = [],

outline_line_dash_offset = 0,

outline_line_join = 'bevel',

outline_line_width = 1,

output_backend = 'canvas',

renderers = [GlyphRenderer(id='1386', ...), GlyphRenderer(id='1393', ...), GlyphRenderer(id='1400', ...), GlyphRenderer(id='1407', ...), GlyphRenderer(id='1414', ...), GlyphRenderer(id='1421', ...)],

reset_policy = 'standard',

right = [Legend(id='1380', ...)],

sizing_mode = 'scale_width',

subscribed_events = [],

syncable = True,

tags = [],

title = Title(id='1460', ...),

title_location = 'above',

toolbar = Toolbar(id='1372', ...),

toolbar_location = 'above',

toolbar_sticky = True,

visible = True,

width = 800,

width_policy = 'auto',

x_range = DataRange1d(id='1348', ...),

x_scale = LinearScale(id='1352', ...),

y_range = DataRange1d(id='1350', ...),

y_scale = LinearScale(id='1354', ...))

Furthermore, the MS1 elution can also be shown.

sqMassLoader.plotChromatogram("NKESPT(UniMod:21)KAIVR(UniMod:267)", 3, include_ms1=True)

Loading BokehJS ...

Figure(

id = '1591', …)

above = [Legend(id='1759', ...)],

align = 'start',

aspect_ratio = None,

aspect_scale = 1,

background = None,

background_fill_alpha = 1.0,

background_fill_color = '#ffffff',

below = [LinearAxis(id='1600', ...)],

border_fill_alpha = 1.0,

border_fill_color = '#ffffff',

center = [Grid(id='1603', ...), Grid(id='1607', ...)],

css_classes = [],

disabled = False,

extra_x_ranges = {},

extra_x_scales = {},

extra_y_ranges = {},

extra_y_scales = {},

frame_height = None,

frame_width = None,

height = 450,

height_policy = 'auto',

hidpi = True,

inner_height = 0,

inner_width = 0,

js_event_callbacks = {},

js_property_callbacks = {},

left = [LinearAxis(id='1604', ...)],

lod_factor = 10,

lod_interval = 300,

lod_threshold = 2000,

lod_timeout = 500,

margin = (0, 0, 0, 0),

match_aspect = False,

max_height = None,

max_width = None,

min_border = 5,

min_border_bottom = None,

min_border_left = None,

min_border_right = None,

min_border_top = None,

min_height = None,

min_width = None,

name = None,

outer_height = 0,

outer_width = 0,

outline_line_alpha = 1.0,

outline_line_cap = 'butt',

outline_line_color = '#e5e5e5',

outline_line_dash = [],

outline_line_dash_offset = 0,

outline_line_join = 'bevel',

outline_line_width = 1,

output_backend = 'canvas',

renderers = [GlyphRenderer(id='1630', ...), GlyphRenderer(id='1637', ...), GlyphRenderer(id='1644', ...), GlyphRenderer(id='1651', ...), GlyphRenderer(id='1658', ...), GlyphRenderer(id='1665', ...), GlyphRenderer(id='1672', ...), GlyphRenderer(id='1686', ...), GlyphRenderer(id='1692', ...), GlyphRenderer(id='1698', ...), GlyphRenderer(id='1705', ...), GlyphRenderer(id='1711', ...), GlyphRenderer(id='1717', ...), GlyphRenderer(id='1724', ...), GlyphRenderer(id='1730', ...), GlyphRenderer(id='1736', ...), GlyphRenderer(id='1743', ...), GlyphRenderer(id='1749', ...), GlyphRenderer(id='1755', ...)],

reset_policy = 'standard',

right = [Legend(id='1624', ...)],

sizing_mode = 'scale_width',

subscribed_events = [],

syncable = True,

tags = [],

title = Title(id='1814', ...),

title_location = 'above',

toolbar = Toolbar(id='1616', ...),

toolbar_location = 'above',

toolbar_sticky = True,

visible = True,

width = 800,

width_policy = 'auto',

x_range = DataRange1d(id='1592', ...),

x_scale = LinearScale(id='1596', ...),

y_range = DataRange1d(id='1594', ...),

y_scale = LinearScale(id='1598', ...))

Note

Boundaries shown are directly copied from the the OpenSwath output and are not effected by changing smoothing parameters.

MzML Visualization

Chromatograms can also be extracted on the fly from .mzML files. This is useful for visualizing how a chromatogram would appear if different extraction parameters were used and if chromatograms were not saved upon data analysis.

First we must initiate a MzMLDataLoader which links a .mzML file with a results file and a library file. Currently supported results files include .osw and a DIA-NN .tsv report. We can link multiple result files in a single loader object in order to compare the features across software tools as shown below.

from massdash.loaders import MzMLDataLoader
mzml_loader = MzMLDataLoader(rsltsFile=["example_dia/diann/report/test_1_diann_report.tsv", "example_dia/openswath/osw/test.osw"],
                            dataFiles="example_dia/raw/test_raw_1.mzML",
                            libraryFile="example_dia/diann/lib/test_1_lib.tsv")

Initializing valid scores for selection
[2024-10-10 13:02:19,790] MzMLDataAccess - INFO - Opening example_dia/raw/test_raw_1.mzML file...: Elapsed 0.3596317768096924 ms
[2024-10-10 13:02:19,791] MzMLDataAccess - INFO - There are 3867 spectra and 1 chromatograms.
[2024-10-10 13:02:19,805] MzMLDataAccess - INFO - There are 117 MS1 spectra and 3750 MS2 spectra.

Now we can plot each of these using the plotChromatogram() function. Here, we must also specify extraction parameters such as mz_tol (in ppm) and rt_window (in seconds).

mzml_loader.plotChromatogram("DYASIDAAPEER", 2, mz_tol=20, rt_window=200, im_window=None, smooth=True)

Loading BokehJS ...

Figure(

id = '2005', …)

above = [Legend(id='2191', ...)],

align = 'start',

aspect_ratio = None,

aspect_scale = 1,

background = None,

background_fill_alpha = 1.0,

background_fill_color = '#ffffff',

below = [LinearAxis(id='2014', ...)],

border_fill_alpha = 1.0,

border_fill_color = '#ffffff',

center = [Grid(id='2017', ...), Grid(id='2021', ...)],

css_classes = [],

disabled = False,

extra_x_ranges = {},

extra_x_scales = {},

extra_y_ranges = {},

extra_y_scales = {},

frame_height = None,

frame_width = None,

height = 450,

height_policy = 'auto',

hidpi = True,

inner_height = 0,

inner_width = 0,

js_event_callbacks = {},

js_property_callbacks = {},

left = [LinearAxis(id='2018', ...)],

lod_factor = 10,

lod_interval = 300,

lod_threshold = 2000,

lod_timeout = 500,

margin = (0, 0, 0, 0),

match_aspect = False,

max_height = None,

max_width = None,

min_border = 5,

min_border_bottom = None,

min_border_left = None,

min_border_right = None,

min_border_top = None,

min_height = None,

min_width = None,

name = None,

outer_height = 0,

outer_width = 0,

outline_line_alpha = 1.0,

outline_line_cap = 'butt',

outline_line_color = '#e5e5e5',

outline_line_dash = [],

outline_line_dash_offset = 0,

outline_line_join = 'bevel',

outline_line_width = 1,

output_backend = 'canvas',

renderers = [GlyphRenderer(id='2044', ...), GlyphRenderer(id='2051', ...), GlyphRenderer(id='2058', ...), GlyphRenderer(id='2065', ...), GlyphRenderer(id='2072', ...), GlyphRenderer(id='2079', ...), GlyphRenderer(id='2086', ...), GlyphRenderer(id='2093', ...), GlyphRenderer(id='2100', ...), GlyphRenderer(id='2107', ...), GlyphRenderer(id='2114', ...), GlyphRenderer(id='2121', ...), GlyphRenderer(id='2128', ...), GlyphRenderer(id='2135', ...), GlyphRenderer(id='2156', ...), GlyphRenderer(id='2162', ...), GlyphRenderer(id='2168', ...), GlyphRenderer(id='2175', ...), GlyphRenderer(id='2181', ...), GlyphRenderer(id='2187', ...)],

reset_policy = 'standard',

right = [Legend(id='2038', ...)],

sizing_mode = 'scale_width',

subscribed_events = [],

syncable = True,

tags = [],

title = Title(id='2275', ...),

title_location = 'above',

toolbar = Toolbar(id='2030', ...),

toolbar_location = 'above',

toolbar_sticky = True,

visible = True,

width = 800,

width_policy = 'auto',

x_range = DataRange1d(id='2006', ...),

x_scale = LinearScale(id='2010', ...),

y_range = DataRange1d(id='2008', ...),

y_scale = LinearScale(id='2012', ...))

Visualizing Chromatograms Across Files

plotChromatogram() can also be supplied with multiple results file and data files. However, one of the results files supplied must always be a .osw file.

from massdash.loaders import SqMassLoader
sqMassLoader = SqMassLoader(rsltsFile='osw/test_data.osw', dataFiles=['xics/test_chrom_1.sqMass', 'xics/test_chrom_2.sqMass'])

Initializing valid scores for selection

Currently, plotChromatogram() only supports visualization of a single run. Thus if multiple data files are supplied like above, the runName must also be specified. The runName is the name of the file without the extension, e.g. test_chrom_2

sqMassLoader.plotChromatogram("NKESPT(UniMod:21)KAIVR(UniMod:267)", 3, runName='test_chrom_2', includeBoundaries=False)

Loading BokehJS ...

Figure(

id = '2526', …)

above = [],

align = 'start',

aspect_ratio = None,

aspect_scale = 1,

background = None,

background_fill_alpha = 1.0,

background_fill_color = '#ffffff',

below = [LinearAxis(id='2535', ...)],

border_fill_alpha = 1.0,

border_fill_color = '#ffffff',

center = [Grid(id='2538', ...), Grid(id='2542', ...)],

css_classes = [],

disabled = False,

extra_x_ranges = {},

extra_x_scales = {},

extra_y_ranges = {},

extra_y_scales = {},

frame_height = None,

frame_width = None,

height = 450,

height_policy = 'auto',

hidpi = True,

inner_height = 0,

inner_width = 0,

js_event_callbacks = {},

js_property_callbacks = {},

left = [LinearAxis(id='2539', ...)],

lod_factor = 10,

lod_interval = 300,

lod_threshold = 2000,

lod_timeout = 500,

margin = (0, 0, 0, 0),

match_aspect = False,

max_height = None,

max_width = None,

min_border = 5,

min_border_bottom = None,

min_border_left = None,

min_border_right = None,

min_border_top = None,

min_height = None,

min_width = None,

name = None,

outer_height = 0,

outer_width = 0,

outline_line_alpha = 1.0,

outline_line_cap = 'butt',

outline_line_color = '#e5e5e5',

outline_line_dash = [],

outline_line_dash_offset = 0,

outline_line_join = 'bevel',

outline_line_width = 1,

output_backend = 'canvas',

renderers = [GlyphRenderer(id='2565', ...), GlyphRenderer(id='2572', ...), GlyphRenderer(id='2579', ...), GlyphRenderer(id='2586', ...), GlyphRenderer(id='2593', ...), GlyphRenderer(id='2600', ...)],

reset_policy = 'standard',

right = [Legend(id='2559', ...)],

sizing_mode = 'scale_width',

subscribed_events = [],

syncable = True,

tags = [],

title = Title(id='2732', ...),

title_location = 'above',

toolbar = Toolbar(id='2551', ...),

toolbar_location = 'above',

toolbar_sticky = True,

visible = True,

width = 800,

width_policy = 'auto',

x_range = DataRange1d(id='2527', ...),

x_scale = LinearScale(id='2531', ...),

y_range = DataRange1d(id='2529', ...),

y_scale = LinearScale(id='2533', ...))

MzMLDataLoader can also be supplied with multiple .mzML as shown below.

from massdash.loaders import MzMLDataLoader
mzml_loader = MzMLDataLoader(rsltsFile=["example_dia/diann/report/test_diann_report_combined.tsv", "example_dia/openswath/osw/test.osw"],
                            dataFiles=["example_dia/raw/test_raw_1.mzML", "example_dia/raw/test_raw_2.mzML"],
                            libraryFile="example_dia/diann/lib/test_2_lib.tsv")

Initializing valid scores for selection
[2024-10-10 13:02:20,817] MzMLDataAccess - INFO - Opening example_dia/raw/test_raw_1.mzML file...: Elapsed 0.31288671493530273 ms
[2024-10-10 13:02:20,818] MzMLDataAccess - INFO - There are 3867 spectra and 1 chromatograms.
[2024-10-10 13:02:20,836] MzMLDataAccess - INFO - There are 117 MS1 spectra and 3750 MS2 spectra.
[2024-10-10 13:02:21,181] MzMLDataAccess - INFO - Opening example_dia/raw/test_raw_2.mzML file...: Elapsed 0.33651185035705566 ms
[2024-10-10 13:02:21,182] MzMLDataAccess - INFO - There are 3867 spectra and 1 chromatograms.
[2024-10-10 13:02:21,198] MzMLDataAccess - INFO - There are 117 MS1 spectra and 3750 MS2 spectra.

mzml_loader.plotChromatogram("DYASIDAAPEER", 2,
                             mz_tol=20, rt_window=200, im_window=None,
                             runName='test_raw_2', includeBoundaries=True)

Loading BokehJS ...

[2024-10-10 13:02:21,594] InteractivePlotter - WARNING - prec is empty, Returning 0.
[2024-10-10 13:02:21,598] InteractivePlotter - WARNING - prec is empty, Returning 0.

Figure(

id = '2863', …)

above = [Legend(id='3049', ...)],

align = 'start',

aspect_ratio = None,

aspect_scale = 1,

background = None,

background_fill_alpha = 1.0,

background_fill_color = '#ffffff',

below = [LinearAxis(id='2872', ...)],

border_fill_alpha = 1.0,

border_fill_color = '#ffffff',

center = [Grid(id='2875', ...), Grid(id='2879', ...)],

css_classes = [],

disabled = False,

extra_x_ranges = {},

extra_x_scales = {},

extra_y_ranges = {},

extra_y_scales = {},

frame_height = None,

frame_width = None,

height = 450,

height_policy = 'auto',

hidpi = True,

inner_height = 0,

inner_width = 0,

js_event_callbacks = {},

js_property_callbacks = {},

left = [LinearAxis(id='2876', ...)],

lod_factor = 10,

lod_interval = 300,

lod_threshold = 2000,

lod_timeout = 500,

margin = (0, 0, 0, 0),

match_aspect = False,

max_height = None,

max_width = None,

min_border = 5,

min_border_bottom = None,

min_border_left = None,

min_border_right = None,

min_border_top = None,

min_height = None,

min_width = None,

name = None,

outer_height = 0,

outer_width = 0,

outline_line_alpha = 1.0,

outline_line_cap = 'butt',

outline_line_color = '#e5e5e5',

outline_line_dash = [],

outline_line_dash_offset = 0,

outline_line_join = 'bevel',

outline_line_width = 1,

output_backend = 'canvas',

renderers = [GlyphRenderer(id='2902', ...), GlyphRenderer(id='2909', ...), GlyphRenderer(id='2916', ...), GlyphRenderer(id='2923', ...), GlyphRenderer(id='2930', ...), GlyphRenderer(id='2937', ...), GlyphRenderer(id='2944', ...), GlyphRenderer(id='2951', ...), GlyphRenderer(id='2958', ...), GlyphRenderer(id='2965', ...), GlyphRenderer(id='2972', ...), GlyphRenderer(id='2979', ...), GlyphRenderer(id='2986', ...), GlyphRenderer(id='2993', ...), GlyphRenderer(id='3014', ...), GlyphRenderer(id='3020', ...), GlyphRenderer(id='3026', ...), GlyphRenderer(id='3033', ...), GlyphRenderer(id='3039', ...), GlyphRenderer(id='3045', ...)],

reset_policy = 'standard',

right = [Legend(id='2896', ...)],

sizing_mode = 'scale_width',

subscribed_events = [],

syncable = True,

tags = [],

title = Title(id='3195', ...),

title_location = 'above',

toolbar = Toolbar(id='2888', ...),

toolbar_location = 'above',

toolbar_sticky = True,

visible = True,

width = 800,

width_policy = 'auto',

x_range = DataRange1d(id='2864', ...),

x_scale = LinearScale(id='2868', ...),

y_range = DataRange1d(id='2866', ...),

y_scale = LinearScale(id='2870', ...))

More Information

For more details on the implementation please checkout the Python API.