Setting Up Your Computer

Who this is for: new lab members on their first day. Before you start: nothing. Do this before Getting Started with EpiModelHIV.

We write and test all of our code on our own computers and use the HPC only to run it at scale, so a working local setup comes first. This page covers the software, accounts, and settings you need.

Install the core tools

• R from CRAN. See Which R version below.
• RStudio from Posit.
• git from git-scm.com. Macs offer to install it the first time you type git in a terminal.
• GitHub Desktop from desktop.github.com, if you prefer a graphical git client. Our tutorials show both.

Tools for compiling R packages

Several of our packages, and many of the packages renv installs, are built from source, so you need a compiler:

• Windows: Rtools matching your R version (Rtools45 covers R 4.5 and 4.6). See Tips for Windows Users.
• Mac: the Xcode command line tools (run xcode-select --install in a terminal) and the GNU Fortran compiler, both described on CRAN's macOS tools page.

Which R version

R versions are numbered major.minor.patch: in 4.6.1, 4 is the major version, 6 the minor version, and 1 the patch. Each project records the R version it was built with at the top of its renv.lock file. Use the same major and minor version as that file on your computer and on the HPC; the patch number can differ. Packages installed under one minor version (4.5) must be reinstalled for another (4.6), so when you upgrade R, expect each project's packages to reinstall.

For a new project, use the R version in the EpiModelHIV-Template's renv.lock. The HPC has the current R versions available (see Using R via Spack on the HPC).

RStudio settings

Go to Tools > Global Options:

• General > Basic > Workspace: untick "Restore .RData into workspace at startup", and set "Save workspace to .RData on exit" to Never. (Or run usethis::use_blank_slate() once, which sets both.) Restarting R (Session > Restart R, Cmd+Shift+0 on a Mac, Ctrl+Shift+F10 on Windows) then gives you a clean session instead of reloading old objects, which avoids errors that are hard to track down, especially when code later runs on the HPC.
• Code > Saving: set "Line ending conversion" to Posix (LF). Scripts with Windows line endings fail on the HPC.
• If your system is not in English: Advanced > Experimental Features > "User Interface Language": English, so menus match this wiki.

Where to keep your repositories

Clone repositories into a folder that is not synced by Dropbox, OneDrive, or iCloud, for example ~/git/. Sync tools and git interfere with each other, and renv libraries are large.

GitHub account and personal access token

1. Create a GitHub account if you do not have one, and ask Sam to add you to the EpiModel organization. Our private repositories, including EpiModelHIV-p, are visible only to members.

2. Request access to the ARTnet data, which our HIV models are built from (see Home).

3. Create a personal access token (PAT), which R uses to install packages from our private repositories. In R:

   usethis::create_github_token()

   This opens GitHub's page for a classic token with the right scopes ticked (repo is the one that matters). Give it a name and an expiration date you will remember; when a token expires, installs from GitHub start failing with error 401. Copy the token; GitHub shows it only once.

4. Store the token in your user .Renviron file:

   usethis::edit_r_environ()

   Add one line, save the file, and restart R:

   GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxx
   

Each project also gets its own .Renviron with the token in it, because a project .Renviron hides the user one; Getting Started with EpiModelHIV shows how. For the HPC, see Using Git on the HPC. Never commit a token to git or paste it into Slack.

Optional reading

• Happy Git and GitHub for the useR, a practical guide to using git with R and RStudio.

Next: learn EpiModel (Home), then Getting Started with EpiModelHIV.