MEDUSA-HR

Machine learning Enabled Deisotoping and Untargeted Spectra Analysis for High-Resolution Mass Spectrometry

This is the extension of the original MEDUSA project for high-resolution mass spectrometry. This project is dedicated to identification of the Pd and some other elements in the high resolution mass-spectra. All the project's functionality will be merged into the original project after the publication of the paper. Extended features like model training and .mzXML files processing will be added after the publication.

How to use it?

To start with MEDUSA, first, install the required packages running. It is recommended to create new virtual environment for this purpose. The whole installation process may spend up to 10 minutes. There is no need for concern.

conda env create -f environment.yml

Or for just python (use python 3.9 and pip 24.0)

pip install -r requirements.txt

Next, install the package permanently using the provided installation script:

conda activate medusa_hr
python install_package.py install

This will create a .pth file in your Python's site-packages directory, making medusa-hr permanently available without needing to modify PYTHONPATH for each session.

Package Installation Management

The install_package.py script provides several commands:

python install_package.py install    # Install medusa-hr permanently
python install_package.py uninstall  # Remove medusa-hr installation  
python install_package.py check      # Check current installation status

To check if the installation is successful, run the following command:

python test_env.py

If you see the "Success" message, the installation is successful.

Simple operations with mass-spectra

To open a spectrum run

from mass_automation.experiment import Experiment

exp = Experiment('/path/to/spectrum.mzXML', n_scans=128, n_points=6)

Individual spectra can be accessed in list-like fashion

spectrum = exp[0]

Masses and intensities can be accessed manually

masses = spectrum.masses
ints = spectrum.ints

See more details on working with MEDUSA in documentation.

Elements identification

To use the model on your own isotopic distribution, run:

from mass_automation.formula.hr.nn_model import ElementClassifier
from mass_automation.formula.hr.final_architectures import LTTwoEncoders

model = ElementClassifier(Model=LTTwoEncoders,
                          weights="data/models_hr/NNModels/two_encoders_augmented_1.ckpt")

mz = [..] # list of m/z values
ints = [..] # list of intensities
isodistribution = (mz, ints)

preds = model.predict(isodistribution, threshold=0.5)

And you will obtain the dictionary with the predictions, like {element : probability}.

The example of the usage of the model is available in the nn_model_usage.ipynb file. There the model's evaluation is performed on the test dataset.

The usage of the pipeline from spectrum processing to the final predictions is demonstrated in the full_pipeline.ipynb file.

Model training and finetuning

The model training and finetuning are implemented in the finetune.py file.

You may train our model on your own data, or add new elements to the model. For more details, see the README file.

Dataset generation

The dataset generation is implemented in the dataset_generator.py file. For more details, see the README file.

Data

Model architectures discussed in the paper are available in the final_architectures.py file. Their weights are available in the data/models_hr/NNModels directory.

Test dataset is available in the data/datasets/test_dataset_hr_extended.pkl file.

Classical ML models

Classical machine learning models (including the combined estimator used by the sklearn-based element classifier) are not shipped in this repository. Download them from Zenodo: https://doi.org/10.5281/zenodo.20445747.

To use the classical ElementClassifier in mass_automation/formula/hr/model.py, set the path to your downloaded .pkl file in mass_automation/formula/hr/__init__.py:

COMB_CLASSICAL_MODEL_PATH = "/path/to/classic/ml/model.pkl"  # e.g. path to ML_combination.pkl from the Zenodo archive

Then:

from mass_automation.formula.hr.model import ElementClassifier

clf = ElementClassifier()
# clf(isodistribution) or clf.predict_proba(...) — see model.py

The neural-network workflow above uses mass_automation.formula.hr.nn_model.ElementClassifier and does not require this step; only the classical sklearn-based classifier reads COMB_CLASSICAL_MODEL_PATH.