Installation and updating

This section will guide you through the steps you need to take to install sdcApp. sdcApp is a graphical user interface (GUI) for the sdcMicro package. The sdcMicro package is an add-on package for the statistical software R. In order to start working with sdcApp, you need to install R, RStudio [1] as well as several add-on packages for R. All software is available free of charge and open-source. R and RStudio run on most operating systems (OS), including Windows, Mac OS X and Linux. To use sdcApp, a webbrowser needs to be installed as well [2].

R, RStudio, the sdcMicro package as well as dependencies (other R packages that need to be installed for the sdcMicro package to work properly) are regularly updated. Therefore, it is recommended to regularly update to the latest version of the software. The Section Updating R, RStudio and the sdcMicro package shows how to check for updates and install updates.

Installing R and RStudio

The first step in the installation of sdcApp is the installation of R and RStudio. The free open source statistical software R can be downloaded from the CRAN website. By selecting your OS (cf. Fig. 1), the installer will be dowloaded to your computer. In order to install R, open the installer and follow the installation steps.

_images/installDownloadR.png

Fig. 1 Select OS to start downloading R

Once R is successfully installed, you can install RStudio. RStudio is an IDE (integrated development environment) for R. RStudio makes working with R much easier. RStudio Desktop and RStudio Server can be downloaded free of charge from the RStudio website. On this webpage, you can click on the blue button under ‘2: Install RStudio’ as shown in Fig. 2 or scroll down to the overview of different versions and select the version corresponding to your OS to start downloading the installer. In order to install RStudio, open the installer and follow the installation steps.

_images/installRStudioVersion_new.png

Fig. 2 Click on the blue button under 2: Install RStudio

Note

We recommend updating to the latest versions of R and RStudio if this software is already installed on your computer before moving on. See also the Sections Updating R and Updating RStudio for more information on updating the software.

Once R and RStudio are installed on your computer, open RStudio. The RStudio interface consists by default of four different panes as shown in Fig. 3.

  1. Script editor (by default left up)
  2. Workspace and history (by default right up)
  3. R console (by default left down)
  4. Plots, files and help (by default right down)
_images/installRStudio_new.png

Fig. 3 Screenshot RStudio

Installing sdcMicro package

sdcApp is included in the R package sdcMicro. Once RStudio is opened, sdcMicro can be installed by executing commands in the R console. sdcMicro and a set of other R packages that are required by the sdcMicro package are downloaded from the CRAN servers. Therefore, it is necessary to be connected to the internet during the installation process. [3]

In order to install the latest version of the sdcMicro package, type the command install.packages("sdcMicro", dependencies = TRUE) in the console and press enter to execute (cf. Fig. 4). The first time you are installing R packages, you will be prompted to select a CRAN mirror (server) to install the package from. Since the packages on all mirrors are identical, you can choose any of the locations. The sdcMicro package itself uses functionality from a set of other R packages (e.g., haven for reading files in different formats). By specifying the dependencies argument to TRUE, these dependencies will automatically be installed too.

Listing 1 Installing sdcMicro package
1
2
# install sdcMicro package
install.packages("sdcMicro", dependencies = TRUE)
_images/installInstallsdcMicro_new.png

Fig. 4 Installing sdcMicro package from R console

Note

Also dependencies will be installed and the installation may take some time. Dependencies are other add-on packages, of which the functionality is required to run the sdcMicro package.

Launching sdcApp

Once the sdcMicro package is successfully installed, the sdcMicro package needs to be loaded. Installing the package is only required once (except for updating), whereas loading the package is required every time a new R session is started.

You can load the sdcMicro package by typing library(sdcMicro) and launch the application by typing sdcApp() (cf. Fig. 5).

Listing 2 Loading sdcMicro package and launching sdcApp
1
2
3
4
5
# Load sdcMicro package
library(sdcMicro)

# Launch sdcApp (opens in browser window)
sdcApp()

sdcApp opens in your system’s default web browser through the local host IP 127.0.0.1: (cf. Fig. 6). sdcApp works with recent versions of any webbrowser. Due to small issues encountered with some browsers, we recommend to use Google Chrome, Mozilla Firefox or Safari for the best performance. In case your default web browser is not one of the aforementioned browsers, you can simply open an alternative browser and copy paste the local host IP address from the R console into the new browser. sdcApp will open in the new browser.

Note

An internet connection is not required while using sdcMicro and sdcApp and the data are stored locally on your computer or server. The web browser uses a local host IP, which is not connected to the internet and the browser is only used to communicate with the running R session.

Note

After launching sdcApp the R session is busy and cannot be used for other calculations.

Furthermore, it’s important that your R session is enabled to use the installed webbrowser.

_images/installRconsoleIP_new.png

Fig. 5 R console with local IP after launching sdcApp

_images/installsdcAppStartIP_new.png

Fig. 6 Start screen sdcApp in browser with local IP

In rare cases, not all dependencies are correctly installed and the following error message appears in the R console upon loading the sdcMicro package (cf. Fig. 7). In that case, install the package(s) indicated in the error message manually by using the command install.packages() with the name of the package(s). In the example error message, this would be for the haven package.

_images/installErrorDependencies.png

Fig. 7 Error message in console in case of missing dependencies

Updating R, RStudio and the sdcMicro package

R, RStudio, the sdcMicro package as well as dependencies are regularly updated. Updates include bug fixes as well as additional functionality. Therefore, it is recommended to regularly update to the latest version of the software.

Updating R

RStudio uses by default the most recent version of R available on your system. New versions of R packages, including the sdcMicro package, rely on the newest version of R. Therefore, it’s important to regularly check for updates of R. The easiest way to do so is to visit regularly the CRAN website. If a new version of R is available, the same steps as for the installation of R need to be followed as described in the Section Installing R and RStudio. The version number of the R version installed on your computer appears in the R console upon launching R or RStudio (cf. Fig. 8).

_images/installRVersion_new.png

Fig. 8 R console with version number

Updating RStudio

To check for updates in RStudio, go to Help -> Check for updates. If an update is available, the current version number and the newest version number are shown. In order to install the newer version, you need to visit the RStudio website and follow the steps as described in the Section Installing R and RStudio.

Updating R packages

The sdcMicro package is regularly updated to fix bugs and add functionality. In order to check for newer versions, click on the Update button to get an overview of all packages that have newer versions available (cf. Fig. 9). By clicking Select all, these packages are all automatically updated.

_images/installCheckUpdate.png

Fig. 9 Updating R packages in RStudio

Alternatively, one can type the command update.packages() in the R console to update all installed packages.

Listing 3 Updating packages
1
2
# Update packages
update.packages()

Bug reporting on GitHub

The sdcMicro package is open source software and the source code can be easily viewed on the GitHub of the sdcMicro project. There you can also report alleged bugs and raise other issues.

[1]Technically speaking, RStudio is not required to run sdcApp. Nevertheless, we recommend to install RStudio for a better user experience.
[2]sdcApp is a Shiny web application, which works best in a recent version of a webbrowser. Therefore, it is recommended to ensure that your webbrowser is updated regularly. Some webbrowsers may impede the proper functioning of sdcApp. If sdcApp doesn’t work properly in your default web browser, please try to install Firefox or Google Chrome.
[3]It is possible to download R, RStudio and the packages and transfer the files to the computer with for example a USB drive in case the computer sdcMicro should be installed on cannot be connected to the internet for technical or confidentiality reasons.