Chapter 3 The Basics

Before we go any further, let’s take a moment and ensure that you have the following tools at your disposal. This will help you start on a path to success.

3.1 Getting Started Checklist

  1. Ensure that you have all of necessary accounts and if not, contact Neil (njh5464).
    1. GitHub
    2. EducationShinyAppTeam
    3. BOAST:SU24-Discussions Channel in Microsoft Teams (tied to your PSU AccessID)
  2. Ensure that you have all of the required software
    1. R (version 4.4.0 minimum)
      • You can check your current version by starting R and seeing what version is listed at the start or by typing version into the console
    2. RStudio Desktop (version 2034.04.1 Build 748 or higher; most current version preferred)
    3. GitHub Desktop
  3. R Packages from CRAN–here are some basic packages that everyone will need; be sure to install their dependencies. You may copy the following code into your R console to install the packages.
install.packages(
    pkgs = c("devtools", "shiny", "shinydashboard", "shinyBS", 
              "shinyWidgets", "ggplot2", "tidyverse")
)
  1. The boastUtils Package (see below)
  2. The BOAST App Template (see below)

3.2 boastUtils Package

Bob created the boastUtils package to automate much of the design and development process. This will not only reduce the amount of work you’ll need to do, it’ll also make apps more consistent. Additionally, we routinely add tools to this package that are indispensable for creating and maintaining BOAST apps.

Since Summer 2020, we require all apps to make use of this package.

Please check out the package’s GitHub page for instructions on installing and usage. You may also copy the following code into your R console to install the boastUtils package.

library(devtools)
devtools::install_github("EducationShinyAppTeam/boastUtils")

3.3 A Quick Note on Packages (and R)

All too often, people will install R and R packages and that is the end of it. However, both are living things: they change over time. To this end, we encourage you to get into the habit of checking for updates to R and packages on a regular basis (e.g., monthly). (You can also do the same with RStudio.) This will ensure that you are using the newest version of packages which can help mitigate errors.

For updating R, you can type version in your R console to see what version you have and then compare that to current version posted to CRAN.

To check for updates to R packages that are on CRAN, click on the Update button of RStudio’s packages window. (Typically found in the lower right quadrant.) You can also type update.packages() into your R console to run a check and then update packages. (You can also use old.packages() to see if you have any packages that have newer versions available.)

To update boastUtils you’ll have to run the install command again.

3.4 BOAST Template App

Bob and Neil have created a App_Template repository that you can use as a template for your own apps. To get started, clone the App_Template template repo found on GitHub. This will provide you with a skeleton for organizing your files as well as your code.

There are several methods you can use:

3.4.1 Direct Download

You can download this repository directly by visiting:

https://github.com/EducationShinyAppTeam/App_Template/archive/master.zip

3.4.3 Command Line

Enter the following command in your terminal:

git clone git@github.com:EducationShinyAppTeam/App_Template.git

See also:

3.4.4 RStudio Project

You can also use RStudio to connect to and copy repositories from GitHub. There are a few extra steps that you’ll need to go through compared to other methods. We recommend that you use GitHub Desktop.

  1. In your browser, navigate to the repository you want to copy; in this case the App_Template repo.
  2. Launch RStudio and create a new project.
  3. Select the Version Control option and then Git.
  4. Switch back to your browser and click on the Clone or Download button. Click on the SSH, and then you should see a line of text starting with git@github that you can copy. Do so.
  5. Returning to RStudio, paste the text you just copied into the Repository URL field.
  6. Adjust the directory name and the subdirectory (where this project will live on your machine) as you see fit.
  7. Click the Create Project button.

This method will ensure that you will be able to successfully push and pull changes to GitHub. For additional help, Neil has created a video “Using RStudio to Connect to GitHub” which walks you through the process.

3.5 Useful RStudio Settings

There are a few settings in RStudio that can help make life much easier. While they aren’t required, we do encourage you to at least try them out.

3.5.1 Coding Margin

Generally speaking, you do not want your code to be on an overly long line. A cutoff of 80 characters works in the vast majority of cases. When your line gets beyond 80 characters, the entire line becomes much more difficult for people to read, including yourself. RStudio has the ability to add a thin grey line at the right hand side of your coding window to mark when 80 characters occurs.

To enable this feature:

  1. Enter the Global Options of RStudio (see the Tools menu),
  2. Click on Code in the left-hand menu,
  3. Select the Display tab across the top,
  4. Click the box next to “Show margin” and make sure that the Margin column field is set to 80,
  5. Click Apply and OK

3.5.2 Line Numbers

In the event that you RStudio does not automatically display line numbers for your code, you’ll want to enable their display. This is vital for looking at error messages or discussing code with others.

  1. Enter the Global Options of RStudio (see the Tools menu),
  2. Click on Code in the left-hand menu,
  3. Select the Display tab across the top,
  4. Click the box next to “Show line numbers”,
  5. Click Apply and OK

3.5.3 Whitespace Characters

This option takes a bit of getting used to. In essence, RStudio will display a “whitespace” character (e.g., a grey dot) in each bit of empty space as well as end of line characters (a grey dash with a downwards hook at the right-hand end). This option can help you make sure that you are improving the readability of your code by using appropriate spacing.

  1. Enter the Global Options of RStudio (see the Tools menu),
  2. Click on Code in the left-hand menu,
  3. Select the Display tab across the top,
  4. Click the box next to “Show whitespace characters”,
  5. Click Apply and OK

3.5.4 Rainbow Parentheses

One of the most common programming bugs is that of mismatched parentheses (), braces {}, or brackets []. RStudio can help out with this through the use of Rainbow Parentheses, which makes color matched sets of parentheses as well as automatically putting in both open and close versions.

  1. Enter the Global Options of RStudio (see the Tools menu),
  2. Click on Code in the left-hand menu,
  3. From the Editing tab, make sure that “Insert matching parens/quotes” is checked,
  4. Select the Display tab across the top,
  5. Click the box next to “Rainbow parentheses”,
  6. Click Apply and OK

3.5.5 Code Diagnostics

Two useful Coding Diagnostics deal with the assignment operator, <- and the putting the appropriate whitespace into your code. RStudio has tools to help you ensure that you adhere to the proper usages here.

  1. Enter the Global Options of RStudio (see the Tools menu),
  2. Click on Code in the left-hand menu,
  3. Select the Diagnostics tab across the top,
  4. Make sure there is a check mark in the boxes next to each of the following
    • Show diagnostics for R
    • Enable diagnostics within R function calls
    • Check arguments to R function calls
    • Check usage of ‘<-’ in function calls
    • Provide R style diagnostics (e.g. whitespace)
  5. Click Apply and OK

You may select other diagnostics in addition to those we’ve listed here.