Mass spectrometry data visualization is essential for a wide range of applications, such as validation of workflows and results, benchmarking new algorithms, and creating comprehensive quality control reports. Python offers a popular and powerful framework for analyzing and visualizing multidimensional data; however, generating commonly used mass spectrometry plots in Python can be cumbersome. Here we present pyOpenMS-viz, a versatile, unified framework for generating mass spectrometry plots. pyOpenMS-viz directly extends pandas DataFrame plotting for generating figures in a single line of code. This implementation enables easy integration across various Python-based mass spectrometry tools that already use pandas DataFrames to store MS data. pyOpenMS-viz is open-source under a BSD 3-Clause license and freely available at https://github.com/OpenMS/pyopenms_viz.
Research Article
pyOpenMS-viz: Streamlining Mass Spectrometry Data Visualization with pandas
https://doi.org/10.21203/rs.3.rs-5166557/v1
This work is licensed under a CC BY 4.0 License
Version 1
posted
You are reading this latest preprint version
In omics-based mass spectrometry (MS) analysis, it is routine to couple multiple instruments, including liquid chromatography, multiple mass analyzers, and ion mobility spectrometry, to maximize selectivity. 1,2 This integration, however, results in complex multidimensional datasets that are challenging to interpret. Consequently, effective data visualization is crucial for accurately interpreting MS datasets, validating workflows and results, benchmarking new algorithms, generating comprehensive quality control reports, and supporting the development of novel algorithms. While there are established and high-performant software tools for mass spectrometry visualization3,4, these solutions come with steep learning curves, are tailored to specific data analysis workflows, or are not designed with extensibility in mind. This lack of flexibility makes it difficult to adapt these visualization tools for novel algorithm development or to integrate them seamlessly into diverse analytical or quality control pipelines.
Over the past decade, the Python programming language has become a leading tool for data analysis and machine learning. Many mass spectrometry software tools such as pyOpenMS 5 , Pyteomics6, spectrum_utils7,8, and the Alpha Ecosystem9 have been developed facilitating rapid algorithm development. However, despite Python's extensive ecosystem for both static and interactive data visualization10–12, existing tools often prioritize data processing and analysis, offering only limited support for advanced and broadly applicable plotting capabilities. Feature-rich plots including, spectra, chromatograms, peak maps and mobilograms required for mass spectrometry data visualization are cumbersome to generate, require a substantial amount of code, or can be challenging to produce, especially for new users not familiar with the technical details of different plotting libraries. Here we present pyOpenMS-viz, a flexible, unified Python module designed for rapid mass spectrometry data visualization. pyOpenMS-viz enables users to generate common MS plots with typically a single line of code directly from a pandas DataFrame13, a widely-used data format already supported by many Python-based MS-tools. pyOpenMS-viz seamlessly integrates into the existing MS-based Python ecosystem, offering significant value for use in both Jupyter Notebooks and web applications. In the following sections, we briefly outline the architecture and design decisions of pyOpenMS-viz and demonstrate how it can be effectively utilized across various development environments to quickly produce commonly used visualizations.
The core design of pyOpenMS-viz is an application programming interface (API) library that supports modular plotting backend implementations (currently supported: Matplotlib, Bokeh, Plotly). While its inner workings are hidden from the end user, pyOpenMS-viz internally defines an abstract base class, BasePlot, as the foundation for all visualization objects in the pyOpenMS-viz library. BasePlot defines the methods that must be implemented by each supported backend to achieve a consistent interface across the different plotting libraries. The package offers simple building block plots (such as LinePlot and ScatterPlot) and mass spectrometry-specific plots (such as ChromatogramPlot and SpectrumPlot) that inherit from the BaseMSPlot abstract class. To accommodate the different user requirements regarding the plotting library, each optional backend is implemented in a separate module. Backend-specific modules inherit from BasePlot and implement their abstract methods using the respective library’s API. For example, the Bokeh backend (BOKEHPlot) inherits from BasePlot and implements the required methods using Bokeh's API. This ensures that plots need to be defined only once, independently of the plotting backend, after the underlying simple plots have been implemented, thereby facilitating the addition of additional plotting backends. In practice, the user does not come into contact with the technical details of the internal implementation because pyOpenMS-viz integrates with the pandas plot function. By extending the pandas plotting interface, MS figures can be generated directly from a DataFrame (in tabular long-format) using the familiar pandas plotting syntax. Users are required to specify the kind of plot, and column names corresponding with the DataFrame columns to be plotted. Additionally, the user must also specify a plotting backend (one of ‘ms_bokeh’, ‘ms_matplotlib’ and ‘ms_plotly’). For example, plotting a chromatogram using bokeh is achieved by the following call `df.plot(kind='chromatogram', x='retention_time', y='intensity', backend='ms_bokeh')`. Currently supported plots include the mass spectra, chromatograms, mobilograms and peak maps.
Gallery visualizations are generated from a diaPASEF HeLa-Yeast two-proteome dataset described in Meier, F. et. al. 2021. 14 Data was processed as stated in Sing. JC., Charkow., J. et. al. 2024.15 Visualization depicted in the StreamSage web application is DDA data from Shen, X. et. al. 2018.16 Search result configuration parameters were used as described in Lazear, M. 2023.17
Pandas DataFrames are commonly used for representing MS data in a tabular structure. Mass spectrometry data is typically loaded from a raw experiment file (i.e., mzML, d, raw, wiff) into a DataFrame object using a library capable of accessing the raw data (Figure 1, Listing 1-4).6,18–20 Further preprocessing and data manipulation such as filtering, smoothing or peak picking can easily be performed directly on the pandas DataFrame before plotting. pyOpenMS-viz has been designed to make the plotting of MS data as accessible as possible. At its core, pyOpenMS-viz extends the pandas API, allowing users to directly plot mass spectrometry data from a DataFrame with just a single line of code, lowering the learning curve and encouraging visual data exploration (Figure 1). Users can specify which columns of the DataFrame to plot and how to group data across all plot types. This reduces the need for strict column naming conventions or data reformatting, simplifying the visualization process without affecting upstream data processing tools. This structure allows plots to be easily adapted to alternative data dimensions, such as ion mobility.
Figure 1: pyOpenMS-viz is a flexible plotting platform for mass spectrometry data visualization. pyOpenMS-viz is a Python-based visualization tool allowing for compatibility with a wide variety of pre-existing mass spectrometry tools. pyOpenMS-viz extends the build-in plotting module of pandas, a widely used data analysis and manipulation tool, already commonly used in the mass spectrometry Python ecosystem. This allows for direct plotting of DataFrames. pyOpenms-viz only uses user-specified columns meaning that users can store additional custom metadata not used in plotting. Currently supported plot types include spectrum, peak map, mobilogram and chromatograms. Supported backends include Matplotlib, Bokeh and Plotly, allowing both static and interactive visualization.
Table 1 Overview of Plot Types Supported. PyOpenMS-viz supports a diverse set of mass spectrometry plots across different backends to support the generation of both interactive and publication quality plots. All plots are supported across all backends with the exception of a peak map 3D since Bokeh backend has limited support for 3D visualizations. Visualizations of these plots across different backends can be found in Figure S2.
The class-based architecture (Supplemental Figure 1) also ensures a consistent API across diverse plotting backends. This allows users to easily switch between generating static figures with Matplotlib or interactive figures with Bokeh or Plotly by simply changing a single parameter (Supp. Figure 2, Listing 5). pyOpenMS-viz is designed to work well in different environments (Figure 2). In script-based workflows, it facilitates the generation of static, publication quality figures using Matplotlib for single files or while batch processing large data sets (Supp. Figure 3). Within Jupyter notebooks, researchers can adopt a workflow to process and visually explore their data. Sharing their notebook along with visualizations is a convenient way to share results and can increase reproducibility. pyOpenMS-viz can easily be integrated in Python-based web applications to create interactive visualization tools that allow users to explore MS data online. Because the package works the same way across these different setups, it simplifies the learning process for users and empowers them to use it in different contexts. The currently supported plots include spectra, chromatograms, mobilograms and peak maps (Table 1, Figure 1), which are further explained below.
In mass spectrometry, the spectrum plot is widely used to verify the identity of an analyte. It visualizes recorded ion intensities (e.g., the measured ion current) distributed over a mass-to-charge (m/z) dimension. A common use case is the visualization of annotated tandem mass spectra for verifying analyte identification or intensity ratios in label-based quantification workflows (Figure 3a). pyOpenMS-viz spectrum plots leverage the groupby functionality to group and color peaks based on annotation. pyOpenMS-viz also supports custom peak annotations, including text labels to highlight peaks of interest, mirror spectrum plots for comparing an experimental spectrum to another one (e.g., from spectral libraries or fragment intensity predictions) (Supp. Figure 4, Listing 6). Furthermore, to speed up plotting, pyOpenMS-viz bins peaks to reduce the number of peaks rendered (Listing 7).
Chromatogram plots are commonly used to visualize the total ion current detected in a mass spectrometer or elution profiles of analyte(s) tracked over retention time. In targeted experiments, a chromatogram of multiple mass traces is frequently inspected to verify the identification and quantification quality. pyOpenMS-viz supports grouping of mass traces using the pandas groupby functionality. Grouped mass traces get plotted with different colors in the same plot (Figure 3b, Supp. Figure 4, Listing 6). pyOpenMS-viz allows users to manually select and group column names of the same DataFrame to achieve different types of visualizations (Figure 3b, Supp. Figure 4, Listing 6). Furthermore, peak boundaries can optionally be supplied in an additional pandas DataFrame for annotation allowing for validation of automated peak-picking tools like OpenSwath21 or DIA-NN22 (Listing 8). Plots can easily be adapted to plot alternative dimensions such as ion mobility. As an example, we include the Mobilogram plot class which is a modified version of the chromatogram plot for visualizing ion mobility data in PASEF workflows (Figure 3c).
Sometimes, visualization across a single dimension is not sufficient for quality control, and visualization across two or more dimensions is required. For example, feature detection algorithms may detect eluting analytes in retention time and m/z dimensions or additional dimensions of separation such as ion mobility can produce multidimensional spectra. Peak maps allow plotting peak data along both dimensions using color-coded intensities, producing a plot that resembles a heatmap (Figure 3d-f). Since peak maps commonly display large amounts of data which can be slow in a Python plotting environment, pyOpenMS-viz supports dynamic peak binning to display large amounts of data in a performant manner, without much loss of visual information (Listing 7). Peak maps can also be plotted with marginal plots, such that a chromatogram representing the total ion current and a merged spectrum of the visible area is included on the marginals (Figure 3g-i). In addition to the heatmap-like 2D view, peak maps can also be displayed in a 3D format. In this view, intensity is represented as a third dimension, allowing for a clearer and more detailed representation of the data, particularly of elution profiles and isotopic peaks in a single plot. (Figure 3j-l, Supp. Figure 4).
pyOpenMS-viz is a unified, flexible plotting API to rapidly generate commonly used mass spectrometry plots such as spectra, chromatograms, mobilograms, and peak maps. Its modular nature allows it to be easily extended to support novel plot types or visualization backends. pyOpenMS-viz works well in many Python development environments, such as Jupyter Notebooks and Streamlit WebApps and can be utilized in MS-based research to inspect and validate results, benchmark tools, perform quality control, and support the development of novel algorithms. In addition, the combination of Jupyter Notebooks and pyOpenMS-viz serves as an ideal platform for teaching computational or general mass spectrometry-related concepts, offering interactive and visual learning experiences. Since pandas DataFrames are already widely adopted in the MS-Python community, we expect that pyOpenMS-viz will integrate seamlessly into existing workflows. We are aware that using pandas DataFrames introduces some data redundancy, trading maximum performance for ease of use. However, this trade-off aligns with our primary goal of making MS data plotting more accessible. Moving forward, we envision pyOpenMS-viz to be a base plotting package for different Python-based mass spectrometry workflows, including integration into web apps or other Python applications.As a community-driven project, we warmly welcome discussions regarding novel features and performance enhancements. Additionally, we welcome external contributions to enhance the functionality of pyOpenMS-viz.
Data Availability
The diaPASEF dataset used for generating the example Jupyter notebook and gallery figures can be retrieved from PRIDE with the following accession, PXD017703. Data used to showcase pyOpenMS-viz integration into the StreamSage web application can be retrieved from PRIDE with the following accession, PXD003881. The pyOpenMS-viz library is open source and freely available under a BSD-3 clause license on GitHub (https://github.com/OpenMS/pyopenms_viz), and available via the PyPi repository. The example StreamSage web application built with OpenMS WebApps Template (https://github.com/OpenMS/streamlit-template) is available on GitHub at: https://github.com/singjc/StreamSage.
Contributions
J.C.S., J.C., A.W. and T.S. designed the study. J.C.S., J.C. and A.W. designed and developed the software. M.G. and T.D.M. contributed to figure generation and testing of the library. H.L.R. and T.S. supervised the project. All authors contributed to the writing of the manuscript. All authors read and approved the final manuscript.
Competing Interests
T.S. is an officer in OpenMS Inc., a non-profit foundation that manages the international coordination of OpenMS development. All remaining authors declare no competing interests.
Acknowledgments
J.C.S. was supported by the European Research Area Network Personalized Medicine Cofund (PerProGlio, #506078) and CIHR (#507496). J.C. was supported by CIHR (#507496) and the Ontario Graduate Scholarship. A.W. was supported by de.NBI (Bioinformatics Infrastructure, Baden-Württemberg). M.G. was supported by CIHR (#507496). T.S. acknowledges funding by the Federal Ministry of Education and Research in the frame of de.NBI/ELIXIR-DE (W-de.NBI-022) and is supported by the Ministry of Science, Research and Arts Baden-Württemberg. We would like to thank Dr. Yasset Perez-Riverol for their valuable feedback and insightful comments.
- Venter, P., Muller, M., Vestner, J., Stander, M. A., Tredoux, A. G. J., Pasch, H., & de Villiers, A. (2018). Comprehensive Three-Dimensional LC × LC × Ion Mobility Spectrometry Separation Combined with High-Resolution MS for the Analysis of Complex Samples. Analytical Chemistry, 90(19), 11643–11650. https://doi.org/10.1021/acs.analchem.8b03234
- D’Atri, V., Causon, T., Hernandez-Alba, O., Mutabazi, A., Veuthey, J.-L., Cianferani, S., & Guillarme, D. (2018). Adding a new separation dimension to MS and LC–MS: What is the utility of ion mobility spectrometry? Journal of Separation Science, 41(1), 20–67. https://doi.org/10.1002/jssc.201700919
- MacLean, B., Tomazela, D. M., Shulman, N., Chambers, M., Finney, G. L., Frewen, B., Kern, R., Tabb, D. L., Liebler, D. C., & MacCoss, M. J. (2010). Skyline: An open source document editor for creating and analyzing targeted proteomics experiments. Bioinformatics, 26(7), 966–968. https://doi.org/10.1093/bioinformatics/btq054
- Sturm, M., & Kohlbacher, O. (2009). TOPPView: An Open-Source Viewer for Mass Spectrometry Data. Journal of Proteome Research, 8(7), 3760–3763. https://doi.org/10.1021/pr900171m
- Röst, H. L., Schmitt, U., Aebersold, R., & Malmström, L. (2014). pyOpenMS: A Python-based interface to the OpenMS mass-spectrometry algorithm library. PROTEOMICS, 14(1), 74–77. https://doi.org/10.1002/pmic.201300246
- Levitsky, L. I., Klein, J. A., Ivanov, M. V., & Gorshkov, M. V. (2019). Pyteomics 4.0: Five Years of Development of a Python Proteomics Framework. Journal of Proteome Research, 18(2), 709–714. https://doi.org/10.1021/acs.jproteome.8b00717
- Bittremieux, W. (2020). spectrum_utils: A Python Package for Mass Spectrometry Data Processing and Visualization. Analytical Chemistry, 92(1), 659–661. https://doi.org/10.1021/acs.analchem.9b04884
- Bittremieux, W., Levitsky, L., Pilz, M., Sachsenberg, T., Huber, F., Wang, M., & Dorrestein, P. C. (2023). Unified and Standardized Mass Spectrometry Data Processing in Python Using spectrum_utils. Journal of Proteome Research, 22(2), 625–631. https://doi.org/10.1021/acs.jproteome.2c00632
- Zeng, W.-F., Zhou, X.-X., Willems, S., Ammar, C., Wahle, M., Bludau, I., Voytik, E., Strauss, M. T., & Mann, M. (2022). AlphaPeptDeep: A modular deep learning framework to predict peptide properties for proteomics. Nature Communications, 13(1), 7238. https://doi.org/10.1038/s41467-022-34904-3
- Bokeh Development Team. (2018). Bokeh: Python library for interactive visualization. https://bokeh.pydata.org/en/latest/
- Inc, P. T. (2015). Collaborative data science. Plotly Technologies Inc. https://plot.ly
- Hunter, J. D. (2007). Matplotlib: A 2D Graphics Environment. Computing in Science & Engineering, 9(3), 90–95. Computing in Science & Engineering. https://doi.org/10.1109/MCSE.2007.55
- The pandas development team. (2024). pandas-dev/pandas: Pandas (Version v2.2.3) [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.13819579
- Meier, F., Brunner, A.-D., Frank, M., Ha, A., Bludau, I., Voytik, E., Kaspar-Schoenefeld, S., Lubeck, M., Raether, O., Bache, N., Aebersold, R., Collins, B. C., Röst, H. L., & Mann, M. (2020). diaPASEF: Parallel accumulation–serial fragmentation combined with data-independent acquisition. Nature Methods, 17(12), Article 12. https://doi.org/10.1038/s41592-020-00998-0
- Sing, J. C., Charkow, J., AlHigaylan, M., Horecka, I., Xu, L., & Röst, H. L. (2024). MassDash: A Web-Based Dashboard for Data-Independent Acquisition Mass Spectrometry Visualization. Journal of Proteome Research, 23(6), 2306–2314. https://doi.org/10.1021/acs.jproteome.4c00026
- Shen, X., Shen, S., Li, J., Hu, Q., Nie, L., Tu, C., Wang, X., Poulsen, D. J., Orsburn, B. C., Wang, J., & Qu, J. (2018). IonStar enables high-precision, low-missing-data proteomics quantification in large biological cohorts. Proceedings of the National Academy of Sciences, 115(21), E4767–E4776. https://doi.org/10.1073/pnas.1800541115
- Lazear, M. R. (2023). Sage: An Open-Source Tool for Fast Proteomics Searching and Quantification at Scale. Journal of Proteome Research, 22(11), 3652–3659. https://doi.org/10.1021/acs.jproteome.3c00486
- Pfeuffer, J., Bielow, C., Wein, S., Jeong, K., Netz, E., Walter, A., Alka, O., Nilse, L., Colaianni, P. D., McCloskey, D., Kim, J., Rosenberger, G., Bichmann, L., Walzer, M., Veit, J., Boudaud, B., Bernt, M., Patikas, N., Pilz, M., … Sachsenberg, T. (2024). OpenMS 3 enables reproducible analysis of large-scale mass spectrometry data. Nature Methods, 21(3), 365–367. https://doi.org/10.1038/s41592-024-02197-7
- Bald, T., Barth, J., Niehues, A., Specht, M., Hippler, M., & Fufezan, C. (2012). pymzML—Python module for high-throughput bioinformatics on mass spectrometry data. Bioinformatics, 28(7), 1052–1053. https://doi.org/10.1093/bioinformatics/bts066
- Willems, S., Voytik, E., Skowronek, P., Strauss, M. T., & Mann, M. (2021). AlphaTims: Indexing Trapped Ion Mobility Spectrometry–TOF Data for Fast and Easy Accession and Visualization. Molecular & Cellular Proteomics, 20, 100149. https://doi.org/10.1016/j.mcpro.2021.100149
- Röst, H. L., Rosenberger, G., Navarro, P., Gillet, L., Miladinović, S. M., Schubert, O. T., Wolski, W., Collins, B. C., Malmström, J., Malmström, L., & Aebersold, R. (2014). OpenSWATH enables automated, targeted analysis of data-independent acquisition MS data. Nature Biotechnology, 32(3), Article 3. https://doi.org/10.1038/nbt.2841
- Demichev, V., Messner, C. B., Vernardis, S. I., Lilley, K. S., & Ralser, M. (2020). DIA-NN: Neural networks and interference correction enable deep proteome coverage in high throughput. Nature Methods, 17(1), Article 1. https://doi.org/10.1038/s41592-019-0638-x
The authors declare potential competing interests as follows: T.S. is an officer in OpenMS Inc., a non-profit foundation that manages the international coordination of OpenMS development. All remaining authors declare no competing interests.
- StreamliningMassSpectrometryDataVisualizationwithPandasSupplementInformation.docx
pyOpenMS-viz: Streamlining Mass Spectrometry Data Visualization with pandas Supplemental Information Supporting Information The following supporting information is available free of charge at ACS website href="http://pubs.acs.org/">http://pubs.acs.org Supplemental Figure S1. - Pyopenms implements an abstract architecture to support different backends. Supplemental Figure S2. - Overview of pyOpenMS-viz plots across different backends. Supplemental Figure S3. - Creating Complex Publication Quality Figures with pyOpenMS-viz. Supplemental Figure S4. - Gallery Showcasing Figure Customizability. Listing 1. - Loading mzML data with pyopenms and plotting. Listing 2. - Loading mzML data with pyteomics and plotting. Listing 3. - Loading mzML data with pymzml and plotting. Listing 4. - Loading Bruker .d data with alphatims and plotting. Listing 5. - Versatility of Integrated pyOpenMS-viz and pandas Plotting. Listing 6. - Flexibility and Configurability. Listing 7. - Data Processing and Plotting. Listing 8. - Advanced Plotting Features.