Contents

1 Introduction

IsoBayes is a Bayesian method to perform inference on single protein isoforms. Our approach infers the presence/absence of protein isoforms, and also estimates their abundance; additionally, it provides a measure of the uncertainty of these estimates, via: i) the posterior probability that a protein isoform is present in the sample; ii) a posterior credible interval of its abundance. IsoBayes inputs liquid cromatography mass spectrometry (MS) data, and can work with both PSM counts, and intensities. When available, trascript isoform abundances (i.e., TPMs) are also incorporated: TPMs are used to formulate an informative prior for the respective protein isoform relative abundance. We further identify isoforms where the relative abundance of proteins and transcripts significantly differ. We use a two-layer latent variable approach to model two sources of uncertainty typical of MS data: i) peptides may be erroneously detected (even when absent); ii) many peptides are compatible with multiple protein isoforms. In the first layer, we sample the presence/absence of each peptide based on its estimated probability of being mistakenly detected, also known as PEP (i.e., posterior error probability). In the second layer, for peptides that were estimated as being present, we allocate their abundance across the protein isoforms they map to. These two steps allow us to recover the presence and abundance of each protein isoform.

1.1 Bioconductor installation

IsoBayes is available on Bioconductor and can be installed with the command:

if (!requireNamespace("BiocManager", quietly = TRUE)) {
    install.packages("BiocManager")
}
BiocManager::install("IsoBayes")

To access the R code used in the vignettes, type:

browseVignettes("IsoBayes")

2 Questions, issues and citation

Questions relative to IsoBayes should be reported as a new issue at BugReports.

To cite IsoBayes, type:

citation("IsoBayes")
## To cite package 'IsoBayes' in publications use:
## 
##   Bollon J, Tiberi S (2023). _IsoBayes: IsoBayes: Single Isoform
##   protein inference Method via Bayesian Analyses_.
##   doi:10.18129/B9.bioc.IsoBayes
##   <https://doi.org/10.18129/B9.bioc.IsoBayes>, R package version 1.0.0,
##   <https://bioconductor.org/packages/IsoBayes>.
## 
## A BibTeX entry for LaTeX users is
## 
##   @Manual{,
##     title = {IsoBayes: IsoBayes: Single Isoform protein inference Method via Bayesian Analyses},
##     author = {Jordy Bollon and Simone Tiberi},
##     year = {2023},
##     note = {R package version 1.0.0},
##     url = {https://bioconductor.org/packages/IsoBayes},
##     doi = {10.18129/B9.bioc.IsoBayes},
##   }

3 Load the package

Load IsoBayes:

library(IsoBayes)

4 Key options

4.1 Input data

IsoBayes works with the output of both MetaMorpheus (MM) (Solntsev et al. 2018), or Percolator (The et al. 2016) (via the OpenMS toolkit (Röst et al. 2016)). Additionally, users can also provide MS data obtained from any bioinformatics tool, as long as the input files follow the structure mentioned in the Input user-provided data Section. In our benchmarks, we tested our model using both MetaMorpheus and Percolator data, and obtained slightly better results, and a shorter runtime with MetaMorpheus.

At the bottom of the vignette, in Section OpenMS and Metamorpheus pipeline we provide example scripts for both OpenMS and Metamorpheus.

In this tutorial, we use a small dataset created by MetaMorpheus. The code to generate the data can be found here.

4.2 PSM counts vs. intensities

We can run IsoBayes on either PSM counts or intensities. In our benchmarks, we found that, although results are consistent between the two types of input data, intensities led to a marginal improvement in performance.

4.3 TPMs (optional)

If available, transcriptomics data (from short of long reads), can also be integrated in the model in the form of TPMs; this will enhance protein isoform inference. To correctly match proteomics and transcriptomics data, transcript isoform and protein isoform names must be consistent. Here, we also specify the path to TPMs (optional); which must be stored in a .tsv file with 1 row per isoform, and 2 columns:

  • ‘isoname’: a character string indicating the isoform name;
  • ‘tpm’: a numeric variable indicating the TPM counts. Column names must be ‘isoname’ and ‘tpm’.

4.4 PEP vs. FDR cutoff

Additionally, we suggest to provide the probability that peptides are erroneously detected (usually called PEP): IsoBayes will use the PEP to sample the presence/absence of each peptide; this will propagate the peptide identification uncertainty throughout the inference process. Alternatively, unreliable peptides can be discarded by specifying a peptide False Discovery Rate (FDR) threshold (also known as qvalue). We suggest using PEP with a weak FDR threshold of 0.1 (default parameters options). This is because peptides with FDR > 0.1 are usually unreliable, and associated to high error probabilities (e.g., PEP > 0.9). In our benchmarks, we found that using PEP (with and FDR threshold of 0.1) provides a (minor) increase in performace compared to the classical FDR thresholding (0.01 threshold), at the cost of a (marginally) higher runtime. If we want to disable the PEP integration, and filter based on the FDR, we can set PEP = FALSE and specify a more stringent FDR cutoff, e.g., as FDR_thd = 0.01.

5 Load the data

First, we load and process the input data using the load_data function.

5.1 Input MetaMorpheus data

We set the directory of the data (internal in the package):

data_dir = system.file("extdata", package = "IsoBayes")

We set the path to the AllPeptides.psmtsv file returned by MetaMorpheus:

path_to_peptides_psm = paste0(data_dir, "/AllPeptides.psmtsv")

We set the path (optional) to the TPMs:

tpm_path = paste0(data_dir, "/jurkat_isoform_kallisto.tsv")

5.1.1 Peptide-Spectrum Match (PSM) counts

The AllPeptides.psmtsv file contains all the information required to run IsoBayes with PSM counts; we load the file via load_data:

PSM_data_loaded = load_data(
    path_to_peptides_psm = path_to_peptides_psm,
    path_to_tpm = tpm_path
)
## We found:
## 10647 protein isoforms.
## After FDR filtering (if used), we will analyze:
## 7521 protein isoforms.
## Percentage of unique peptides:
## 46.26%

5.1.2 Intensities

If we want to run the algorithm with peptide intensities, in addition to AllPeptides.psmtsv, we also need to load a second file generated by MM: AllQuantifiedPeptides.tsv. Then, we have to set abundance_type argument to “intensities”; otherwise, the load_data function will ignore the AllQuantifiedPeptides.tsv file.

path_to_peptides_intensities = paste0(data_dir, "/AllQuantifiedPeptides.tsv")
data_loaded = load_data(
    path_to_peptides_psm = path_to_peptides_psm,
    path_to_peptides_intensities = path_to_peptides_intensities,
    abundance_type = "intensities",
    path_to_tpm = tpm_path
)
## Peptides with intensity equal to 0:
## 0.568%
## NA's intensity: 30.823%
## We found:
## 10647 protein isoforms.
## After FDR filtering (if used), we will analyze:
## 7492 protein isoforms.
## Percentage of unique peptides:
## 46.29%

5.2 Input Percolator data

IsoBayes is also compatible with the PSM file from Percolator (from the OpenMS toolkit). The README shows how to use OpenMS tools to generate an idXML file containing PSM data. Once the file has been created, we can pass its path to load_data and set input_type as “openMS”.

Percolator_data_loaded = load_data(
    path_to_peptides_psm = "/path/to/file.idXML",
    input_type = "openMS",
    path_to_tpm = tpm_path
)

Please note that when using data generated by Percolator, the algorithm can only process PSM counts and not intensities.

5.3 Input user-provided data

We can also input MS data obtained from any bioinformatics tool. To this aim, the data must be organized in a .tsv file, a data.frame or in the rowData object of a SummarizedExperiment. In all cases, each row corresponds to a peptide, and columns refer to:

  • ‘Y’: a numeric variable indicating the peptide abundance (PSM counts or intensities, as defined by the user);
  • ‘EC’: Equivalent Classes, a character string indicating the isoform(s) name the peptide maps to. If the peptide maps to multiple protein isoforms, the names must be separated with “|” , i.e. “name_isoform_1|name_isoform_2”;
  • ‘FDR’: (optional) a numeric variable indicating the FDR of each peptide;
  • ‘PEP’: (optional) a numeric variable indicating the probability that a peptide is erroneously detected;
  • ‘sequence’: (required when using PEP) a character string indicating the peptide name/id/amino acids sequence.

Note that, when using user-provided data, argument path_to_peptides_intensities is not considered, because users are free to set column Y to PSM counts or intensities.

To load user-provided data, we just need to pass the file path, the data.frame or the SummarizedExperiment object and set input_type as “other” .

# X can be a path to a .tsv file, a data.frame or a SummarizedExperiment object
user_data_loaded = load_data(
    path_to_peptides_psm = X,
    input_type = "other",
    path_to_tpm = tpm_path
)

6 Inference

Once we have loaded the data, we can run the algorithm using the inference function.

set.seed(169612)
results = inference(data_loaded)

By default, IsoBayes uses one single core. For large datasets, to speed up the execution time, the number of cores can be increased via the n_cores argument.

6.1 Gene Normalization (optional)

In order to analyse alternative splicing within a specific gene, we may want to normalize the estimated relative abundances for each set of protein isoforms that maps to a gene. To this aim, we need to input a csv file containing two columns denoting the isoform name and the gene name.

path_to_map_iso_gene = paste0(data_dir, "/map_iso_gene.csv")
set.seed(169612)
results_normalized = inference(data_loaded, map_iso_gene = path_to_map_iso_gene)

Specifying the map_iso_gene argument, also enables users to plot results via plot_relative_abundances function.

7 Visualizing results

Results are stored as a list with three data.frame objects: ‘isoform_results’, ‘normalized_isoform_results’ and ‘gene_abundance’. If ‘map_iso_gene’ was not provided, only ‘isoform_results’ is returned.

names(results_normalized)
## [1] "isoform_results"            "normalized_isoform_results"
## [3] "gene_abundance"

Inside the ‘isoform_results’ data.frame, each row corresponds to a protein isoform. The columns report the following results:

head(results_normalized$isoform_results)
##    Gene   Isoform Prob_present Abundance CI_LB CI_UB           Pi     Pi_CI_LB
## 1 AAGAB AAGAB-201        0.626     1.278     0     3 1.619661e-05 2.746699e-10
## 2 AAGAB AAGAB-203        0.769     1.722     0     3 2.119815e-05 3.110762e-10
## 3  AAK1  AAK1-201        0.608     1.246     0     3 1.213651e-05 4.082657e-36
## 4  AAK1  AAK1-203        0.501     1.035     0     3 1.047273e-05 9.205197e-29
## 5  AAK1  AAK1-211        0.763     3.355     0     6 3.275675e-05 9.006062e-14
## 6  AAK1  AAK1-212        0.627     2.364     0     6 2.295597e-05 3.450492e-15
##       Pi_CI_UB       TPM    Log2_FC Prob_prot_inc
## 1 4.775833e-05 17.284100 -1.4811946         0.062
## 2 5.229594e-05 26.384500 -1.7031935         0.010
## 3 4.110602e-05  1.625010  1.5133916         0.586
## 4 3.745038e-05  0.632271  2.6625088         0.556
## 5 8.082293e-05 11.637600  0.1055574         0.504
## 6 7.418921e-05  7.264770  0.2724388         0.447

In ‘normalized_isoform_results’ data.frame, we report the protein isoform relative abundances, normalized within each gene (i.e., adding to 1 within a gene).

head(results_normalized$normalized_isoform_results)
##    Gene   Isoform   Pi_norm Pi_norm_CI_LB Pi_norm_CI_UB Pi_norm_TPM
## 1 AAGAB AAGAB-201 0.4258653  1.891150e-05     0.9682488  0.39580156
## 2 AAGAB AAGAB-203 0.5741347  3.175120e-02     0.9999811  0.60419844
## 3  AAK1  AAK1-201 0.1573195  6.842824e-32     0.4668099  0.07679758
## 4  AAK1  AAK1-203 0.1322452  1.750025e-24     0.4625652  0.02988097
## 5  AAK1  AAK1-211 0.4172822  1.155285e-09     0.8485678  0.54999017
## 6  AAK1  AAK1-212 0.2931531  5.771833e-11     0.8236290  0.34333128

In ‘gene_abundance’ data.frame, for each gene (row) we return:

head(results_normalized$gene_abundance)
##    Gene Abundance CI_LB CI_UB
## 1 AAGAB     3.000     3     3
## 2  AAK1     8.000     8     8
## 3  AAMP    12.127     8    13
## 4  AAR2     7.000     7     7
## 5 AARS1   111.980   112   112
## 6 AARS2     4.000     4     4

Finally, IsoBayes provides the plot_relative_abundances function to visualize protein-level and transcript-level relative abundances across the isoforms of a specific gene:

plot_relative_abundances(results_normalized, gene_id = "TUBB")

By default plot_relative_abundances normalizes the relative abundances within genes (again, adding to 1 within a gene). To disable the normalization, set the normalize_gene argument to FALSE:

plot_relative_abundances(results_normalized, gene_id = "TUBB", normalize_gene = FALSE)

Note that plot_relative_abundances can be used only when, in the map_iso_gene argument of the inference function, we provide a csv file that maps the protein isoforms to the corresponding gene (path_to_map_iso_gene in this case).

8 Session info

sessionInfo()
## R version 4.3.1 (2023-06-16)
## Platform: x86_64-pc-linux-gnu (64-bit)
## Running under: Ubuntu 22.04.3 LTS
## 
## Matrix products: default
## BLAS:   /home/biocbuild/bbs-3.18-bioc/R/lib/libRblas.so 
## LAPACK: /usr/lib/x86_64-linux-gnu/lapack/liblapack.so.3.10.0
## 
## locale:
##  [1] LC_CTYPE=en_US.UTF-8       LC_NUMERIC=C              
##  [3] LC_TIME=en_GB              LC_COLLATE=C              
##  [5] LC_MONETARY=en_US.UTF-8    LC_MESSAGES=en_US.UTF-8   
##  [7] LC_PAPER=en_US.UTF-8       LC_NAME=C                 
##  [9] LC_ADDRESS=C               LC_TELEPHONE=C            
## [11] LC_MEASUREMENT=en_US.UTF-8 LC_IDENTIFICATION=C       
## 
## time zone: America/New_York
## tzcode source: system (glibc)
## 
## attached base packages:
## [1] stats     graphics  grDevices utils     datasets  methods   base     
## 
## other attached packages:
## [1] IsoBayes_1.0.0   BiocStyle_2.30.0
## 
## loaded via a namespace (and not attached):
##  [1] SummarizedExperiment_1.32.0 gtable_0.3.4               
##  [3] xfun_0.40                   bslib_0.5.1                
##  [5] ggplot2_3.4.4               Biobase_2.62.0             
##  [7] lattice_0.22-5              vctrs_0.6.4                
##  [9] tools_4.3.1                 bitops_1.0-7               
## [11] generics_0.1.3              stats4_4.3.1               
## [13] parallel_4.3.1              tibble_3.2.1               
## [15] fansi_1.0.5                 pkgconfig_2.0.3            
## [17] Matrix_1.6-1.1              data.table_1.14.8          
## [19] S4Vectors_0.40.0            rngtools_1.5.2             
## [21] HDInterval_0.2.4            lifecycle_1.0.3            
## [23] GenomeInfoDbData_1.2.11     farver_2.1.1               
## [25] compiler_4.3.1              munsell_0.5.0              
## [27] codetools_0.2-19            GenomeInfoDb_1.38.0        
## [29] htmltools_0.5.6.1           sass_0.4.7                 
## [31] RCurl_1.98-1.12             yaml_2.3.7                 
## [33] pillar_1.9.0                crayon_1.5.2               
## [35] jquerylib_0.1.4             DelayedArray_0.28.0        
## [37] cachem_1.0.8                magick_2.8.1               
## [39] doRNG_1.8.6                 iterators_1.0.14           
## [41] abind_1.4-5                 foreach_1.5.2              
## [43] tidyselect_1.2.0            digest_0.6.33              
## [45] dplyr_1.1.3                 bookdown_0.36              
## [47] labeling_0.4.3              fastmap_1.1.1              
## [49] grid_4.3.1                  colorspace_2.1-0           
## [51] cli_3.6.1                   SparseArray_1.2.0          
## [53] magrittr_2.0.3              S4Arrays_1.2.0             
## [55] utf8_1.2.4                  withr_2.5.1                
## [57] scales_1.2.1                rmarkdown_2.25             
## [59] XVector_0.42.0              matrixStats_1.0.0          
## [61] evaluate_0.22               knitr_1.44                 
## [63] GenomicRanges_1.54.0        IRanges_2.36.0             
## [65] doParallel_1.0.17           rlang_1.1.1                
## [67] Rcpp_1.0.11                 glue_1.6.2                 
## [69] BiocManager_1.30.22         BiocGenerics_0.48.0        
## [71] jsonlite_1.8.7              R6_2.5.1                   
## [73] MatrixGenerics_1.14.0       zlibbioc_1.48.0

9 OpenMS and Metamorpheus pipeline

IsoBayes works directly with the output of MetaMorpheus, or Percolator (via the OpenMS toolkit). Additionally, users can also provide MS data obtained from any bioinformatics tool, as long as the input files follow the structure mentioned in the Input user-provided data Section IsoBayes works with the output of both MetaMorpheus (MM) (Solntsev et al. 2018), or Percolator (The et al. 2016) (via the OpenMS toolkit (Röst et al. 2016)). Additionally, users can also provide MS data obtained from any bioinformatics tool, as long as the input files follow the structure mentioned in the Input user-provided data Section.

Below, we provide example scripts for both OpenMS and Metamorpheus.

9.1 MetaMorpheus pipeline

To generate the MM output files required to run IsoBayes, we need to execute the following commands:

  • Install MetaMorpheus via Conda:
conda install -c conda-forge metamorpheus
  • Inside the folder with the configuration (.toml), spectra (.mzML or .raw) and database (.xml) files run:
metamorpheus -t Task1-SearchTaskconfig.toml Task2-CalibrateTaskconfig.toml Task3-SearchTaskconfig.toml Task4-GPTMDTaskconfig.toml Task5-SearchTaskconfig.toml -s 04-30-13_CAST_Frac4_6uL.raw 04-30-13_CAST_Frac5_4uL.raw -d uniprot-mouse-reviewed-1-24-2018.xml.gz uniprot-cRAP-1-24-2018.xml.gz

or

metamorpheus -t Task1-SearchTaskconfig.toml Task2-CalibrateTaskconfig.toml Task3-SearchTaskconfig.toml Task4-GPTMDTaskconfig.toml Task5-SearchTaskconfig.toml -s mzML/04-30-13_CAST_Frac4_6uL.mzML mzML/04-30-13_CAST_Frac5_4uL.mzML -d uniprot-mouse-reviewed-1-24-2018.xml.gz uniprot-cRAP-1-24-2018.xml.gz

There are several ways to install and run MM. For more details see the MM tutorial, where you can also find the example files used here.

9.2 Percolator pipeline

We provide a brief pipeline where several OpenMS applications are chained together to generate an idXML file required to run IsoBayes with Percolator output. The pipeline starts from peptide identification results stored in mzID files.

First, install OpenMS toolkit and Percolator tool. For instructions on how to install them on your operating system see OpenMS Installation and Percolator Installation.

Next, declare some useful global variable:

path_to_data=/path/to/mzIDfiles
path_out=/path/to/output
NTHREADS=4
ENZYME_indexer="Chymotrypsin"
ENZYME_percolator="chymotrypsin"
DECOY_STRING="mz|DECOY_"
fdr=1

Below, we show an example with chymotrypsin enzyme. If the data was generated with another enzyme, please search for the corresponding enzyme in the documentation below, and reset the global variables ENZYME_indexer and ENZYME_percolator with the correct enzyme.

PeptideIndexer --help
PercolatorAdapter --help

This pipeline also assumes that in the /path/to/mzIDfiles folder there is a fasta file listing target and decoy protein isoforms. The DECOY_STRING allows you to change the string needed to identify a decoy in the fasta file.

cd $path_out

# convert mzID files into idXML files
for mz in $path_to_data/*.mzID
do
        IDFileConverter -in $mz -threads $NTHREADS -out $mz.idXML
done

# merge the files
IDMerger -in $path_to_data/*.idXML -threads $NTHREADS -merge_proteins_add_PSMs -out $path_out/merge.idXML
rm $path_to_data/*.idXML

# index the peptide file with the fasta file
PeptideIndexer -in $path_out/merge.idXML -enzyme:name $ENZYME_indexer -threads $NTHREADS -decoy_string_position prefix -decoy_string $DECOY_STRING -fasta $path_to_data/genecodeAndDecoy.fasta -out $path_out/merge_index.idXML
rm $path_out/merge.idXML

# run percolator
PercolatorAdapter -in $path_out/merge_index.idXML -enzyme $ENZYME_percolator -threads $NTHREADS -generic_feature_set -score_type pep -out $path_out/merge_index_percolator_pep.idXML
rm $path_out/merge_index.idXML

# Estimate the false discovery rate on peptide level using decoy searches and keep the ones with FDR < $fdr
FalseDiscoveryRate -in $path_out/merge_index_percolator_pep.idXML -out $path_out/merge_index_percolator_pep_$fdr.idXML -protein false -threads $NTHREADS -FDR:PSM $fdr -algorithm:add_decoy_peptides -algorithm:add_decoy_proteins
rm $path_out/merge_index_percolator_pep.idXML

# Associate each peptite with Posterior Error Probability score
IDScoreSwitcher -in $path_out/merge_index_percolator_pep_$fdr.idXML -out $path_out/merge_index_percolator_pep_switched_$fdr.idXML -new_score 'Posterior Error Probability_score' -new_score_orientation lower_better -new_score_type pep -threads $NTHREADS
rm $path_out/merge_index_percolator_pep_$fdr.idXML

For more details on OpenMS tools see its Documentation.

References

Röst, Hannes L, Timo Sachsenberg, Stephan Aiche, Chris Bielow, Hendrik Weisser, Fabian Aicheler, Sandro Andreotti, et al. 2016. “OpenMS: A Flexible Open-Source Software Platform for Mass Spectrometry Data Analysis.” Nature Methods 13 (9): 741–48.

Solntsev, Stefan K, Michael R Shortreed, Brian L Frey, and Lloyd M Smith. 2018. “Enhanced Global Post-Translational Modification Discovery with Metamorpheus.” Journal of Proteome Research 17 (5): 1844–51.

The, Matthew, Michael J MacCoss, William S Noble, and Lukas Käll. 2016. “Fast and Accurate Protein False Discovery Rates on Large-Scale Proteomics Data Sets with Percolator 3.0.” Journal of the American Society for Mass Spectrometry 27: 1719–27.