1  Setup

Your project work starts here. Setup involves:

Setup activities typically take 30 minutes to an hour.

Important“My project won’t knit”

Don’t rush this process. Almost every “my project won’t knit” message we get traces back to a setup problem. Make sure you pass the setup check before you move on.

1.1 Install R and RStudio

If you haven’t already, install R and then install RStudio. That order matters: RStudio looks for R when it opens, so in the other order it will not work. Below are step-by-step guides for Windows and macOS.

TipA fuller walkthrough, with pictures of every prompt

If you have never installed software like this before, work from the Installing R and RStudio guide instead. It covers the same ground more slowly, with a tab for each platform and an explanation of every warning box you will see along the way. Come back here when R and RStudio are both open.

ImportantCheck your operating system first
  • Windows: the current RStudio requires Windows 11. Click Start, type about, press Enter, and read the Edition line. If it says Windows 10, stop and email Dr. Cormier before installing anything.
  • macOS: the current R and RStudio require macOS 14 (Sonoma) or newer. Click the Apple menu, then About This Mac, and read the line above the chip. Sonoma, Sequoia, or Tahoe are fine. Ventura, Monterey, or Big Sur are not, so email Dr. Cormier.

1.1.1 Windows

Step 1: Install R

  1. Go to the CRAN R Project website.
  2. Click on “Download R for Windows”.
  3. Click on “base” and then select the link labeled “Download R x.x.x for Windows” (where x.x.x is the latest version).
  4. Open the downloaded .exe file and follow the installation prompts, accepting the defaults.

Step 2: Install RStudio

  1. Visit the RStudio download page.
  2. Click the link to download the Windows installer.
  3. Open the downloaded .exe file and complete the installation using default settings.
WarningTwo boxes Windows will show you

“Windows protected your PC”, a blue box with only a Don’t run button. This does not mean the file is unsafe. It appears for almost every newly released installer. Click the small More info link, then Run anyway.

“Do you want to allow this app to make changes to your device?” Click Yes. If it asks for an administrator password you do not have, your laptop is managed by an IT department. Stop and email Dr. Cormier.

Step 3: Verify the installation

  1. Launch RStudio from the Start menu.
  2. In the Console pane, type R.version$platform and press Enter.
  3. You should see "x86_64-w64-mingw32". If you get an error, or RStudio says it cannot find R, R did not install correctly. Redo Step 1.
Note

Open RStudio from the Start menu, never by double-clicking the installer in your Downloads folder. That file installs the program, it is not the program. Once you create your .Rproj file later in this chapter, you will open the project instead, and that becomes your normal way in.

1.1.2 macOS

First, identify your Mac’s chip. Newer Macs use Apple Silicon (M1, M2, M3, M4, etc.); older ones use Intel processors. You need to know which you have to pick the right R installer.

  1. Click the Apple menu (top-left corner) → About This Mac.
  2. Look at the Chip (Apple Silicon) or Processor (Intel) line:
    • If it says “Apple M1”, “M2”, “M3”, “M4”, or any Apple-labeled chip, you have Apple Silicon. You want the arm64 installer.
    • If it says “Intel Core …”, you have an Intel Mac. You want the x86_64 installer.

Step 1: Install R

  1. Visit the CRAN R Project website.
  2. Click on “Download R for macOS”.
  3. Select the latest version matching your chip — either R-x.x.x-arm64.pkg (Apple Silicon) or R-x.x.x-x86_64.pkg (Intel).
  4. Open the downloaded .pkg file and follow the installation prompts.
WarningIf macOS asks for access to your Downloads folder, say yes

Partway through, macOS may ask whether the Installer can read files in your Downloads folder. Allow it. If you click Don’t Allow, this install fails and you will not be able to install anything else from Downloads afterward.

Note also that you do not drag R anywhere. R uses a .pkg installer, which puts R into Applications for you. The dragging step is for RStudio only.

Step 2: Install RStudio

  1. Go to the RStudio download page. One download works on both Apple Silicon and Intel. The chip only mattered for R.
  2. Click the link to download the macOS version of RStudio.
  3. Open the downloaded .dmg file and drag the RStudio icon onto the Applications folder. Wait for the copy bar to finish.
ImportantThen eject the disk image. This is the step people skip.

The window you dragged from is not a folder on your computer. It is a temporary disk image, like a CD your Mac pretended to insert. If you open RStudio from that window, you are running it off the pretend CD. It works until you restart, and then RStudio vanishes along with your settings.

Close the window. In any Finder sidebar, under Locations, find RStudio with a small eject symbol beside it and click the eject symbol. Dragging installs it; ejecting proves you did.

Step 3: Verify the installation

  1. Open RStudio from your Applications folder. The first time, macOS warns that it was downloaded from the internet. Click Open.
  2. In the Console pane, type R.version$platform and press Return.
  3. You should see "aarch64-apple-darwin20" on Apple Silicon or "x86_64-apple-darwin20" on Intel. If it does not match the chip you identified above, you installed the wrong R. Redo Step 1 with the other installer and install it over the top.

1.2 Install the required R packages

Now, install the seven packages required by the project.

  1. Select the Packages tab in the bottom-right pane.

  2. Click Install at the top of that pane.

  3. In the “Install Packages” box, enter the package names separated by spaces or commas:

    here tidyverse modelsummary ggpmisc car ggrepel kableExtra

  4. Make sure Install dependencies is checked.

  5. Click Install.

Tip

You install packages only once per machine. Once installed, you “attach” them to a script (.R) or an R Markdown (.Rmd) using the library() function. The requisite library() calls are already included in the setup chunk of the project.Rmd template. Do not edit the setup chunk.

1.3 Create the required directory or folder structure

1.3.1 Make a BA 3316 folder first

Before building the project directory structure, you need to set up a top-level BA 3316 folder first. If you are new at this sort of thing, put it on your desktop. Otherwise, put it somewhere inside the Documents folder that makes sense to you.

Inside BA 3316, create two subfolders:

BA 3316/
├── Homework/
└── Project/
NoteThe trailing slash means “this is a folder”

Throughout this guide, a name ending in / is a folder, not a file. The slash is notation, not part of the name. When you create the folder above you type Homework, not Homework/.

The same holds for data/, out/, r/, and the rest. A name with an extension, like project.Rmd or LF.R, is a file.

  • Homework/ is where you’ll save completed homework assignments.
  • Project/ is the self-contained working directory for all project-related files.

The next step is creating the required structure inside of Project/. We won’t have anything more to say about the Homework/ directory in this guide.

1.3.2 Create the required subfolders inside Project/

The required directory structure has two levels – a main project folder, which you just created, and these five subfolders:

  • data/ contains input data sets
  • data_documentation/ contains the data documentation file
  • out/ contains outputs generated by the script
  • r/ contains the R script that produces outputs
  • css/ contains the CSS (cascading style sheet) file that styles the slide deck

After creating the five subfolders, your project directory should look like this:

BA 3316/
├── Homework/
└── Project/
    ├── data/
    ├── data_documentation/
    ├── out/
    ├── r/
    └── css/

You’ll put files into these subfolders in the next step. The .Rmd files themselves will live in the Project/ root, not in any of the subfolders.

1.4 Download the Pre-project file pack and sort its contents

Your project work starts with the Pre-project Exercise, so you’ll download the Pre-project file pack from Canvas first. You will find it in the module labelled Project. It is a .zip file containing the seven files required to complete the Pre-project Exercise:

  • pre_project.Rmd — R Markdown template for the Pre-project Exercise
  • LF.R — R script that produces LF.csv
  • project_slidedeck.css — the CSS file that styles the slide deck
  • pppub25.csv — March 2025 CPS person-level data file
  • hhpub25.csv — March 2025 CPS household-level data file
  • cpsmar25_documentation.pdf — March 2025 CPS documentation file
  • check_setup_preproject.R — R script that checks your setup for the Pre-project Exercise

Download and move the .zip file into your Project/ folder and unzip it. Sort the files from the unzipped folder into the right subfolders in your Project/ directory.

The Main Project requires a few additional files that are bundled in another file pack. We will cover those in the Main Project section of this guide.

Here is where each file goes:

File Goes in
pre_project.Rmd Project/ (root)
LF.R Project/r/
project_slidedeck.css Project/css/
pppub25.csv Project/data/
hhpub25.csv Project/data/
cpsmar25_documentation.pdf Project/data_documentation/
check_setup_preproject.R Project/r/

After sorting each file into its proper location, your Project folder should look like this:

Project/
├── pre_project.Rmd
├── data/
│   ├── pppub25.csv
│   └── hhpub25.csv
├── data_documentation/
│   └── cpsmar25_documentation.pdf
├── out/
│   (empty for now — LF.R will write LF.csv here)
├── r/
│   ├── LF.R
│   └── check_setup_preproject.R
└── css/
    └── project_slidedeck.css

1.5 Create an R Project in the Project directory

Creating an R Project turns your Project/ folder into a single, self-contained workspace: every time you open it by double-clicking the .Rproj file, RStudio automatically makes that folder your working directory. That is what lets the here() paths in the scripts and the R Markdown template find your data and output files reliably – without it, RStudio has no fixed sense of where your project lives, which is the source of the cryptic “file not found” errors that come from running things out of your Downloads folder.

To create your R Project, follow these steps:

  1. Open RStudio.
  2. Go to File → New Project.
  3. Choose Existing Directory.
  4. Browse to your Project/ folder and click Create Project.
  5. RStudio re-opens in your Project folder loaded as the active project.

Creating the R Project writes the file Project.Rproj in the Project/ root. After creating the R Project, always, always, always open RStudio by double-clicking the Project.Rproj file.

1.6 Run the setup check

After completing the above steps, run the setup-check script to confirm everything is in place. It checks for the presence of all required files and confirms that they are in the right places. If you have any setup problems, it will tell you what they are and how to fix them.

To run the setup check script:

  1. Go to the Files tab in the bottom-right pane of RStudio.
  2. Click the r/ subfolder.
  3. Click the file check_setup_preproject.R to open it in the editor.
  4. In the editor, select all lines using Ctrl+A on Windows or Cmd+A on a Mac.
  5. Click the Run button in the top-right of the editor pane.

The script’s output appears under the Console tab in the pane below the editor, indicating whether each required file is in place — one line per file, marked either ✓ (good) or ✗ with a specific instruction telling you what to fix. Do not proceed until every line is a ✓.

1.7 Common errors

In our experience, these are three common setup errors, each of which is easily preventable.

  1. project_slidedeck.css in the wrong folder

    The CSS file styles your slide deck. If it’s anywhere but Project/css/project_slidedeck.css, your knitted slides will not be format compliant and your submission will be rejected. The setup-check script will catch this, so there should be no excuse for not correcting the problem.

  2. Working from your Downloads folder

    If you launch a script or R Markdown file from your Downloads folder, RStudio’s working directory will be Downloads, not your Project/ folder and you will get cryptic “file not found” errors when the script or R Markdown tries to read files using here(). This occurs when you download the file pack into Downloads and then open the files directly from there.

  3. Knitting the R Markdown before running the R script

    Knitting pre_project.Rmd before running LF.R will generate a fatal error because the Rmd reads out/LF.csv, which doesn’t exist until you run LF.R. The setup-check script confirms that LF.R exists, but it can’t confirm that it actually produced LF.csv. Only running the script can confirm that.

1.8 What happens next

When you are set up, continue to the Pre-project Exercise. After completing it, download and sort the Main Project file pack as described in the Main Project chapter, then run its setup check before beginning the analysis.