RStudio is available as an integrated application on the All of Us Researcher Workbench. The app runs on a virtual machine in your workspace cloud environment. 

RStudio provides a richer integrated environment for R development than the R terminal or Jupyter notebooks. The app includes a variable explorer, an R Markdown editor, a debugger, and an R terminal.

In this article, we will describe how using RStudio on the cloud can be different than on a desktop app and we’ll give step-by-step instructions to start the RStudio app, save your data, and stop the app. To learn more, read Using the Cohort and Dataset Builders with RStudio. Please also view our video tutorial of using RStudio in the Researcher Workbench here. 

Table of Contents

• RStudio on the Cloud
• Starting RStudio 
• File synchronization between the workspace bucket and the persistent disk
• Using RStudio files within the app
• Accessing workspace storage from the RStudio console and terminal
• Stopping the RStudio application
• Making an RShiny app with RStudio
• Accessing the RStudio tutorial in the Researcher Workbench 
• Other helpful material 

RStudio on the Cloud

The first step to running the RStudio app is to start a cloud environment. The RStudio app runs on a virtual machine (VM) or clusters of machines in your workspace cloud analysis environment. The RStudio cloud environment on the Researcher Workbench is a VM with 4 CPUs, 15 GB RAM, and 100 GB of disk space and is not customizable. 

Cloud Storage

There are two dedicated storage locations when using RStudio on the cloud: the persistent disk and the workspace bucket. 

The persistent disk is created when you start the RStudio app, and it is attached to the cloud environment. The persistent disk can be saved even if you stop the cloud environment, and it can be re-attached to your next cloud environment in the workspace. The data on your persistent disk is not shareable and is only available to the researcher who created the RStudio app. Read Persistent Disk: Managing & Deleting for information related to persistent disks.

Using the workspace bucket is helpful for saving your work and sharing your work with workspace collaborators. Data can be copied by the owner of the persistent disk to a shareable workspace bucket. Further information about the workspace bucket can be found in the How (and why) to save RStudio data to workspace storage article.

Cloud cost

The cost of running RStudio on the cloud within the Researcher Workbench depends on the length of time you run the app and the size of the data that you store within your workspace bucket and/or persistent disk. The RStudio app costs $0.40 per hour while running. The persistent disk associated with the RStudio app is $4.00 per month. You can estimate costs by reading the article  What exactly am I paying for? 

You will be charged from the time you first start the RStudio app until it’s been deleted. You can save your work on your persistent disk or workspace bucket and create the app again when you are ready to use RStudio again.

Saving your work

Two common types of analysis files are R Script (.R) and R-Markdown (.Rmd) files. You can use these files to save the code that you run and to display plots. It’s good practice to keep track of your work in RStudio in .R and .Rmd files and save those files to your workspace bucket. Within your workspace bucket, you can share your work with workspace collaborators. 

Some features to note that will come in handy when you are using RStudio in the cloud:

• When you save .R and .Rmd files using the app, they will be saved to both your persistent disk and workspace bucket.
• You can preview .R and .Rmd files that are saved to your workspace bucket in your workspace Analysis tab. This can be helpful for sharing your work without having to start a cloud environment.

Starting RStudio

To start the RStudio app, you create the RStudio cloud environment.

1) Open a workspace or create a new workspace.

2) Select the RStudio Cloud Environment icon on the right hand menu of your workspace. The RStudio Cloud Environment information screen will open.

• You can also get to the RStudio Cloud Environment information screen by clicking on the Applications icon (a cloud with a thunderbolt) and then clicking on the RStudio app button.

3) Select Start at the bottom of the RStudio Cloud Environment information screen to launch the RStudio app.

Opening RStudio

4) After a short time, the RStudio app will be active. To verify that the app is running, you will see a green circle on the RStudio app icon in the right hand menu.

5) Select Open RStudio from the bottom right corner of the RStudio Cloud Environment information screen to open the application.

When you open the RStudio app, you will see the console pane (1), the environment pane (2), and the files and plots pane (3). In the console pane, you can run any R code, similarly to running the R Graphical User Interface (GUI).

You can also access your system shell by using the terminal tab next to the console. In the environment pane, you can see any currently saved objects. In the files tab, you will see any files that are saved to your persistent disk. 

The auto-delete option

When you start the app, you are opted in to the auto-delete function, which will automatically delete your RStudio application if left idle for 1 day. Your persistent disk will not be deleted when your RStudio application is auto-deleted. You can change your idle period or opt-out of auto-delete in the RStudio Cloud Environment panel.

We recommend that you use auto-delete if you are concerned about incurring costs by leaving the app running in the background.

File synchronization between the workspace bucket and the persistent disk

When you use the RStudio GUI for file handling, RStudio is saving and opening files within your persistent disk in the /home/rstudio folder. Any RStudio files (.R and .Rmd files) will be synced to your workspace bucket in the WORKSPACE_BUCKET/notebooks folder.

In reverse, all RStudio files in the workspace bucket notebooks folder will be synced to your persistent disk rstudio folder. Note: The files may take up to 30 seconds to a couple minutes to save to your workspace bucket or persistent disk.

Any files within the WORKSPACE_BUCKET/notebooks folder will be automatically available to be previewed in the Analysis tab. Note: .Rmd files saved as HTML can be previewed but .Rmd files saved as PDFs will not appear. 

You can manually copy other file types between your persistent disk and notebooks folder using the terminal, following the instructions below. 

Using RStudio files within the app

In the following instructions, you will use the RStudio application to create, save, and export RStudio files.

Creating a new file

1) Select File from the top menu → New File and then select the file type you want to create.

The new file will open in the source pane above your R console on the left side of your app.

a. If you create a new .Rmd file you will need to install the markdown package, which will install after you are prompted. You will need to install this package every time you create a new RStudio Cloud Environment. 

i. A popup window will ask you if you want to install the markdown package, Click Yes.

ii. The app will install markdown on the Background Jobs tab.

iii. Using the Markdown information screen, give your file a Title, choose the Output Format, and select Ok to create the new Markdown file.

Saving a file

1) To save a file you are editing, select File from the top menu → Save As

2) Enter the file name for your new file.

3) Select Save. The app will give the file the proper file extension.

4) The file will be saved in your persistent disk. See file synchronization for more details about your RStudio files being synced between your persistent disk and workspace bucket. Note: The files may take up to 30 seconds to save to your workspace bucket and will be saved to the notebooks folder.

You can see your saved files in the file browser in the lower right corner of the RStudio app.

Open a file

1) You can open .R or .Rmd files from the persistent disk by selecting Open → choose the file you want to open from the top menu.

2) Or, you can click on a file you want to open in the Files browser in the lower right corner of RStudio. 

There is currently not a simple solution to upload RStudio files into the workspace. However, you can upload RStudio files using the Jupyter app: Are external coding files able to be imported for analysis? All .R and .Rmd files saved to your workspace bucket will appear in your Analysis Tab.

Render a .Rmd file

You can use the Knit tool to save your R-Markdown file as a PDF, HTML, or Word document. The tool uses TinyTeX to render the files. Install the TinyTeX package on your RStudio console with the following command:

tinytex::install_tinytex()

Select the Knit button drop down menu and then select which type of document you want to create. The files will appear as pop-ups and the Knit tool will save them to your persistent disk.

Uploading files

There is currently not a simple solution to upload an external .R or .Rmd file into the workspace. Using a Jupyter environment, you can upload any .R or .Rmd files following these instructions: Are external coding files able to be imported for analysis? All .R and .Rmd files saved to your workspace bucket will appear in your Analysis Tab.

Accessing workspace storage from the RStudio console and terminal

As previously described, there are two dedicated storage locations when using RStudio on the cloud: the persistent disk and the workspace bucket. You can use the RStudio console and terminal with the following instructions in order to view files in those locations and make sure your work is properly saved.

You can find the persistent disk in the $HOME directory of the RStudio server at /home/rstudio with the following command:

1) [Terminal] List the contents of your persistent disk

ls /home/rstudio

The workspace bucket is available in the terminal and console with the environment variable WORKSPACE_BUCKET.

2) [Console] View the path of your workspace bucket & list contents of your bucket

my_bucket = Sys.getenv('WORKSPACE_BUCKET')
system(paste0("gsutil ls ", my_bucket), intern=T)

3) [Terminal] View the contents of your workspace bucket

bucket="$WORKSPACE_BUCKET"
gsutil ls "$bucket"

RStudio files (.R and .Rmd files) are automatically synced between the /home/rstudio folder of your persistent disk and the notebooks folder of your workspace bucket. You can also copy files between these two locations manually.

4) [Terminal] View the contents of your workspace bucket notebooks folder

bucket="$WORKSPACE_BUCKET"
gsutil ls "$bucket"/notebooks

5) [Terminal] Copy files from your persistent disk to your workspace bucket

bucket="$WORKSPACE_BUCKET"
gsutil cp /home/rstudio/file_name "$bucket"

Stopping the RStudio application

When you are finished using the app, we recommend that you save all of your work in .R or .Rmd files in your workspace bucket and then stop the application by deleting the cloud environment. Pausing the RStudio cloud environment is not available. 

The workspace bucket is the best option for saving work that needs to be shared with collaborators who have access to the workspace. To resume your work, you can open your saved .R and .Rmd files in a new RStudio cloud environment.

To delete your RStudio cloud environment: 

1) Click on the cloud and thunderbolt Applications icon in the right hand menu.

2) In the RStudio active applications menu, click on the trash to delete the cloud environment.

Additionally, you can open the RStudio Cloud Environment panel by clicking on the RStudio icon in the right hand menu. At the bottom left of the panel, select Delete Environment.

3) You have two delete environment options:

a. Keep persistent disk, delete environment. If you keep your persistent disk, you will incur a cost of $4.00 a month. The persistent disk will be saved and opened the next time you start an RStudio cloud environment.

b. Delete persistent disk and environment. Your persistent disk and environment will be deleted. Only data that is within your workspace bucket will be saved.

Making an RShiny app with RStudio

You can make RShiny apps using RStudio. The RShiny project will be saved within a project folder in your persistent disk. Any .R or .Rmd files within the project folder will not be saved to the workspace bucket. To copy the folder from your persistent disk to your workspace bucket, use gsutil cp -r.

1) [Terminal] Copy entire directory tree to workspace bucket

bucket="$WORKSPACE_BUCKET"
gsutil cp -r /home/rstudio/file_name "$bucket"

Note: Only one user can access RShiny Apps within the RStudio Cloud Environment. As a workaround, you can share the RShiny app code with collaborators and they can re-run the code and re-generate the app in their RStudio environment.

An example of making an RShiny app can be found on the Terra platform, which is the platform that the Researcher Workbench is built on. See the Terra workspace RShiny WGS Association Visualization.

Accessing the RStudio tutorial in the Researcher Workbench

The Featured Workspace "How to Get Started with Registered Tier Data (v7)" has an RStudio tutorial to help you get started with using RStudio in the Researcher Workbench. To gain access to the contents of the RStudio tutorial you can duplicate the entire Featured Workspace or just the tutorial file via the steps below: 

1. Login to the Researcher Workbench

2. Start an RStudio application in a Registered Tier workspace. 

3. Once an RStudio application is started in your workspace, navigate to the "Featured Workspaces" section of the Researcher Workbench, and select the "Analysis" tab of the Featured Workspace "How to Get Started with Registered Tier Data (v7)" 

4. Copy the "Data_101_Fundamentals_Rstudio.Rmd" file to your workspace in which the RStudio application is running.

5. Once the tutorial is copied into your workspace, navigate to the "Analysis" tab of your workspace, and select the copied tutorial file. 

6. On the next page select "Edit" to launch the tutorial into the RStudio application. Note: it will not render a preview due to file size. 

7. The tutorial will then load in the active RStudio application for use.

Other helpful material

To open datasets from the Cohort and Dataset Builders with RStudio, read Using the Cohort and Dataset Builders with RStudio. 

For additional information and instructions, check out the following RStudio articles on the Terra platform:

1. Starting and customizing your RStudio app
2. Using and launching RStudio with .Rmd files
3. How (and why) to save RStudio data to workspace storage