toppic(1)

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

💖 Name 💖

okay so toppic(1) is from the TopPIC suite, and her full government name is Top-down mass spectrometry based Proteoform Identification and Characterization. She's your girl for proteoform identification and characterization. 💅

✨ SYNOPSIS ✨

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

🌈 DESCRIPTION 🌈

TopPIC (Top-down mass spectrometry based Proteoform Identification and Characterization) is out here identifying and characterizing proteoforms at the proteome level by searching top-down tandem mass spectra against a protein sequence database. She is the successor to MS-Align+, periodt. She efficiently identifies proteoforms with unexpected alterations — mutations, post-translational modifications (PTMs), all the plot twists — accurately estimates the statistical significance of identifications, and characterizes reported proteoforms with unknown mass shifts. Her bag of tricks includes indexes, spectral alignment, generation function methods, and the modification identification score (MIScore), all to increase speed, sensitivity, and accuracy. iconic behavior, honestly.

1. Input 🧚

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

2. Output 🎀

TopPIC outputs two comma separated value (csv) files, an xml file, and a collection of html files for identified proteoforms. For example, when the input data file is spectra_ms2.msalign, the output includes:

  • spectra_ms2_toppic_prsm.csv: a csv file containing identified proteoform spectrum-matches (PrSMs) with an E-value or spectrum level FDR cutoff.
  • spectra_ms2_toppic_proteoform.csv: a csv file containing identified proteoforms with an E-value or proteoform level FDR cutoff.
  • spectra_ms2_toppic_proteoform.xml: an xml file containing identified proteoforms with the E-value or proteoform level FDR cutoff.
  • spectra_html/toppic_prsm_cutoff: a folder containing java script files of identified PrSMs using the E-value or spectrum level FDR cutoff.
  • spectra_html/toppic_proteoform_cutoff: a folder containing java script files of identified PrSMs using the E-value or proteoform level FDR 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 spectrum_html/topview/index.html. Google Chrome is recommended (Firefox and IE are not recommended). trust, bestie, use Chrome.

When the input contains two or more data files, TopPIC 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_toppic_prsm.csv: a csv file containing PrSMs identified from all the input files with an E-value or spectrum level FDR cutoff.
  • combined_ms2_toppic_proteoform.csv: a csv file containing proteoforms identified from all the input files with an E-value or proteoform level FDR cutoff.
  • combined_ms2_toppic_proteoform.xml: an xml file containing proteoforms identified from all the input files with the E-value or proteoform level FDR cutoff.
  • combined_html/toppic_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/toppic_proteoform_cutoff: a folder containing java script files of PrSMs identified from all the input files using the E-value or proteoform level FDR cutoff.
  • combined_html/topview: a folder containing html files for the visualization of identified PrSMs.

💅 OPTIONS 💅

  • -h, --help — Print the help message. the "help me bestie" button.
  • -a, --activation <CID|HCD|ETD|UVPD|FILE> — Set the fragmentation method(s) of MS/MS spectra. When FILE is selected, the fragmentation methods of spectra are given in the input spectrum 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 containing the information of 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.
  • -e, --mass-error-tolerance <a positive integer> — Set the error tolerance for precursor and fragment masses in part-per-million (ppm). Default value: 15. When the lookup table approach (-l) is used for E-value estimation, valid error tolerance values are 5, 10, and 15 ppm.
  • -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 value for unexpected mass shifts (in Dalton). Default value: 500.
  • -m, --min-shift <a number> — Set the minimum value for unexpected mass shifts (in Dalton). Default value: -500.
  • -s, --num-shift <0|1|2> — Set the maximum number of unexpected mass shifts in a PrSM. Default value: 1.
  • -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.
  • -l, --lookup-table — Use a lookup table method for computing p-values and E-values. It is faster than the default generating function approach, but it may reduce the number of identifications.
  • -r, --num-combined-spectra <a positive integer> — Set the number of combined spectra. The parameter is set to 2 (or 3) for combining spectral pairs (or triplets) generated by the alternating fragmentation mode. Default value: 1.
  • -i, --mod-file-name <a common modification file> — Specify a text file containing a list of common PTMs for proteoform characterization. The PTMs are used to identify and localize PTMs in reported PrSMs with unknown mass shifts. See an example file.
  • -H, --miscore-threshold <a number between 0 and 1> — Set the score threshold (MIScore) for filtering results of PTM characterization. Default value: 0.45.
  • -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 about 16 GB memory is needed for 4 threads.
  • -x, --no-topfd-feature — Specify that there are no TopFD feature files for proteoform identification.
  • -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 TopPIC.

🌸 EXAMPLES 🌸

okay bestie this is the part where it all clicks, like literally the moment the vibes become practical. every single one of these is a real, working invocation, so just copy-paste and go 💅

  • search one deconvoluted MS/MS spectrum file against a protein database, with feature files, and don't even stress about naming them. so you've got a spectrum file spectra_ms2.msalign and a protein database proteins.fasta, plus a feature file spectra.feature. and here's the cute part: you do not have to tell it the feature file name at all. TopPIC is gonna read the spectrum file name spectra_ms2.msalign and figure the feature file names out all by itself. main character energy fr.
toppic proteins.fasta spectra_ms2.msalign
  • search TWO deconvoluted MS/MS spectrum files against a protein database, with feature files, and smash all the identifications together. the files are spectra1_ms2.msalign and spectra2_ms2.msalign, the database is proteins.fasta, and on top of that all identifications get combined and reported under the file name "combined." 🫶
toppic -c combined proteins.fasta spectra1_ms2.msalign
spectra2_ms2.msalign
  • search EVERY deconvoluted MS/MS spectrum file chilling in the current folder against a protein database, with feature files. wildcard moment, the * does the heavy lifting 🦋
toppic proteins.fasta *_ms2.msalign
  • search one deconvoluted MS/MS spectrum file against a protein database, but with NO feature files. the -x says no features today bestie 🙈
toppic -x proteins.fasta spectra_ms2.msalign
  • search one deconvoluted MS/MS spectrum file against a protein database with feature files, plus a fixed modification. specifically carbamidomethylation on cysteine, and the code for it is C57 ✨
toppic -f C57 proteins.fasta spectra_ms2.msalign
  • search one deconvoluted MS/MS spectrum file against a protein database with feature files, and cap the mass shifts. in an identified proteoform, at most 2 mass shifts are allowed, and the maximum allowed mass shift value is 10,000 Dalton 😤
toppic -s 2 -M 10000 proteins.fasta spectra_ms2.msalign
  • search one deconvoluted MS/MS spectrum file against a protein database with feature files, with a 5 ppm error tolerance for precursor and fragment masses. tiny tolerance, big precision, we love to see it 🎀
toppic -e 5 proteins.fasta spectra_ms2.msalign
  • search one deconvoluted MS/MS spectrum file against a protein database with feature files, and get your FDRs under control. 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 a lot of filtering and honestly? correct behavior 💖
toppic -d -t FDR -v 0.05 -T FDR -V 0.05 proteins.fasta
spectra_ms2.msalign
  • search one deconvoluted MS/MS spectrum file with ALTERNATING CID, HCD, and ETD spectra against a protein database with feature files. and the whole point is to combine alternating CID, HCD, and ETD spectra to increase proteoform coverage — that's the -r 3 doing its thing 🔥
toppic -r 3 proteins.fasta spectra_ms2.msalign
  • search one deconvoluted MS/MS spectrum file against a protein database with feature files, and then match up those unexpected mass shifts. once proteoforms with unexpected mass shifts are identified, TopPIC matches the mass shifts to four common PTMs: acetylation, phosphorylation, oxidation and methylation, and uses an MIScore cutoff of 0.3 to filter the reported PTM sites. the modification file common_mods.txt can be found here (as in, right where the original page links it — go grab it bestie) 📎
toppic -i common_mods.txt -H 0.3 proteins.fasta spectra_ms2.msalign
  • search one deconvoluted MS/MS spectrum file against a protein database with feature files, but make it fast. use 6 CPU threads to speed up the computation, because waiting is not the vibe ⚡
toppic -u 6 proteins.fasta spectra_ms2.msalign

💜 SEE ALSO 💜

the friend group, the squad, the other icons in this toolkit — go read them too:

  • topfd (1)
  • topmg (1)
  • topdiff (1)

🌈 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 — credit where credit is due, always 💅

👑 Author

Filippo Rusconi <lopippo@debian.org> and upstream authors (Dr. Xiaowen Liu's Lab at Indiana University-Purdue University Indianapolis and others). shoutout to the whole team fr fr 🫶

Filippo Rusconi and Indiana University-Purdue University Indianapolis.

okay that's the whole page bestie, you made it to the end 🏁 this was toppic, version 1, dated 20200521 — go identify some proteoforms and slay 💖✨🦋

📦 where this page comes from