How to use RStudio

Owned by Lynne Hardie (Unlicensed), created
Last updated: Oct 13, 2021 by Dominic Hul
6 min read

The following document, copied below, is a quick guide to using RStudio as the tool to querying the APPROACH Online Reporting platform

 

To work in RStudio on the Approach Online reporting environment the requirements are:

  1. An APPROACH Online Reporting account

  2. An APPROACH RStudio account

  3. AHS network access

One needs to access the AHS network first using the private secure network access. Connect to the AHS network using your credentials. If you do not have any, contact the IT support of AHS to request access)

 

 

Step 1. Connect to AHS

When you want to access the RStudio , first connect to AHS VPN or make sure to already be within the AHS network environment.

NOTE: You cannot use AHS’s MyApps via Citrix at present because AHS currently forces you to use Internet Explorer and it is not compatible with that.https://researchcalgary.atlassian.net/browse/ASD-9684

 

FYI: For a VPN client: Download and install, for example FortiClient VPN client. For setup and usage:

http://vpnextranet.albertahealthservices.ca/vpnfiles/Fortigate_VPN5_Client_Architecture_and_Installation_Document.htm

 

Step 2. Connect to RStudio

Point your browser to RStudio by navigating to https://rstudio.approach.org. Login using your RStudio account credentials.

If you don’t yet have an RStudio account, check in with the Approach Service Desk to check if your account was assigned and set up to have one. One can be requested through the Approach access approval form and registration process.

 

 

Tip: Changing your password

You will most likely want to change the auto-generated password provided to you. To do so, follow these steps.

  1. Sign into RStudio with your credentials

  2. Click on the ‘Terminal’ tab

  3. Type passwd and press Enter

    1. Fill out your current password, your new password and confirm your new password

    2. Your password has been changed. Next time you log into RStudio, use your new password.

       

Step 3. RStudio landing page layout and summary

 

I.        Script/Source Editor:
R scripts can be written and tested here. Either create a new script from File -> New File, or you may open and edit an existing script/project saved to your workspace. RStudio provides a set of core features as part of the source editor tool which is explained in detail here - https://support.rstudio.com/hc/en-us/articles/200484448-Editing-and-Executing-Code

II.     Workspace Variables & Console History:

The Environment tab lists the variables and functions present in the current R session (an R session may be restarted by navigating to Session -> Restart R.

The History tab will display all previously entered code/commands into the console (includes both code ran from a script from source editor, as well as manually entered code written directly into the console)

III.  Console:
The console is where all code will be executed. If you run a script, the script will be entered and executed through the console. You may also manually enter and run any valid R code into the console for quick debugging/evaluation purposes.

IV.    Files, Plots & Packages

The Files tab displays a ‘File Explorer’ type view for you to navigate through your workspace. Any files and projects you save will be located within your workspace and found here. Clicking on any file in this tab will automatically populate the source editor with the file’s contents.

The Plots tab holds all the plots generated in your R session. Plots can be exported as PDF or JPEG. The use of plots is a very high value tool used for data visualization. For an introduction into data visualization in R, visit https://towardsdatascience.com/a-guide-to-data-visualisation-in-r-for-beginners-ef6d41a34174

The Packages tab lists all existing R packages installed and available for use (both system and user level packages). You may view documentation for any package by clicking on the package name within this list. The Packages tab also provides the ability to search for and install new packages; as well as searching and applying updates to existing packages.

 Step 4. Installing and importing the necessary libraries used to query the Approach database

 

Note: The Approach library and dependencies should already be preinstalled once you have access to your account.

To confirm the APPROACH package has been installed, do the following:

  1. Sign into RStudio

  2. On the right-hand side of the screen, click on the 'Packages' tab

    1. Confirm that the ‘approach’ library is underneath the ‘User Library’ list

       

 

a.      (Ignore this step if you already have the package installed)
Install the Query Utility R Package for APPROACH. This package is not public, and only available on the RStudio server. To install, run the following command in the console

install.packages("/home/cru/approach_0.1.1.tar.gz", source = TRUE, repos = NULL)

If successful, the console should return the following

Installing package into ‘/home/<your-username>/R/x86_64-pc-linux-gnu-library/3.6’ (as ‘lib’ is unspecified) * installing *source* package ‘approach’ ... ** using staged installation ** R ** byte-compile and prepare package for lazy loading ** help ** installing help indices ** building package indices ** testing if installed package can be loaded from temporary location ** testing if installed package can be loaded from final location ** testing if installed package keeps a record of temporary installation path * DONE (approach)

 

b.      Import the installed APPROACH library, running the following command in console

library(approach)

 

c.       Create an ApproachAPI instance/object as follows

api = ApproachAPI()

This api variable will be used to authenticate yourself, and send PostgreSQL queries to the database

*You may use any variable name in place of api

 

Step 5. Using the ApproachAPI class

 a.       Logging In
Before submitting a query, the API must authenticate all subsequent requests. Authenticate yourself first using the ApproachAPI $login() function as below

api$login()

You will be prompted for your APPROACH reporting platform credentials.

 

You will also be prompted for a 2-factor token sent to your device

 

A popup will display, confirming you are authenticated and can query the database

 

b.      Submitting Queries

Warning - Some tables have 100,000+ records stored. Try to refrain from selecting all from large data sets.

  • Ex. Running SELECT * FROM approach.patient; would return 200,000+ records. This would be too much data for the database, RSTudio, as well as your computer to be processing and rendering frequently.

  • If you are unsure if a query will return too many rows to process, you can limit the number of rows returned using the LIMIT clause at the end of any query.

    • i.e., SELECT * FROM approach.patient LIMIT 1000


Build your PostgreSQL query and submit it using the ApproachAPI $query(string) function

  • The model explorer tool available in the reporting platform can be used to determine tables, field names and relationships used to build your queries.

See here: https://front.approach.org/model-explorer  (must be logged in)

e.g.,
api$query("SELECT count(*) as c, bmi FROM approach.patient WHERE bmi IS NOT NULL and bmi > 0 GROUP BY bmi ORDER BY c DESC;")

 

The query function will render the query’s results into a table

 

The resulting data frame is stored in the api$dataFrame variable. You may use this object for further data analysis, as well as using it for the generation of plots and graphs.

c.       Logging Out
To close off your session with the API, run the $logout function as below

api$logout()

A confirmation message will be displayed once logged out

 

  • By default, a session will timeout and close off after 45 minutes of inactivity. However, explicitly logging out is suggested for security purposes.