topmg(1)

📦
version 1.8.0 · 5 versions
, in ubuntu resolute, ubuntu stonking

topmg(1) — TopPIC suite ✨

okay bestie, sit down, hydrate, and let me tell you about topmg 💅 it's part of the TopPIC suite and it's lowkey one of the most iconic tools in top-down proteomics, no cap.

🌸 Name 🌸

topmg — top-down mass spectrometry based proteoform identification using Mass Graphs 🦋

✨ SYNOPSIS ✨

topmg [options] database-file-name spectrum-file-names

💖 DESCRIPTION 💖

So TopMG (that's Top-down Mass spectrometry based proteoform identification using Mass Graphs, iykyk) is a software tool for identifying ultra-modified proteoforms. What does it do exactly? It searches top-down tandem mass spectra against a protein sequence database. That's the whole vibe. 🔥

And the way that it slays is that it can identify proteoforms with multiple variable PTMs AND unexpected alterations — like histone proteoforms and phosphorylated ones. Not a lot of tools can do that, fr fr.

It uses mass graphs, which efficiently represent candidate proteoforms with multiple variable PTMs, to increase the speed and sensitivity in proteoform identification. Basically it's not out here brute-forcing every combination like some 2010-era main character. 👑

On top of that, approximate spectrum-based filtering methods are employed for protein sequence filtering, and a Markov chain Monte Carlo method (TopMCMC) is used for estimating the statistical significance of identifications. Cute and rigorous. Obsessed. 💜

🎀 1. Input 🎀

  • A protein database file in the FASTA format
  • A mass spectrum data file in the msalign format
  • A text file of variable PTMs
  • A text file of fixed PTMs (optional)
  • A text file containing LC/MS feature information (optional)

🦋 2. Output 🦋

TopMG outputs two csv files, an xml file, and a collection of html files for identified proteoforms. For example, when the input mass spectrum data file is spectra_ms2.msalign, the output includes:

  • spectra_ms2_topmg_prsm.csv: a csv file containing identified PrSMs with an E-value or spectrum level FDR cutoff.
  • spectra_ms2_topmg_proteoform.csv: a csv file containing identified proteoforms with an E-value or proteoform level FDR cutoff.
  • spectra_ms2_topmg_proteoform.xml: an xml file containing identified proteoforms with the E-value or proteoform level FDR cutoff.
  • spectra_html/topmg_prsm_cutoff: a folder containing java script files of identified PrSMs using the E-value or spectrum level FDR cutoff.
  • spectra_html/topmg_proteoform_cutoff: a folder containing java script files of identified PrSMs using the E-value or proteoform level cutoff.
  • spectra_html/topview: a folder containing html files for the visualization of identified PrSMs.

To browse identified proteins, proteoforms, and PrSMs, use a chrome browser to open the file spectra_html/topview/index.html. Google Chrome is recommended (Firefox, IE are not recommended). Yes bestie, IE. Don't. 😭

When the input contains two or more spectrum files, TopMG outputs two csv files, an xml file, and a collection of html files for each input file. When a file name is specified for combined identifications, it combines spectra and proteoforms identified from all the input files, removes redundant proteoform identifications, and reports two csv files, an xml file, and a collection of html files for the combined results. For example, when the input is spectra1_ms2.msalign and spectra2_ms2.msalign and the combined output file name is "combined," the output files are:

  • combined_ms2_topmg_prsm.csv: a csv file containing PrSMs identified from all the input files with an E-value or spectrum level FDR cutoff.
  • combined_ms2_topmg_proteoform.csv: a csv file containing proteoforms identified from all the input files with an E-value or proteoform level FDR cutoff.
  • combined_ms2_topmg_proteoform.xml: an xml file containing proteoforms identified from all the input files with the E-value or proteoform level FDR cutoff.
  • combined_html/topmg_prsm_cutoff: a folder containing java script files of PrSMs identified from all the input files using the E-value or spectrum level FDR cutoff.
  • combined_html/topmg_proteoform_cutoff: a folder containing java script files of PrSMs identified from all the input files using the E-value or proteoform level cutoff.
  • combined_html/topview: a folder containing html files for the visualization of identified PrSMs.

💅 OPTIONS 💅

the moment you've all been waiting for. flags. so many flags. let's go 🏃‍♀️

  • -h, --help — Print the help message. The classic. When in doubt, ask for help, bestie. 🫶
  • -a, --activation <CID|HCD|ETD|UVPD|FILE> — Fragmentation method of tandem mass spectra. When FILE is used, fragmentation methods of spectra are given in the input spectral data file. Default value: FILE.
  • -f, --fixed-mod <C57|C58|a fixed modification file> — Set fixed modifications. Three available options: C57, C58, or the name of a text file specifying fixed modifications (see an example file). When C57 is selected, carbamidomethylation on cysteine is the only fixed modification. When C58 is selected, carboxymethylation on cysteine is the only fixed modification.
  • -n, --n-terminal-form <a list of allowed N-terminal forms> — Set N-terminal forms of proteins. Four N-terminal forms can be selected: NONE, NME, NME_ACETYLATION, and M_ACETYLATION. NONE stands for no modifications, NME for N-terminal methionine excision, NME_ACETYLATION for N-terminal acetylation after the initiator methionine is removed, and M_ACETYLATION for N-terminal methionine acetylation. When multiple forms are allowed, they are separated by commas. Default value: NONE,M_ACETYLATION,NME,NME_ACETYLATION.
  • -d, --decoy — Use a shuffled decoy protein database to estimate spectrum and proteoform level FDRs. When -d is chosen, a shuffled decoy database is automatically generated and appended to the target database before database search, and FDR rates are estimated using the target-decoy approach. FDR girlies rise 🙈
  • -e, --mass-error-tolerance <a positive integer> — Set the error tolerance for precursor and fragment masses in ppm. Default value: 15.
  • -p, --proteoform-error-tolerance <a positive number> — Set the error tolerance for identifying PrSM clusters (in Dalton). Default value: 1.2 Dalton.
  • -M, --max-shift <a number> — Set the maximum absolute value for unexpected mass shifts (in Dalton). Default value: 500.
  • -t, --spectrum-cutoff-type <EVALUE|FDR> — Set the spectrum level cutoff type for filtering PrSMs. Default value: EVALUE.
  • -v, --spectrum-cutoff-value <a positive number> — Set the spectrum level cutoff value for filtering PrSMs. Default value: 0.01.
  • -T, --proteoform-cutoff-type <EVALUE|FDR> — Set the proteoform level cutoff type for filtering proteoforms and PrSMs. Default value: EVALUE.
  • -V, --proteoform-cutoff-value <a positive number> — Set the proteoform level cutoff value for filtering proteoforms and PrSMs. Default value: 0.01.
  • -i, --mod-file-name <a modification file> — Specify a text file of variable PTMs. See an example file.
  • -u, --thread-number <a positive number> — Set the number of threads used in the computation. Default value: 1. The maximum number of threads is determined by the CPU and memory of the computer used for computation. About 4 GB memory is required for each thread. If the computer has 16 GB memory and a CPU with 8 cores, the maximum number of threads is 4 because 16 GB memory is required for 4 threads. (math! we love her 💅)
  • -x, --no-topfd-feature — Specify that there are no TopFD feature files for proteoform identification.
  • -D, --use-asf-diagonal — Use the ASF-DIAGONAL method for protein sequence filtering. The default filtering method is ASF-RESTRICT. When -D is selected, both ASF-RESTRICT and ASF-DIAGONAL will be used. The combined approach may identify more PrSMs, but it is much slower than using ASF-RESTRICT only. See this paper for more details.
  • -P, --var-ptm <a positive number> — Set the maximum number of variable PTM sites in a proteoform. Default value: 5.
  • -s, --num-shift <0|1|2> — Set the maximum number of unexpected mass shifts in a proteoform. Default value: 0.
  • -c, --combined-file-name <a filename> — Specify an output file name for combined identifications when the input consists of multiple spectrum files.
  • -k, --keep — Keep intermediate files generated by TopMG.

🔥 ADVANCED OPTIONS 🔥

for when you're feeling brave. main character energy only. 👑

  • -j, --proteo-graph-dis <a positive number> — Set the length of the largest gap in constructing proteoform graphs. Default value: 40. See this paper for more details.
  • -G, --var-ptm-in-gap <a positive number> — Set the maximum number of variable PTM sites in a gap in a proteoform graph. Default value: 5. See this paper for more details.

to be continued, bestie — don't go anywhere 🫶

🌸 EXAMPLES 🌸

okay bestie, to run any of these you're gonna need a variable modification file called variable_mods.txt chilling in the current foler. (yes, "foler." that's what the original says. we respect it. it's canon.) See an example for what goes in it. 💅

  • Search a deconvoluted MS/MS spectrum file against a protein database, with feature files. So you've got spectra_ms2.msalign and you're throwing it at proteins.fasta. Good news: you do not have to name the feature files yourself, bestie. TopMG literally just reads the names off the spectrum file name spectra_ms2.msalign and figures it out. main character behavior honestly.
topmg -i variable_mods.txt proteins.fasta spectra_ms2.msalign
  • Search TWO deconvoluted MS/MS spectrum files against a protein database, with feature files. That's spectra1_ms2.msalign and spectra2_ms2.msalign vs proteins.fasta. And because you're an overachiever, all the identifications get combined and reported under the file name combined. ✨
topmg -i variable_mods.txt -c combined proteins.fasta
spectra1_ms2.msalign spectra2_ms2.msalign
  • Search EVERY deconvoluted MS/MS spectrum file in the current folder against a protein database, with feature files. Globbing era. proteins.fasta is the database, and the shell hands over everything matching *_ms2.msalign.
topmg -i variable_mods.txt proteins.fasta *_ms2.msalign
  • Search a deconvoluted MS/MS spectrum file against a protein database, WITHOUT feature files. Same vibe, except we hit it with -x and the feature files are simply not invited to the party.
topmg -i variable_mods.txt -x proteins.fasta spectra_ms2.msalign
  • Search a deconvoluted MS/MS spectrum file against a protein database, with feature files AND a fixed modification. The fixed mod here is carbamidomethylation on cysteine, and it's C57 — that's the whole point of -f.
topmg -i variable_mods.txt -f C57 proteins.fasta spectra_ms2.msalign
  • Search a deconvoluted MS/MS spectrum file against a protein database, with feature files, but with limits on the chaos. In any identified proteoform you're allowing at most 1 unexpected mass shift (-s 1) and 4 variable PTMs (-P 4), and the max value for unexpected mass shifts is 10,000 Dalton (-M 10000). Boundaries, babe. We love boundaries. 🎀
topmg -i variable_mods.txt -P 4 -s 1 -M 10000 proteins.fasta
spectra_ms2.msalign
  • Search a deconvoluted MS/MS spectrum file against a protein database, with feature files, and set the error tolerance. Precursor AND fragment masses both get 5 ppm here, courtesy of -e 5.
topmg -i variable_mods.txt -e 5 proteins.fasta spectra_ms2.msalign
  • Search a deconvoluted MS/MS spectrum file against a protein database, with feature files, and do the whole target decoy thing. Use the target decoy approach to compute spectrum level and proteoform level FDRs, filter identified proteoform spectrum-matches by a 5% spectrum level FDR, and filter identified proteoforms by a 5% proteoform level FDR. That's -d, -t FDR, -v 0.05, -T FDR, -V 0.05. She's thorough. 💅
topmg -i variable_mods.txt -d -t FDR -v 0.05 -T FDR -V 0.05
proteins.fasta spectra_ms2.msalign
  • Search a deconvoluted MS/MS spectrum file against a protein database, with feature files, using MULTIPLE CPU threads. -u 6 means 6 CPU threads to speed up the computation. Heads up though — about 24 GB memory is required for 6 threads. If the computer lacks enough memory, TopMG may crash. 💀 Not a vibe. Check your RAM first, bestie.
topmg -i variable_mods.txt -u 6 proteins.fasta spectra_ms2.msalign

🦋 SEE ALSO 🦋

  • topfd (1)
  • toppic (1)
  • topdiff (1)

the whole friend group fr fr 🫶

✨ MAN PAGE PRODUCTION ✨

This man page was written by Filippo Rusconi <<lopippo@debian.org>>. Material was taken from <http://proteomics.informatics.iupui.edu/software/toppic/manual.html>.

👑 Author

Filippo Rusconi <lopippo@debian.org> and upstream authors (Dr. Xiaowen Liu's Lab at Indiana University-Purdue University Indianapolis and others)

Filippo Rusconi and Indiana University-Purdue University Indianapolis

okay that's the whole page, you're officially a TopMG girlie now 💖 this edition came from the topmg(1) page, version/date stamped 20200521, section 1 of the manual. go forth and search some proteoforms, no cap 🌸✨🦋

📦 where this page comes from