Pi-UVMorphe (UltraViolet-specific Multimodal Optimized Reliability Prediction for Hybrid Envelope fragments) is a dual-branch deep learning framework designed for accurate and reliable fragment ion identification in UVPD top-down proteomics. Developer is Bo Yao from State Key Laboratory of Medical Proteomics, National Center for Protein Sciences (Beijing).
Overview of π-UVMorphe architecture. Raw mzML files and peptide lists are preprocessed via peak deconvolution to extract tabular features and isotope envelope images. The π-UVMorphe model processes the inputs through dual branches: the tabular branch utilizes an MLP for feature extraction, while the image branch employs a Vision Transformer (ViT) to encode isotope patterns; both features are then concatenated for classification to output conserved fragment labels. The downstream application utilizes the fragment identification results to generate sequence cleavage plots and calculate Internal Reliability Scores (IRS) for quality visualization.
python == 3.10.19
torch == 1.13.0
torchvision == 0.14.0
numpy == 1.26.4
pandas == 2.3.3
scikit-learn == 1.7.2
Pillow == 11.1.0
plotly == 6.7.0
matplotlib == 3.10.8
pyteomics == 4.7.5
PyQt5 == 5.15.11
tqdm == 4.67.3
You can set up the environment using either standard pip or via conda
conda create -n Pi-UVMorphe python=3.10.19 -y
conda activate Pi-UVMorphe
cd /path/to/Pi-UVMorphe
pip install -r requirements.txt
The model weight file (best_model.pth) is stored using Git LFS and may not download automatically when cloning the repository.
Please Go to the Releases page and download best_model.pth, then place it in the project root directory.
To utilize the model, you need to prepare the following inputs:
-
Mass Spectrometry Data Files: MSALIGN File (-m / --msalign) Format: .msalign Description: The primary mass spectrometry data file containing deconvolution headers and peak lists (typically generated by TopFD). This file provides the experimental mono-isotopic masses and charge states of the detected fragment ions.
Spectrum JSON File (-j / --js) Format: spectrum0.js or standard JSON spectrum path Description: The corresponding spectrum profile data that contains raw intensity, ion counts, and detailed envelope shapes. The model relies on this file to extract deep chromatographic and morphological features.
-
Biological Sequence & Metadata: Protein Sequence (-s / --sequence) Format: Plain text string (Capitalized single-letter amino acid codes, e.g., "SHHWGYG...") Description: The target amino acid sequence of the protein being analyzed. The algorithm uses this sequence as the template to generate theoretical internal and terminal fragments for matching.
Modification Type (-mod / --modification) Format: String selection (Optional) Allowed Values: acetylated, deaminated, methylated, dimethylated, formylated, amided, c_methylated, dehydrated. Description: Specifies the post-translational modification (PTM) to be considered during the fragment matching process, ensuring precise mass shift calculations.
-
Model Weights & Configuration: StandardScaler File (--scaler) Format: .pkl (Default: scaler0424.pkl) Description: A serialized Python pickle file containing the normalization parameters (mean and variance) used to scale the input feature vectors before feeding them into the neural network.
Model Weights (--model) Format: .pth (Default: best_model.pth) Description: The pre-trained PyTorch model checkpoint containing the optimized weights of the Pi-UVMorphe neural network architecture.
PPM Tolerance (--ppm) Format: Integer (Default: 5) Description: The parts-per-million (PPM) mass tolerance window allowed when matching experimental mass peaks to theoretical fragment masses.
You can launch the complete pipeline with a single command. To test your installation with the provided example dataset, execute:
python run.py -m data/example_data/10uMCA25+UVPDLPT1,5mJ1pFullP_ms2.msalign -j data/example_data/10uMCA25+UVPDLPT1,5mJ1pFullP_html/topfd/ms2_json/spectrum0.js -s "SHHWGYGKHNGPEHWHKDFPIANGERQSPVDIDTKAVVQDPALKPLALVYGEATSRRMVNNGHSFNVEYDDSQDKAVLKDGPLTGTYRLVQFHFHWGSSDDQGSEHTVDRKKYAAELHLVHWNTKYGDFGTAAQQPDGLAVVGVFLKVGDANPALQKVLDALDSIKTKGKSTDFPNFDPGSLLPNVLDYWTYPGSLTTPPLLESVTWIVLKEPISVSSQQMLKFRTLNFNAEGEPELLMLANWRPAQPLKNRQVRGFPK" -mod acetylated
If you prefer a visual, point-and-click environment to upload files, configure parameters, and visualize sequence cleavage plots, launch the GUI dashboard by running:
python run_gui.py
The graphical user interface (GUI) of the π-UVMorphe. (a) Analysis settings panel. Users can input .msalign and spectrum0.js files, protein sequences, and set modifications and PPM tolerance. Real-time processing logs are displayed below. (b) Results overview panel. Displays a global statistics summary (e.g., matches, coverage) and a detailed table of matched fragments, including fragment types, theoretical/observed masses, intensities, charges, and m/z values.
Please contact me if you have any help: doggyfox@163.com