Skip to content
ParallelSquaredPublic

About

Joint modeling of DIA spectra

Resources

Stars

10 stars

Watchers

3 watching

Forks

Repository files navigation

JMod

JMod is an open and flexible software for increasing the throughput of sensitive proteomics by supporting multiplexing in the mass and time domains.

Reference

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

Table of Contents

Setting up JMod

Windows Setup

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.

  1. Download the JMod repository. The most recent release of JMod can be downloaded here.

  2. Navigate to the JMod directory. Inside that directory is a launch.bat file. 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.
  3. 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.

Linux/MacOS Setup

Setup Steps
  1. Download the JMod repository. The most recent release of JMod can be downloaded here.

  2. 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 uv

    or via wget/curl if it is not already installed.

  3. Open a new terminal and navigate to the JMod directory. The directory contains a pyproject.toml that lists all required packages and dependencies. Run the following command to install the environment:

    uv sync

  4. You can now launch the JMod GUI with uv run python run_jmod_from_GUI.py or run a search using the command line with uv run python run_jmod.py <args>.

Thermo Raw File Support

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.

Unimod

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.

Running a Search

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.

File Conversion

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-

Library Structure

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.

Running JMod with the Graphical User Interface (GUI)

alt text

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.

Running JMod with the Command Line Interface (CLI)

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_library or 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

Output Files

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-values
  • experiment_results/: Plots comparing the searched files
  • JMod_config.json: Configuration file for this current search
  • JMod_log.log: Log of the search
  • filtered_IDs.parquet: IDs filtered at 1% FDR with select columns
  • filtered_IDs.csv: IDs filtered at 1% FDR with extended columns
  • Summary.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

Structure of Results Directory:

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

About

Joint modeling of DIA spectra

Resources

Stars

10 stars

Watchers

3 watching

Forks

Releases

Packages

Contributors

Languages