.. _`ris-rstudio`:

=======
RStudio
=======

.. contents::
   :depth: 1
   :local:

.. admonition:: Compute Resources

    - Have questions or need help with compute, including activation or issues?
      Follow `this link. <https://washu.atlassian.net/servicedesk/customer/portal/2/group/6/create/43>`__
    - :ref:`User Agreement <compute-user-agreement>`

.. _`ris-rstudio-docker`:

.. admonition:: Docker Usage

    - The information on this page assumes that you have a knowledge base of
      using Docker to create images and push them to a repository for use. If
      you need to review that information, please see the links below.
    - :ref:`Docker and the RIS Compute Service <docker-on-compute>`
    - :ref:`Docker Basics: Building, Tagging, & Pushing A Custom Docker Image <ris-docker-basics>`

.. _`ris-rstudio-software`:

Image Details
-------------

- Docker image hosted at ghcr.io/washu-it-ris/rstudio
- noVNC (https://novnc.com/info.html)
- RStudio (https://rstudio.com/)
- R (https://www.r-project.org/)
- Optional: Seurat (https://satijalab.org/seurat/)

.. _`rstudio-initial-setup`:

Initial Setup
-------------

R installs a default set of packages during installation. The list of installed
packages can be viewed in the lower right pane of RStudio, with currently active
packages indicated with a checkmark.

.. image:: ../images/rstudio-packages.png

If you wish to install additional packages, you can do so by first creating a
file in your home directory called ``.Rprofile``, if it doesn't already exist.
This file will be loaded automatically when RStudio starts.

.. code::

    > touch ~/.Rprofile

Next, create a folder to host your additional R packages. In the example below,
the R packages will be stored in a folder named ``R_libraries`` in the Active
folder of your storage allocation.

.. admonition:: Storage Allocation Name

    Make sure to replace ``${STORAGE_ALLOCATION}`` with the same name as the
    name of your storage allocation.

.. code::

    mkdir /storage1/fs1/${STORAGE_ALLOCATION}/Active/R_libraries/

Backup an existing ``.Rprofile`` file if you have one.

.. code::

        mv ~/.Rprofile ~/.Rprofile.bak

Create a new ``.Rprofile`` file to store your additional R packages in storage1.

.. code::

    cat <<EOF > $HOME/.Rprofile
    vals <- paste('/storage1/fs1/${STORAGE_ALLOCATION}/Active/R_libraries/',paste(R.version$major,R.version$minor,sep="."),sep="")
    for (devlib in vals) {
        if (!file.exists(devlib))
        dir.create(devlib)
    x <- .libPaths()
    x <- .libPaths(c(devlib,x))
    }
    rm(x,vals)
    EOF

Now that the ``.Rprofile`` file is created, you can install additional R
packages using ``install.packages()``. Please see
https://www.rdocumentation.org/packages/utils/versions/3.6.2/topics/install.packages
for more information.

.. _`ris-rstudio-gui`:

Interactive GUI Session
-----------------------

- Interactions GUI sessions are done via the ``Custom noVNC Image`` application in Open On Demand (OOD).
- You can find out more about OOD here: :ref:`Compute Quick Start <compute-quick-start>`.
- There are two fields beyond the basics that will need information specific to this image.
    - Environment Variables
    - Docker Image

Environment Variables
~~~~~~~~~~~~~~~~~~~~~

- This information should be space separated in the field.

.. code::

    PASSWORD=password

- Optional variables
    - GUI display size. This can be changed with the following variables.
        - Width default: 1024
        - Height default: 768

    .. code::

        DISPLAY_WIDTH=<width> DISPLAY_HEIGHT=<height>

Docker Image
~~~~~~~~~~~~

.. code::

    ghcr.io/washu-it-ris/rstudio:<tag>

.. _`rstudio-docker-tag`:

.. admonition:: RStudio Docker Tag

    The ``<tag>`` will refer to the version of RStudio in the Docker container.
    Please click :ref:`here <rstudio-versions>` to see a current list of
    available RStudio versions and their corresponding Docker images.

- Fill out the rest of the fields with the appropriate information (explained in the quick start).
- Launch the job through the methods described in the quick start.
- Once in an interactive RStudio session using the following command:

.. code::

    > rstudio

You should now see the RStudio GUI

.. image:: ../images/rstudio-success.png

.. note::
    You can safely ignore ``XDG_RUNTIME_DIR`` and ``Session version X does
    not match server version X`` warnings that may appear when starting RStudio.

Interactive Command-Line Session
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- If you wish to use R in an interactive command-line
  session, you can do so with the following commands.

.. code::

    export LSF_DOCKER_VOLUMES="/storage1/fs1/${STORAGE_ALLOCATION}/Active:/storage1/fs1/${STORAGE_ALLOCATION}/Active"
    bsub -Is -q general-interactive -a 'docker(ghcr.io/washu-it-ris/rstudio:<tag>)' /bin/bash

.. _`rstudio-extend`:

Availability Through Open On Demand (OOD)
-----------------------------------------

- Currently there are limitations on the version of Rstudio that can be made available through a stand alone Docker image.
- This can cause an issue with some packages.
- Rstudio is available through the THPC platform, available in OOD.
    - :ref:`More on THPC here.<ris-thpc-quickstart>`
    - :ref:`More on OOD here.<compute-ood>`

Starting Rstudio
~~~~~~~~~~~~~~~~

- First you need to start up an instance of THPC (Compute RIS Desktop) in OOD.
- Next you need to load and launch Rstudio-server through the terminal.

.. code::

    module load RStudio-Server
    rstudio-server start

- After launching Rstudio, you need to open a new shell.
    - Right click in the noVNC window.
    - Select "Application" > "Shell" > "Bash"

.. image:: ../images/rstudio-new-terminal.png

- Finally, you need to load and launch Firefox, connecting to Rstudio, in the new shell.

.. code::

    module load Firefox
    firefox http://localhost:8787

Extending the RStudio Docker Image
----------------------------------

The steps in the :ref:`initial setup <rstudio-initial-setup>` will work for some
but not all R packages. For example, ``devtools`` requires the following
dependencies to be installed to the Docker image: ``build-essential
libcurl4-gnutls-dev libxml2-dev libssl-dev``.

This will require extending the existing Docker image to include these
dependencies. Below is a sample Dockerfile that includes these dependencies.
Please see :ref:`this section <rstudio-docker-tag>` for more information on
setting the Docker tag in the Dockerfile.

.. admonition:: Dockerfile Best Practices

    It is recommended to set the Docker tag to a specific R version. This will
    prevent using an updated version of the RIS RStudio image, which may have
    compatibility issues with R packages previously installed. As an example, in
    the Dockerfile below, the tag is set to ``3.6.3``.

.. code::

    FROM gcr.io/ris-registry-shared/rstudio:3.6.3

    # install packages using apt-get

    ENV LANG=C.UTF-8 LC_ALL=C.UTF-8
    ARG DEBIAN_FRONTEND=noninteractive
    RUN apt-get update --fix-missing && \
    apt-get install -y build-essential \
    libcurl4-gnutls-dev libxml2-dev \
    libssl-dev && \
    apt-get clean

    # extend image to include tidyverse and devtools R packages

    RUN R -e "install.packages(c('devtools','tidyverse'), dependencies=TRUE)"

Please see :ref:`our Docker Workshop <ris-docker-workshop>` for more information
on building and pushing a Docker image. You can also open a ticket at our
`Service Desk <https://washu.atlassian.net/servicedesk/customer/portal/2/group/6/create/43>`__ for
further help.

.. _`rstudio-versions`:

Available RStudio Versions
--------------------------

Current Version:
~~~~~~~~~~~~~~~~
- Stand Alone Docker Image Version
    - ghcr.io/washu-it-ris/rstudio
        - 4.3.0
- THPC Version
    - 4.2.1

Earlier Versions:
~~~~~~~~~~~~~~~~~

Earlier versions are still available but no longer directly supported by RIS.
Please refer to the latest version for direct support.

- gcr.io/ris-registry-shared/rstudio
    - 4.2.3
    - 4.2.2
    - 4.1.2
    - 4.1.2_seurat_4.1.1
    - 4.0.0
    - 3.6.3