masster

MASSter is a Python package for the analysis of metabolomics experiments by LC-MS/MS data, with a main focus on the challenging tasks of untargeted and large-scale studies. MASSter is actively used, maintained, and developed by the Zamboni Lab at ETH Zurich.

The project started in 2025 and led to a complete makeover, reqriting and integrating multiple tools into a single ecosystem that maximizes performance, includes the newest developments, works equally well across vendors and experiment types (from small to large, DDA and DIA), is suited for automatization, and is free of paywalls, strict licenses, etc.

Masster has become the workhorse for both R&D and routine work. It is in continue development. We decided to make MASSter public primarily for these reasons:

• FAIRification of data processing: We want others to be able to reproduce our results starting from raw data, using fully parameterized scripts that do not depend on human interaction.
• Empowering other labs: To allow other labs to immediately benefit from the latest developments we implement.

Content

MASSter is designed to handle LC-MS/MS data, regardless of whether it is DDA, DIA/SWATH, or DIA/ZTScan. It partly relies on the potent and fast feature detection provided by OpenMS, but the rest was re-engineered: centroiding, RT alignment, adduct and isotopomer detection, merging of multiple samples, gap-filling, quantification, extraction of the best MS2 spectra across the entire study, visualization, and export to mzTab-M, MGF, parquet, etc.

MASSter comes with its own storage format: ".sample5 (for single-file analyses) and *.study5 (for aggregated data). They are HDF5-based formats, which ensure interoperability across platforms and Python versions.

What is not included in MASSter is:

• downstream data analysis: Simple approaches like PCA, UMAP, or ANOVA are integrated for QC, but we didn't include methods for normalization or pathway analysis, etc.
• annotation by MS2 with spectral matching: by design, we outsource MS2 annotation to external tools, like LipidOracle or timaR. Masster has import functions to read the results of annotation and embed them into visualization and export files.
• support for ion mobility, or MS3 data.
• a GUI: we stick to Python scripts. Interactive data exploration is possible by notebooks (Jupyter or Marimo)

Distributions

Two versions exist:

The light version (masster-light) is distributed via PyPI, and allows to read, visualize, filter, export results that were processed by MASSter. The light version does NOT allow to process data, or read from raw files. It's available for any Python 3.11+. This is the recommended version for users that are only interested in the results, or developers that want to directly read sample5 and study5 files.

The full version (masster) is distributed via GitHub, and includes all functionalities, incl. reading from raw or mzML/mz5 data. As reading from vendor formats via .NET builds on pythonnet, the full version is currently only available for Python 3.12-3.14. The full package is licensed separately under the PolyForm Noncommercial License 1.0.0.

Installation

Light version

pip install masster-light
# or
uv add masster-light

Full version

uv add --index https://zamboni-lab.github.io/masster-dist/simple masster
# or
pip install --extra-index-url https://zamboni-lab.github.io/masster-dist/simple masster

Documentation:

Distribution repository: https://github.com/zamboni-lab/masster-dist Wiki: https://github.com/zamboni-lab/masster-dist/wiki Issues: https://github.com/zamboni-lab/masster-dist/issues

Disclaimer

MASSter is research software under active development. While we use it extensively in our lab and strive for quality and reliability, please be aware:

• No warranties: The software is provided "as is" without any warranty of any kind, express or implied.
• Backward compatibility: We do not guarantee backward compatibility between versions. Breaking changes may occur as we improve the software.
• Performance: While optimized for our workflows, performance may vary depending on your data and system configuration.
• Support: This is an academic project with limited resources. At the moment, we do not provide external user support.
• Production use: If you plan to use MASSter in production or critical workflows, thorough testing with your data is recommended.

License

GNU Affero General Public License v3. See the LICENSE file for details. For alternative licensing arrangements, please contact the Zamboni Lab at ETH Zurich.

Third-Party Licenses

This project uses several third-party libraries, including pyOpenMS which is licensed under the BSD 3-Clause License. For complete information about third-party dependencies and their licenses, see THIRD_PARTY_NOTICES.md.

Citation

If you use MASSter in your research, please cite this repository.