- Packages
- Validation
- Publications
- Support
- Questions and Bug reports
- R setup
- Installing HADES
- Connecting to a Database
- Supported Database Platforms
- Study packages
- Using Renv for Dependencies
- Developers
- How to contribute
- Developer Community
- Developer Guidelines
- Code Style
- Release Process
- Package Statuses
- Test server usage
- Development Roadmap
- HADES Package Requirements
Here are the steps for installing the required environment to run theOHDSI R packages. Four things needs to be installed:
- R is a statistical computing environment. It comeswith a basic user interface that is primarily a command-line interface.For stability, we’ve picked one R version that we aim to support for awhile moving forward. Since 2023-04-01 our target is R4.2.3. We highly recommend installing R 4.2.3 for maximumcompatibility.
- RTools is a set of programs that is required onWindows to build R packages from source.
- RStudio is an IDE (Integrated DevelopmentEnvironment) that makes R easier to use. It includes a code editor,debugging and visualization tools. Please use it to obtain a nice Rexperience.
- Java is a computing environment that is needed torun some of the components in the OHDSI R packages, for example thoseneeded to connect to a database.
In order to install HADES, you must also set a GitHub Personal AccessToken as described in thissection
These instructions are also demonstrated in this video, showing astep-by-step guide to installing the required software.
In Windows, older R versions (< 4.2.0) come with both R a 32-bit anda 64-bits architecture. If you install R in both architectures, youmust also install both 32-bit and 64- bits Javaversions. It is recommended to only install the 64-bit version of R.
Installing R
Go to https://cran.r-project.org/bin/windows/base/old/4.2.3/,click on ‘R-4.2.3-win.exe’ to download.
After the download has completed, run the installer. Use thedefault options everywhere, with two exceptions: First, it is better notto install into program files. Instead, just make R a subfolder of yourC drive as shown below. Second, to avoid problems due to differingarchitectures between R and Java, if you’re installing an older Rversion (< 4.2.0), disable the 32-bit architecture as also shownbelow.
Once completed, you should be able to select R from your StartMenu.
Installing RTools
Go to https://cran.r-project.org/bin/windows/Rtools/rtools42/rtools.html,and download the RTools installer.
After downloading has completed run the installer. Select thedefault options everywhere.
Installing RStudio
Go to https://posit.co/download/rstudio-desktop/, select‘Download RStudio Desktop For Windows’.
After downloading, start the installer, and use the defaultoptions everywhere.
Installing Java
Go to https://docs.aws.amazon.com/corretto/latest/corretto-8-ug/downloads-list.html,and select the Windows 64-bit JDK installer as highlighted below.
After downloading just run the installer.
The default maximum Java heap space is very small (only 512MB),so to avoid Java out-of-heap-memory errors, we must increase the maximumheap size. To set this for all R programs, add this line to the
.Renvironfile:_JAVA_OPTIONS='-Xmx4g'The easiest way to edit your
.Renvironfile is by usingtheusethispackage:install.packages("usethis")library(usethis)edit_r_environ()This will open
.Renvironin a text editor. Add the line,save the file, and restart R. Java will now have a maximum of 4GB ofheap space available.
Installing R
Go to https://cran.r-project.org/bin/macosx/base/, click on‘R-4.2.3.pkg’ to download.
After the download has completed, run the installer and acceptall of the default options. You should see a screen indicating that theinstallation was successful.
Installing R build tools
We will need to install C and Fortran compilers in order to build Rpackages from source code. These are included with Xcode which can bedownloaded from the Mac App store.
Open the App Store in Mac OS and install Xcode. Xcode is a largeprogram. If disk space is scarce you could also try only installingXcode command line tools by following the instructions here.Verify that the C compiler gcc is installed by opening the terminal andrunning the command
clang. You should see an error thatsays “no input files”.Download and install the gfortran compiler
gfortran-12.2-universal.pkgfrom https://cran.r-project.org/bin/macosx/tools/. Verify theinstallation by opening the terminal and running the command/opt/gfortran/bin/gfortran. You should see an error thatsays “no input files”. R 4.2.3 will look in the wrong place forgfortran, so you must point it to the right location. Runusethis::edit_r_makevars()to open~.R/Makevarsand add:F77 = /opt/gfortran/bin/gfortranFC = /opt/gfortran/bin/gfortranFLIBS=-L /opt/gfortran/libGo to https://www.xquartz.org/, download the .dmg and run theinstaller.
Verify that build tools are installed and available by opening anR console and running
install.packages("pkgbuild")pkgbuild::check_build_tools()
Installing RStudio
- Go to https://posit.co/download/rstudio-desktop/, select‘Download RStudio Desktop For Mac’.
Installing Java
Go to https://www.oracle.com/java/technologies/javase-jdk15-downloads.html,and select the Mac OS installer for the Oracle JDK as highlighted below.
After downloading just run the installer. Check that java isinstalled by opening the terminal and running the command
java. If you see some helpful output about usage then theinstallation was successful.
You should now be ready to go, but we should make sure. StartR-studio, and type
install.packages("SqlRender")library(SqlRender)translate("SELECT TOP 10 * FROM person;", "postgresql")## [1] "SELECT * FROM person LIMIT 10;"## attr(,"sqlDialect")## [1] "postgresql"This function uses Java, so if all goes well we know both R and Javahave been installed correctly!
Another test is to see if source packages can be built. Run thefollowing R code to install the CohortMethod package fromthe OHDSI GitHub repository:
install.packages("remotes")remotes::install_github("OHDSI/CohortMethod")Installing HADES packages requires downloads from GitHub.Unfortunately, GitHub has a cap on how many downloads an anonymous usercan make in a short amount of time, and this cap is reached when tryingto download all HADES packages. To avoid this cap, we need toauthenticate ourselves using our GitHub account. A known GitHub user hasa much higher download cap, and can install HADES without issues. We canauthenticate ourselves by first creating a Personal AccessToken (PAT), and then providing this to R.
Fortunately, you will need to do this only once. After you’ve setyour PAT in R, you can rely on it to be there in all your future Rsessions.
Creating a Personal Access Token
Before we can create a PAT, you must make sure that you have a validGitHub account. You can create one for free at GitHub.com.
The easiest way to create a GitHub PAT is by using the usethis package. Running this codewill open a browser that allows you to generate a PAT:
install.packages("usethis")library(usethis)create_github_token(scopes = c("(no scope)"), description = "R:GITHUB_PAT", host = "https://github.com")You may need to log on to GitHub. Note that the PAT does not requireany of the permissions listed, so you can leave all checkboxesunchecked. Scroll down and click on ‘Generate token’ to generate yourPAT. Your PAT is a sequence of 40 letters and numbers. Make sure to copyyour PAT, because you will not be able to see it again once you closeyour browser!
Adding your Personal Access Token to R
Next, we need to make the PAT available to R. For this we need to adda line to the .Renviron file that looks like this:
GITHUB_PAT = 'a1b2c3d4e5f6g7h8g9h0ijklmnopqrstuvwxyz'where ‘a1b2c3d4e5f6g7h8g9h0ijklmnopqrstuvwxyz’ is your PAT.
The easiest way to edit your .Renviron file is by usingthe usethis package again:
edit_r_environ()This will open .Renviron in a text editor. Add the linewith your PAT, save the file, and restart R. The PAT will now beavailable to the various R functions.
