JMod is an open and flexible software for increasing the throughput of sensitive proteomics by supporting multiplexing in the mass and time domains.
JMod: Joint modeling of mass spectra for empowering multiplexed DIA proteomics
Kevin McDonnell, Daniel J. Geiszler, Nathan Wamsley, Jason Derks, Sarah Sipe, Zachary A. Cohen, Lina Kozhaya Warinner, Maddy Yeh, Eunice Koo, Andrew Leduc, Theodore J. Zwang, Harrison Specht, Nikolai Slavov bioRxiv 2025.05.22.655512; doi: 10.1101/2025.05.22.655512
Setup Steps
JMod has a .bat executable that is only compatible with Windows computers. Follow the instructions below to launch the JMod GUI via the .bat.
-
Download the JMod repository. The most recent release of JMod can be downloaded here.
-
Navigate to the JMod directory. Inside that directory is a
launch.batfile. Double-click on the file to open the JMod GUI.- If this is the first time the computer is setting up a UV environment, it might take a few minutes to download all dependencies and packages.
-
The JMod GUI should open in a new window.
If you would like to set up the UV environment with the command line, please follow the instructions below in Linux/MacOS Setup.
Setup Steps
-
Download the JMod repository. The most recent release of JMod can be downloaded here.
-
It is recommended to use the UV package manager when running JMod. To set up a UV environment for JMod, run the following command:
pip install uvor via wget/curl if it is not already installed.
-
Open a new terminal and navigate to the JMod directory. The directory contains a
pyproject.tomlthat lists all required packages and dependencies. Run the following command to install the environment:uv sync -
You can now launch the JMod GUI with
uv run python run_jmod_from_GUI.pyor run a search using the command line withuv run python run_jmod.py <args>.
Setup Steps
JMod supports direct processing of Thermo .raw files using Thermo's RawFileReader libraries. Thermo's RawFileReader requires .NET Core Framework 4.7.2, 4.4, 4.8.1, or 8.x and newer on Windows or Mono 6.12 or newer on Linux. It does not work with .NET Core 2.x or 3.x on Windows.
To enable .raw file support, please download the latest RawFileReader release, which can be found here.
When using the JMod GUI, you will be prompted to point to the netstandard2.0 directory. If running JMod with the command line, use --rawfilereader_path path/netstandard2.0. Both of these options will save this path to data/settings.json which will be used in future runs unless --rawfilereader_path is specified.
If running JMod on Linux/MacOS, mono will need to be downloaded. This can be done with the following command:
brew install mono
If homebrew is not installed, it can be installed with the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Thermo RawFileReader is developed and distributed by Pacific Northwest National Laboratory (PNNL) and Thermo Fisher Scientific and is licensed and distributed separately from JMod.
JMod ships a copy of the Unimod modification database, data/unimod.xml. Unimod is copyright 2002-2006 Unimod and distributed under the Design Science License, in data/unimod.xml.LICENSE. To update the copy to the latest from unimod.org, run uv run python scripts/update_unimod.py.
To run a JMod search, both a spectrum file (either .raw or .mzML) and a .tsv spectral library are required. If you would like to convert .raw files to .mzML to run with JMod, please follow the instructions below.
JMod currently supports .mzML and .raw files. Direct support for .d files will be added in future releases. To convert .raw files to .mzML files, please make sure the data is centroided. This can be done with MSConvert with the command --filter peakPicking true 1-
Description of Library Columns
| Column | Definition | Req/Opt |
|---|---|---|
| ModifiedPeptide | Peptide sequence including modifications | Req |
| StrippedPeptide | Peptide sequence not including modifications | Req |
| PrecursorCharge | Charge of the precursor | Req |
| RT | Retention time of the precursor | Req |
| PrecursorMz | m/z of the precursor | Req |
| FragmentMz | m/z of the fragment | Req |
| RelativeIntensity | Intensity of the fragment | Req |
| FragmentType | Fragment type (b, y) | Req |
| FragmentCharge | Fragment charge (1, 2, etc.) | Req |
| FragmentSeriesNumber | Fragment series number (12, 9, 5, etc.) | Req |
| FragmentLossType | Fragment loss type (noloss, NH3, H2O) | Opt |
| ProteinID | All proteins that contain the fragment's precursor | Opt |
| ProteinGroup | Inferred proteins | Req |
| ProteinName | Names of proteins in ProteinGroup | Opt |
| Genes | Gene names mapping to proteins in ProteinGroup | Opt |
| IonMobility | Ion mobility of the precursor | Opt |
An example library with the required columns can also be found here.
The GUI can be launched with the launch_JMod.bat file on Windows computers.
If not on a Windows computer, the GUI can be launched with the following command:
uv run python path/to/run_jmod_from_GUI.py
More detailed instructions on how to run JMod from the GUI can be found here.
JMod can be run through the command line with various search parameters. An example command is shown below:
uv run python path/to/run_jmod.py -l path/to/library.tsv -i path/to/file_to_search.mzML
To search multiple files with one library, repeat -i or give a folder of data files with --mzml_folder:
uv run python path/to/run_jmod.py -l path/to/library.tsv -i path/to/file_1.mzML -i path/to/file_2.mzML
uv run python path/to/run_jmod.py -l path/to/library.tsv --mzml_folder path/to/data_folder
Some commonly used search parameters are listed below. A more extensive list of commands can be found here.
Search Parameters
-i, --mzml
Input file in mzML format. Repeat to search multiple files
--mzml_folder
Search every .mzML, .raw and .d file in this folder
-o, --output_folder
Specify an output folder to send search results
default = location of files being searched
-l, --speclib
Spectrum library in DIANN output format (must be .tsv or .parquet)
-t, --threads
Number of threads to be used for the search
default = 10
--ms1_ppm
User provided MS1 ppm error tolerance.
-p --ppm
MS2 matching tolerance in parts per million.
default = 10
--iso
Use MS2 isotopes in search.
default = False
--num_iso
Number of MS2 isotopes to consider if using them
default = 2
--iso_workers
Number of processes used to generate isotopes.
default = 3
-m --atleast_m
Required number of fragments matched from top N fragments (N=10)
default = 3
--no_ms1_req
Don't require observation of an MS1 peak for consideration in the search.
default = False
--apex_jitter
Allow center scan for MS1 quant to slide this many scans if intensity is monotonically increasing.
default = 0
--free_apex
Allow channels to be quantified in different scans. For example, useful for non-coeluting channels caused by deuterium.
default = False
--additional_scans
If free-apex; Each channel apex is selected within this number of scans from the plex group center.
default = 0
--timeplex
Use timePlex mode for search
default = False
--num_timeplex
Number of time offset injections for timePlex search
default = 0
--tag
Tag used in the experiment, if any. See mass_tags.py for details.
default = None
--channels
Comma-separated channels of --tag to search (e.g. --tag dimethyl --channels 0,4).
default = None (all channels)
--SILAC
Adds stable isotope label
default = False
--use_emp_rt
Force use of library retention time for alignment.
default = False
--user_rt_tol
Force use of provided retention time tolerance.
default = False
--rt_tol
User provided retention time tolerance.
--mbr
Match between runs. Requires two or more files.
default = False
--rawfilereader_path
Path to the ThermoRawFileParser if using .raw files
--bruker_sdk_path
Path to the Bruker tdf-sdk if using .d timsTOF files
Library Modifications
Modifications can be added to, or removed from, precursors in the library when it is loaded. The library file itself is not changed.
--add_fixed_mod NAME,SITES or NAME,MASS,SITES
Add a modification to every one of SITES: n for the peptide N-terminus, plus any residues, e.g. nK.
If the mod is not in UniMod, MASS is required.
A mod is never added to a site twice, so this can also give an existing fixed mod its mass.
A site that already carries another modification is skipped, with a warning.
End with ,stack to add it alongside the other modification instead.
--add_variable_mod NAME,SITES or NAME,MASS,SITES
Also make a copy of each precursor for every combination of these sites (every position).
Copies keep their parent's retention time, ion mobility and fragment intensities. Can end with ,stack.
--max_variable_mods
Most variable modifications on one precursor, counted across all of them.
default = 1
--strip_mod NAME or NAME,MASS or NAME,SITES or NAME,MASS,SITES
Remove a modification: from every site, or only from SITES.
If the mod is not in UniMod, MASS is required.
- Use UniMod names (e.g.
UniMod:4) whenever the modification is in UniMod. JMod then looks up its mass and its isotopic composition. Give MASS for a modification UniMod does not have. - Each option can be repeated. Strips are applied first, then fixed modifications, then variable copies.
- Check what the options will do before searching with
--inspect_libraryor the 'i' button in the GUI next to the library loader. - In the GUI, add these options in the Additional Commands box.
For example, to remove carbamidomethylation from cysteines, add heavy lysine (SILAC Lys8, single channel) to every lysine, and allow oxidation of methionine as a variable modification:
--strip_mod UniMod:4,C --add_fixed_mod UniMod:259,K,stack --add_variable_mod UniMod:35,M
JMod can also be run using a configuration file. Each JMod search produces its own configuration file which can be used to initialize other searches. An example configuration can be found in data/default_config.json, and a sample command can be found here:
uv run python path/to/run_jmod.py --config_json path/to/config.json
Options given on the command line override those in the configuration file.
Running JMod with Sample Demo Data
We have provided a small .mzML file and a small library to run a quick JMod search to check that all dependencies and environment variables are working properly. The raw file and library can be found in data/test_mode_filtered.mzML and data/filtered_library.tsv respectively. This quick search can be run on the command line with the following command:
cd path/to/JMod-Main
uv run python run_jmod.py -i data/test_mode_filtered.mzML -l data/filtered_library.tsv
Standalone Commands
These commands run on their own, without a search.
--inspect_library path/to/library
Report the library's modifications, what any --strip_mod, --add_fixed_mod and --add_variable_mod
given would do to them, and whether JMod can load it (with the --tag given, if any).
The "i" button next to the spectral library in the GUI shows the same report.
--make_library path/to/experiment_folder
Build the match between runs library from a finished search's experiment folder.
--combine_results path/to/experiment_folder
Combine the results of a finished search's experiment folder again.
For example:
uv run python path/to/run_jmod.py --inspect_library path/to/library.parquet --tag PSMtag_5plex
JMod produces multiple output files. Each search writes them to a folder determined by -o or 'Output Folder' in the GUI, with one results folder per searched file. Below is a brief description of the main outputs alongside an example directory structure. A more comprehensive description of each output file can be found here.
combined_filtered_IDs.parquet: IDs from all searched files filtered at 1% FDR, with global q-valuesexperiment_results/: Plots comparing the searched filesJMod_config.json: Configuration file for this current searchJMod_log.log: Log of the searchfiltered_IDs.parquet: IDs filtered at 1% FDR with select columnsfiltered_IDs.csv: IDs filtered at 1% FDR with extended columnsSummary.txt: Summary of precursor & protein identifications
With --mbr, the first search of each file is in first_pass/ and the match between runs library is in mbr_library/.
A comprehensive list of all output columns and descriptions for each one can be found below:
JMod Output Columns
| Column | Description |
|---|---|
coeff |
Coefficient estimated for the precursor |
spec_id |
MS2 spectrum ID where the precursor was found |
Ms1_spec_id |
Closest MS1 spectrum to the MS2 spectrum |
seq |
Precursor sequence |
z |
Precursor charge |
window_mz |
Center of the MS2 isolation window |
rt |
Retention time of the MS2 spectrum |
num_lib |
Number of library fragments matched |
frac_lib_int |
Fraction of the library intensity matched |
frac_dia_int |
Fraction of the observed intensity matched to the precursor |
mz_error |
Relative MS1 m/z error |
rt_error |
Retention time error (empirical RT - library RT) |
frac_int_matched |
Fraction of the total spectrum intensity with any match (any precursor) |
frac_int_pred |
Fraction of the total spectrum intensity predicted by all precursors |
spec_r2 |
Pearson correlation for the predictions and observed spectrum |
prec_r2 |
Pearson correlation for the predicted precursor and matched spectrum peaks |
prec_r2_uniq |
Pearson correlation for the predicted precursor and uniquely matched peaks |
frac_int_uniq |
Fraction of library intensity uniquely matched |
frac_int_uniq_pred |
Fraction of total spectrum intensity uniquely predicted |
hyperscore |
Sum of matched intensities times factorial(#b ions) times factorial(#y ions) |
b_counts |
Number of b ions matched |
y_counts |
Number of y ions matched |
longest_y_ions |
Index of largest y ion matched |
scribe_scores |
Scribe score as described here |
max_unmatched_residuals |
Maximum residual for unmatched peaks, normalized and log-transformed |
max_matched_residuals |
Maximum residual for matched peaks, normalized and log-transformed |
gof_stats |
Goodness-of-fit score for each precursor (log2 of residuals/fitted) |
manhattan_distances |
Manhattan distances between precursor peaks and observed peaks (normalized and log-transformed) |
fitted_spectral_contrasts |
Spectral contrast angles for each precursor |
frac_int_matched_pred |
Fraction of the matched spectrum intensity predicted by all precursors |
frac_int_matched_pred_sigcoeff |
Fraction of spectrum intensity predicted by precursors with coeff > 1 |
cosine |
Similarity between predicted spectra and observed intensities |
mz |
Precursor m/z |
tic |
Total ion current |
file_name |
Name of the file searched |
protein |
Protein associated with the precursor |
is_decoy |
Is this a decoy peptide |
n_scans |
Number of scans where that precursor was identified |
manhattan_distances_nearby_max |
Maximum manhattan_distances of nearby scans |
max_matched_residuals_nearby_min |
Minimum max_matched_residuals of nearby scans |
gof_stats_nearby_min |
Minimum gof_stats of nearby scans |
scribe_scores_nearby_min |
Minimum scribe_scores of nearby scans |
smoothness |
The smoothness of coeffs for that precursor |
stripped_seq |
Amino acid sequence without tags or mods |
pep_len |
Peptide sequence length |
sq_rt_error |
Square root of the rt_error |
sq_mz_error |
Square root of the mz_error |
untag_seq |
Peptide sequence without the tag (contains mods) |
untag_prec |
Untag_seq and charge combined |
channels_matched |
Number of channels from the plex set matched |
median_[feature]_stats |
Median of [feature] across channels |
diff_[feature]_from_median |
Difference between channel [feature] and the median [feature] value across channels |
frac_shared_intensity |
Fraction of shared intensity between channels |
channel |
Channel name of the precursor |
silac_channel |
SILAC channel |
med_frag_error |
Median absolute m/z error of the matched fragments |
n_corr_scans |
Number of scans used in correlation calculation |
n_corr_frags |
Number of fragments used in correlation calculation |
mean_frag_corr |
Mean correlation between fragments |
median_frag_corr |
Median fragment correlations between fragments for the same precursor |
max_frag_corr |
Maximum fragment correlations between fragments for the same precursor |
min_frag_corr |
Minimum fragment correlation between fragments for the same precursor |
std_frag_corr |
Standard deviation of fragment correlations |
mean_top3_frag_corr |
Mean of the top 3 fragment correlations |
frac_corr_above_0p5 |
Fraction of fragments with correlation above 50% |
mean_frag_mean_corr |
(no description provided) |
top_[n]_frag_mean_corr |
Mean of top [n] fragment correlations |
top_[n]_frag_sum_corr |
Sum of top [n] fragment correlations |
top_[n]_pair_corr |
Top [n] correlations between fragments |
mean_prec_frag_corr |
Mean precursor to fragment correlation |
max_prec_frag_corr |
Maximum precursor to fragment correlation |
PredVal |
Raw score from the target-decoy classifier (1 is target) |
Qvalue |
Q-value of the precursor |
BestChannel_Qvalue |
Best q-value of the precursor plex set |
plexfitMS1 |
Fitted MS1 coefficient at max |
plexfitMS1_p |
Correlation of theoretical MS1 isotope distribution with observed peaks |
plexfittrace |
Fitted MS1 coefficients of elution trace |
plexfit_ps |
Correlation of theoretical MS1 isotope distribution with observed peaks for each fit in elution trace |
plexfittrace_spec_all |
All MS1 spectra used for MS1 fitting |
plexfittrace_all |
All fitted MS1 coefficients |
plexfittrace_ps_all |
Correlation of theoretical MS1 isotope distribution with observed peaks for each fit |
plex_Area |
Area under fitted MS1 coefficients |
ms1_apex_scan |
MS1 apex scan selected for MS quantitation |
ms1_cor |
Correlation between MS2 coefficients and monoisotopic trace |
traceproduct |
Product of MS1xMS1 correlations |
iso_cor |
Correlation between theoretical and observed MS1 isotopes |
MS1_Int |
Observed intensity of MS1 monoisotopic peak at max |
all_ms1_specs |
MS1 spectra searched for monoisotopic peak |
MS1_Area |
Area under elution trace of MS1 monoisotopic trace |
all_ms1_iso[n]vals |
Observed MS1 intensities for the [n]th isotopic peak (0 being the monoisotopic peak) |
last_aa |
Last amino acid in the peptide sequence |
seq_len |
Length of the amino acid sequence |
run_chan |
Sample run and channel concatenated |
Protein_Qvalue |
Protein q-value |
frag_names |
Names of fragments matched |
frag_errors |
m/z errors of fragments matched |
frag_mz |
Theoretical m/z of fragments matched |
frag_int |
Library intensity of fragments matched |
obs_int |
Observed intensity of fragments matched |
unique_frag_mz |
Fragments that uniquely matched a peak |
unique_obs_int |
Intensities for fragments that uniquely matched a peak |
experiment_folder (-o, or 'Output Folder' entry in GUI)
├── combined_filtered_IDs.parquet
├── JMod_config.json
├── JMod_log.log
├── experiment_results/
│ └── [experiment_plots].png
└── [file]_results/
├── filtered_IDs.parquet
├── filtered_IDs.csv
├── Summary.txt
├── first_search/
│ └── firstSearch.tsv
├── outputs/
│ ├── all_IDs_filtered.parquet
│ ├── all_IDs.csv
│ ├── config.json
│ ├── decoylibsearch_coeffs.parquet
│ └── params.txt
├── scoring/
└────── [scoring_plots].png
