---
title: "Every File in Its Place"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Every File in Its Place}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

## Why organize scripts?

A project with five R files is manageable. A project with fifteen is not, unless they follow a pattern.

`{froggeR}` initializes with three files in every project's `R/` directory:

- `_load.R` -- the entry point
- `_libraries.R` -- package loading
- `_data_dictionary.R` -- variable labels and metadata

These are **infrastructure** files. They set up the project so your analysis scripts can focus on the work. The underscore prefix keeps them sorted above everything else in the directory listing, making them easy to find.

## `_load.R`: one file to source

`_load.R` is the single entry point for your project. Source it, and everything initializes:

```r
source(here::here("R", "_load.R"))
```

Inside, it sources the other infrastructure files and runs any project-wide setup:

```r
# R/_load.R
source(here::here("R", "_libraries.R"))
source(here::here("R", "_data_dictionary.R"))
```

This cascading pattern means your Quarto documents and analysis scripts never need more than one `source()` call. As your project grows, add new files to `_load.R`:

```r
source(here::here("R", "_libraries.R"))
source(here::here("R", "_data_dictionary.R"))
source(here::here("R", "helpers.R"))
source(here::here("R", "clean_data.R"))
```

Your Quarto documents stay clean. One `source()` call at the top, then analysis.

## `_libraries.R`: packages in one place

```r
# R/_libraries.R
suppressPackageStartupMessages({
  library(tidyverse)
  library(gt)
})
```

Every `library()` call lives here. Not scattered across scripts. Not duplicated in Quarto documents. One file, one place to check.

This matters for three reasons:

1. **Visibility**: Anyone opening the project can see every dependency immediately.
2. **Maintenance**: Adding or removing a package is a one-line change in one file.
3. **Clean output**: `suppressPackageStartupMessages()` keeps your console and rendered documents free of startup noise.

## `_data_dictionary.R`: label your variables

```r
# R/_data_dictionary.R
dictionary <- dplyr::tribble(
  ~Variable, ~Description,
  "age", "Age in years",
  "sbp", "Systolic blood pressure (mmHg)",
  "treatment", "Treatment group assignment",
)
```

A data dictionary maps variable names to human-readable labels. Keeping it in a dedicated file means your labels are defined once and available everywhere, not buried inside whichever analysis script needed them first.

This is designed for use with [{sumExtras}](https://www.kylegrealis.com/sumExtras/) using the `options(sumExtras.auto_labels = TRUE)` and `options(sumExtras.prefer_dictionary = TRUE)` for automatic labelling. Your [{gtsummary}](https://www.danieldsjoberg.com/gtsummary/) tables get human-readable labels without manual labeling in every script. Define labels once here, apply them anywhere.

## `_quarto.yml`: how it all connects

The template's `_quarto.yml` is configured to match the directory layout:

```yaml
project:
  type: website
  output-dir: docs
  resources: www
  render:
    - "analysis/*.qmd"
```

Quarto only renders `.qmd` files found in `analysis/`. Static assets in `www/` are copied to the output as resources. Rendered HTML goes to `docs/`, keeping build artifacts out of your source directories. Explore the documentation for other [Quarto project](https://quarto.org/docs/projects/quarto-projects.html) types.

The styling and sidebar also reference these paths directly:

```yaml
format:
  html:
    theme:
      - default
      - brand
      - www/custom.scss

website:
  sidebar:
    contents:
      - text: Home
        href: analysis/index.qmd
```

`custom.scss` is expected in `www/`, and the sidebar links to documents in `analysis/`. Because the directory layout is predictable, the configuration works out of the box. You do not need to edit `_quarto.yml` to wire up paths. They are already correct. Add new documents to `analysis/`, then reference them in the `contents` section following the pattern shown for `analysis/index.qmd`.

For the full `_quarto.yml` specification, see [Quarto Project Basics](https://quarto.org/docs/projects/quarto-projects.html).

## `here::here()` and why relative paths break

Every `source()` call in the template uses `here::here()`:

```r
source(here::here("R", "_load.R"))
```

Not this:

```r
source("R/_load.R")
```

The difference matters the moment your working directory is not the project root. In a `{froggeR}` project, that happens by design.

When you render `analysis/index.qmd`, Quarto sets the working directory to `analysis/`. A relative path like `"R/_load.R"` resolves to `analysis/R/_load.R`, which does not exist. The render fails, and the error message does not make the cause obvious.

`here::here()` resolves paths from the project root, the directory containing your `.Rproj` or `.here` file, regardless of the current working directory. `here::here("R", "_load.R")` always points to the right file, whether you call it from the console, from a script in `R/`, or from a Quarto document in `analysis/`.

This is not just about `source()`. You should use `here::here()` for every file path in your project:

```r
# Reading data
df <- readr::read_csv(here::here("data", "raw_data.csv"))

# Saving output
ggsave(here::here("www", "figure1.png"))
```

Setting this one habit helps prevent an entire class of path-related errors. See the [{here}](https://here.r-lib.org/) package documentation for more.