The Shinyscreen Package

Overview

Shinyscreen R package is an application intended to give the user a first look into raw mass-spectrometry data. This currently means that, given the input of data files and a list of masses of know, or unknown compounds, the application is going to produce the MS1 and MS2 chromatograms of the substances in the list, as well as the MS2 spectra. None of these features have been post-processed in the slightest. However, there is a built-in prescreening aid that will help the user assess the quality of the spectra.

The application is powered by the MSnbase package and built as a Shiny web application.

Installation

The Worst Case Scenario

The major issue users, especially those on Windows, will often experience is the conflict between x64 and x32 architecture of the Java installations and how they interact with many installation methods of R packages and their unfortunate default settings.

It seems that the best way to overcome the issue is to be consistent in installation of only single architecture packages. Various R install routines do not really help with this.

Steps for x64

1. Download and install the latest Java runtime. We tested the most recent installation method with OpenJDK Java. During the installation, you will be presented with two by default disabled options, the JAVA_HOME and the registry key entry. While the installation may work with both of those left unchecked and fiddling later with the environment variables in R itself, it seems easier to just switch both the JAVA_HOME and the registry key on. As a side note, the procedure should work for the proprietary Oracle Java variant as well, but this was not very thorougly tested.
2. Download and install R and RStudio. After running RStudio, make sure that the R session it uses is indeed x64. Which session is being used can be discovered in the Tools>Global Options>General menu (R Sessions).
3. During the procedure, there may be packages that can be be prevented from being installed by mostly harmless warnings. This is why the first order of business is to prevent this from happening.

   Sys.setenv(R_REMOTES_NO_ERRORS_FROM_WARNINGS="true")
       

4. From now on, it is essential to pass the *INSTALL_opts=”–no-multiarch”* keyword argument to any install method which will be called subsequently.
5. Get devtools and BiocManager.

   install.packages(c("devtools","BiocManager"),INSTALL_opts="--no-multiarch")
       

6. Get rJava, rcdk and rcdklibs.

   install.packages(c("rJava","rcdk","rcdklibs"),INSTALL_opts = "--no-multiarch")
       

7. Get RMassBank.

   BiocManager::install("RMassBank", INSTALL_opts = "--no-multiarch")
       

8. Get rsvg and enviPat.

   install.packages(c("rsvg","enviPat"), INSTALL_opts = "--no-multiarch")
       

9. Now, the big challenge - install RChemMass.

   devtools::install_github("schymane/RChemMass", dependencies = F, INSTALL_opts = "--no-multiarch")
       

10. If the previous step worked, it only remains to install Shinyscreen.

    devtools::install_url("https://git-r3lab.uni.lu/eci/shinyscreen/-/archive/master/shinyscreen-master.tar.gz", INSTALL_opts="--no-multiarch")
        

    That’s it! Not exactly a piece of cake.

Problems that can arise

• rJava cannot be loaded, because of some DLL. Either you did not follow the “–no-multiarch” rule, or you have conflicting JAVA_HOME, maybe even Jave registry settings. Try playing around with JAVA_HOME environment variable, for example, try setting it either to “”, or to the path of your Java JRE installation (somewhere inside Program Files).
• If nothing helps, try the Previously Recommended Method

Steps for x32

Not tested, but the procedure should be exactly as outlined above, except that it would be required to install Java x32 bit runtime and make sure RStudio loads x32 bit R session.

Previously Recommended Method

This was only tested successfully with Oracle’s JRE (please let us know if you manage to achieve the same results with OpenJDK). The steps are same as above with the following exceptions.

• Ensure that both 32 bit and 64 bit versions are available for 64 bit systems. In case of Windows, check in `C:\Program Files\Java` and `C:\Program Files (x86)\Java`.
• Drop the INSTALL_opts keyword (as we now have two architectures in parallel).
• Detailed explanation of this method is given here.

Less Bad Scenario

You are on a OS with the sane package dependency management (i.e one of the GNU/Linux distributions). There is a reason why people put effort into packaging R software for the distribution (R package management sucks). Try to install as many dependencies as possible from your official distro channels, then fill the gaps using the standard R installation frameworks. One caveat here is tha some distros that focus on stability (such as Debian stable, or various so-called LTS editions) may have outdated R versions. This might not play well with some dependencies that are changing on shorter time-scales. The solution is to keep your R installation fresh.

Steps for Debian-likes (Taken From the Dockerfile)

Install the dependencies like this,

apt-get update
apt-get install -y --no-install-recommends apt-utils r-base r-recommended g++ gfortran
apt-get install -y --no-install-recommends curl libxml2-dev libssl-dev libssh2-1-dev zlib1g-dev
apt-get install -y --no-install-recommends xdg-utils automake autoconf gcc make pkg-config
apt-get install -y --no-install-recommends net-tools git-all default-jre-headless zlib1g zlib1g-dev 
apt-get install -y --no-install-recommends libnetcdf* openbabel libhdf5-1* libhdf5-hl-1*
apt-get install -y --no-install-recommends r-cran-rcolorbrewer r-cran-data.table r-cran-biocmanager r-cran-tidyverse r-cran-cowplot
apt-get install -y --no-install-recommends r-cran-curl r-cran-promises r-cran-yaml
apt-get install -y --no-install-recommends r-cran-dt r-cran-future
apt-get install -y --no-install-recommends r-cran-rjava r-cran-rsvg r-cran-png
apt-get install -y --no-install-recommends r-cran-rmarkdown r-cran-shiny r-cran-htmltools
apt-get install -y --no-install-recommends r-cran-rcdklibs r-cran-rcdk r-cran-fingerprint
apt-get install -y --no-install-recommends r-bioc-affy r-bioc-affyio
apt-get install -y --no-install-recommends r-cran-devtools
apt-get install -y --no-install-recommends libpng16-16 libpng-tools libpng-dev libpng++-dev

R -e 'install.packages("enviPat", dependencies=TRUE)'
R -e 'BiocManager::install(c("Rhdf5lib","mzR","MSnbase","RMassBank"),update=F)'
R -e 'devtools::install_git("https://github.com/CDK-R/rinchi", dependencies=F)'
R -e 'devtools::install_git("https://github.com/schymane/RChemMass", dependencies=F)'

# If you want MetFrag.
curl -LJO https://github.com/ipb-halle/MetFragRelaunched/releases/download/v.2.5.0/MetFragCommandLine-2.5.0.jar
mv MetFragCommandLine-2.5.0.jar /usr/local/bin/MetFragCommandLine.jar
chmod 0555 /usr/local/bin/MetFragCommandLine.jar

# If you want PubChemLite and MetFrag.
curl -LJO https://zenodo.org/record/7576412/files/PubChemLite_exposomics_20230127.csv?download=1
mkdir /usr/local/metfrag_db
chmod 0555 /usr/local/metfrag_db
mv PubChemLite_exposomics_20230127.csv /usr/local/metfrag_db/PubChemLite_exposomics.csv 

Running Shinyscreen

Terminology

Project directory

This is directory containing Shinyscreen inputs (except the mzML files), intermediate and output files. The inputs are compound and set lists (information on the list inputs is available from Shinyscreen GUI application itself).

Data directory

A data directory contains mzML files.

Projects directory

A directory containing the Shinyscreen project directories.

Top data directory

This directory contains the data directories.

Metfrag databases directory

It contains MetFrag csv databases.

Metfrag JAR path

This is the location of the MetFrag Command Line java runtime.

Java JRE path

The location of Java executable.

Number of Shinyscreen threads

Maximum threads that Shinyscreen can use to parallelise extraction effort. Note that there is (for now), no gain in assigning more threads than the number of mzML files. The absolute maximum of threads is equal to a number of (logical) CPU cores.

Number of MetFrag processes

Number of MetFrag processes. Maximum number is the number of (logical) CPU cores available.

Initialisation

Everything except the number of Shinyscreen threads and the individual project and data directory can be set up using Shinyscreen’s initialisation function init. The number of threads is something defined using package future, before running Shinyscreen, like this:

future::plan("sequential") #Resets the current plan.
future::plan("multisession",workers=4L) #Sets the new plan.

In general, Shinyscreen init function is called like this,

library(shinyscreen)
opts = init(projects="/path/to/projects/dir",
            top_data_dir="/path/to/top-data-directory",
            metfrag_jar="/path/to/metfrag-jar-file",
            metfrag_db_dir="/path/to/metfrag-databases-directory",
            java_bin="/path/to/java/executable",
            metfrag_max_proc=4L)

Then, we run shinyscreen like this,

app(envopts=opts)

Note the port on the localhost (127.0.0.1) Shinyscreen has started and open it in some web browser.

You can start Shinyscreen web application “automatically” if you run,

app(envopts=opts, shiny_args=list(launch.browser=T))  

Note that the environment options — the return value of init — can be stored if you pass save=T argument in a call to init like this,

library(shinyscreen)
opts = init(projects="/path/to/projects/dir",
            top_data_dir="/path/to/top-data-directory",
            metfrag_jar="/path/to/metfrag-jar-file",
            metfrag_db_dir="/path/to/metfrag-databases-directory",
            java_bin="/path/to/java/executable",
            metfrag_max_proc=4L,
            save=T)

After storing configuration, the next time you want to run app, it is enough to,

library(shinyscreen)
opts = init() #This loads stored values.
app(envopts=opts)

If, after storing, you want to change some of the configuration entries, this is also possible,

library(shinyscreen)
opts = init(metfrag_db_dir="/some/other/metfrag-databases-directory") #Loads
                                                                      #other
                                                                      #saved
                                                                      #values
                                                                      #and
                                                                      #replaces
                                                                      #metfrag_db_dir
                                                                      #with
                                                                      #the
                                                                      #new
                                                                      #value.
app(envopts=opts)

In order to store the updated value, you need to pass save=T again.

If you do not pass java_bin and metfrag_max_proc arguments to init, the application will try to deduce the location of java JRE runtime and the maximum number of possible processes for MetFrag automatically.

Additionally, if you are not interested in MetFrag functionality, do not pass metfrag_db_dir to init.

Usage

Shinyscreen is a self-documented application. The best way to learn about using Shinyscreen is by running it. Please let us know if we can improve on that documentation.

Thanks

Many thanks to the students of the Masters in Integrated Systems Biology course (2020–2023) for installing, debugging, testing.