Metadata-Version: 2.4
Name: masster-light
Version: 0.10.49
Summary: Lightweight reader/visualizer for masster .sample5/.study5 files
Project-URL: homepage, https://github.com/zamboni-lab/masster-dist
Project-URL: repository, https://github.com/zamboni-lab/masster-dist
Author: Zamboni Lab, ETH Zurich
License: GNU Affero General Public License v3
Keywords: lc-ms,lc-msms,mass spectrometry,metabolomics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU Affero General Public License v3
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: bokeh>=3.0
Requires-Dist: h5py>=3.10
Requires-Dist: numpy>=2.0
Requires-Dist: polars>=0.20
Provides-Extra: excel
Requires-Dist: openpyxl>=3.1; extra == 'excel'
Requires-Dist: pandas>=2.2; extra == 'excel'
Description-Content-Type: text/markdown

# 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](https://github.com/zamboni-lab/masster-dist), 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.11-3.13.

## Installation

### Light version
```bash
pip install masster-light
# or
uv add masster-light
```

### Full version
```bash
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](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](THIRD_PARTY_NOTICES.md).

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