7  Starting a Project

Every dataset in this book so far has arrived ready to use: a tidy CSV, in the right folder, with sensible column names. Data does not normally show up that way. It shows up as a spreadsheet somebody emailed you, with the numbers starting on row 8.

This module covers the work between getting a file and being able to analyze it: setting up a project, reading the data in, and checking whether it can be trusted.

Learning Objectives

By the end of this chapter you should be able to:

  1. Lay out a project folder that someone else can open and run.
  2. Explain why a script should never contain setwd().
  3. Keep raw data separate from anything you have changed.
  4. Write a README that says where the data came from.

7.1 One Folder Per Project

The working directory (Section 5.1) is the folder R treats as “here”, and the reason read_csv("yields.csv") sometimes fails to find a file that is sitting right in front of you. The advice there was to keep each analysis in its own folder. This section is about what goes in that folder.

A layout that works for almost everything:

canola-trial/
  data/
    canola_trial.csv          <- exactly as it arrived
  R/
    01_clean.R
    02_analysis.R
  output/
    yield_by_variety.png
    summary_table.csv
  README.md

The project is self-contained. Everything the analysis needs is inside canola-trial/. You can zip the folder, send it to somebody, and it will run on their machine. A script that reaches out to a file elsewhere on your hard drive will not.

Raw data is never edited. data/ holds the file as it arrived. If you open the CSV in Excel, fix three cells and save, you have written over the only copy of what you were given, and there is no record of what you changed. Do the fixing in the script, where it leaves a trail.

Outputs are disposable. Anything in output/ can be deleted and regenerated by re-running the scripts. That is a useful test: delete output/, run the scripts, and see whether everything comes back.

Scripts are numbered in the order they run. 01_clean.R then 02_analysis.R. Six months later this tells you where to start. It also makes it obvious when a project has grown a script that has to run third but is named as though it runs first.

7.2 Paths, and Why setwd() Is a Trap

A path tells R where a file is. There are two kinds.

An absolute path starts at the root of your hard drive:

read_csv("/Users/peter/Documents/canola-trial/data/canola_trial.csv")

A relative path starts wherever R currently is:

read_csv("data/canola_trial.csv")

The relative version works on any machine where the project folder is open. The absolute one works only on mine, because it names a user, a folder layout and an operating system that your classmate does not share.

The same objection applies to putting setwd() in a script:

setwd("/Users/peter/Documents/canola-trial")     # do not do this

In my experience this is the most common reason a script that works fine for its author fails for everyone else. It writes one machine into a file you are going to share. Open the project folder instead, with File → Open Folder… in Positron, and the working directory is already correct, so plain relative paths work.

One wrinkle. Windows paths use backslashes, as in C:\Users\..., but a backslash means something special inside an R string. Write forward slashes even on Windows: "C:/Users/...". R handles the translation.

7.3 Say Where It Came From

Every project gets a README.md at the top of the folder, saying what the project is and where the data came from. It does not need to be long.

# Canola nitrogen trial, 2025

Question: how much does yield respond to nitrogen rate, and how much of
that association is really rainfall?

Data
  data/canola_trial.csv
    120 fields. Downloaded from [source] on 2026-08-18.
    Columns: field_id, fertilizer_kg_ha, rainfall_mm, variety, yield_bu_acre

Scripts
  R/01_clean.R      reads the raw file, fixes units, writes data/clean.csv
  R/02_analysis.R   correlation, regression, figures

The source and the download date are the parts that earn their keep. A file called yields_final.csv with no provenance is close to useless a year later: you cannot tell whether it is the 2024 or the 2025 release, whether you already cleaned it, or whether the numbers were revised after you downloaded them. Statistics Canada revises past figures, so “downloaded 2026-08-18” is doing real work.

7.4 File Names

Two rules save a lot of trouble.

Avoid spaces and punctuation. yield data (final).csv will work until the day it does not. yield_data_final.csv is safer.

Write dates as YYYY-MM-DD. 2025-09-15_deliveries.csv sorts chronologically on its own, and Sept15.csv does not.

If you find yourself writing final, final_v2, final_REAL in file names, the project needs a way of tracking versions rather than a longer file name. Version control systems do this, and Git is the common one. It is worth learning if you carry on with this kind of work, though we will not cover it here.

7.5 Test Bank Sample

  1. (Structure.) A classmate sends you a folder containing one script and no data. What are they likely to have done wrong?
  2. (Paths.) Explain the difference between an absolute and a relative path, and say which belongs in a shared script.
  3. (setwd.) Why does a script containing setwd("C:/Users/peter/project") fail for everyone except Peter?
  4. (Raw data.) You spot three obviously wrong values in the CSV you were sent. Why should you not fix them in Excel and save?
  5. (README.) Name two things a README should record about a dataset, and say why each matters a year later.

7.6 Practice Exercises

  1. Set up a project folder for the canola trial with the layout above. Open it in Positron and confirm getwd() points where you expect.
  2. Write a script that reads data/canola_trial.csv using a relative path and writes a summary table to output/.
  3. Delete everything in output/ and re-run the script. Does it all come back? If not, why not?
  4. Write a README for the project, including where the data came from and what each script does.