README.org

#+TITLE: 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 [[https://adoptopenjdk.net][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.
       #+BEGIN_SRC R
       Sys.setenv(R_REMOTES_NO_ERRORS_FROM_WARNINGS="true")
       #+END_SRC

    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. 
       #+BEGIN_SRC R
         install.packages(c("devtools","BiocManager"),INSTALL_opts="--no-multiarch")
       #+END_SRC

    6. Get rJava, rcdk and rcdklibs.
       #+BEGIN_SRC R
         install.packages(c("rJava","rcdk","rcdklibs"),INSTALL_opts = "--no-multiarch")
       #+END_SRC

    7. Get RMassBank.
       #+BEGIN_SRC R
         BiocManager::install("RMassBank", INSTALL_opts = "--no-multiarch")
       #+END_SRC

    8. Get rsvg and enviPat.
       #+BEGIN_SRC R
         install.packages(c("rsvg","enviPat"), INSTALL_opts = "--no-multiarch")
       #+END_SRC

    9. Now, the big challenge - install RChemMass.
       #+BEGIN_SRC R
         devtools::install_github("schymane/RChemMass", dependencies = F, INSTALL_opts = "--no-multiarch")
       #+END_SRC

    10. If the previous step worked, it only remains to install Shinyscreen.
       #+BEGIN_SRC R
         devtools::install_url("https://git-r3lab.uni.lu/eci/shinyscreen/-/archive/master/shinyscreen-master.tar.gz", INSTALL_opts="--no-multiarch")
       #+END_SRC
       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 [[https://www.java.com/en/][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 [[https://github.com/schymane/RChemMass/blob/master/README_installation.txt][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.

** Good Scenario
   You have [[https://guix.gnu.org/][Guix]] installed. Great. Just subscribe to ECI's Guix
   [[https://git-r3lab.uni.lu/eci/eci-pkg-menu][channel]] and install from there.

* Running Shinyscreen
  Provided Shinyscreen is successfully installed this snippet will
  run it.
  #+BEGIN_SRC R
    shinyscreen::app()
  #+END_SRC
  
* Usage
  Shinyscreen (version > 1.0.0) 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 (March 2020)

  - *Tessy Prohaska*
  - *Jeff Didier*
  - *Claudia Cipriani*
  - *Parviel Chirsir*

  for boldly wading through the Windows installation procedure, a task
  that led to more clarity in the docs.