1  Files

1.1 Names

1. File names should be machine readable: avoid spaces, symbols, and special characters. Prefer file names that are all lower case, and never have names that differ only in their capitalization. Delimit words with - or _. Use .R as the extension of R files.

   # Good
   fit_models.R
   utility_functions.R
   
   # Bad
   fit models.R
   foo.r
   ExploratoryDataAnalysis.r

2. File names should be human readable: use file names to describe what’s in the file.

   # good
   report_draft_notes.txt
   
   # bad
   temp.r

   Use the same structure for closely related files:

   # good
   fig_eda.png
   fig_model_3.png
   
   # bad
   figure eda.PNG
   fig model three.png

3. File names should play well with default ordering. If your file names contain dates, use yyyy-mm-dd (ISO8601) format so they sort in chronological order. If your file names include numbers, make sure to pad them with the appropriate number of zeros so that (e.g.) 11 doesn’t get sorted before 2. If files should be used in a specific order, put the number at the start, not the end.

   # good
   01_load_data.R
   02_exploratory_analysis.R
   03_model_approach_1.R
   04_model_approach_2.R
   2025_01_01_report.Rmd
   2025_02_01_report.Rmd
   
   # bad
   alternative model.R
   code for exploratory analysis.r
   feb 01 report.Rmd
   jan 01 report.Rmd
   model_first_try.R
   run-first.r

   If you later realise that you’ve missed some steps, it’s tempting to use 02a, 02b, etc. However, I think it’s generally better to bite the bullet and rename all files.

4. Don’t tempt fate by using “final” or similar words in file names. Instead either rely on Git to track changes over time, or failing that, put the date in the file name.

   # good
   20220320_report.qmd
   20220402_report.qmd
   
   # bad
   finalreport.qmd
   FinalReport-2.qmd

1.2 R scripts

For every R script use the R snippet setup-default, by using the template across the lab, it will make sharing code easier within the lab and for publication.

The snippet generates the following:

# ==== Script Information =======================================================
# Author(s): Joan Kant
# Created: 2026-10-31
# Last modified: 2026-10-31
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Project: Gaiti Lab style
# Script Name: test.R
# Work directory: /Users/joankant/Coding/style
# Container or conda environment used:
# Script Description/Purpose:
# Notes:
# ===============================================================================
# Setup environment ---------------------------------------
# Unload all previously loaded packages + remove previous environment
rm(list = ls(all = TRUE))
box::purge_cache()
pacman::p_unload()
# Setup options
# box.path can be a vector if there are multiple variables
options(box.path = c(file.path(Sys.getenv("GLTB"), "modules")))

# Load libraries
pacman::p_load(data.table, tidyverse, stringr, duckplyr, logger, glue)
box::use(
    base/templateScript[BasicArgumentParser, SetupScript, SetWd, LogSession]
)
# Sets wd based on .git location
SetWd()

# Define input arguments when running from bash
parser <- BasicArgumentParser(description = "")
# Add more arguments, use parser$add_argument()
params <- parser$parse_args()

if (interactive()) {
    # Provide arguments here for local runs
    params$output_dir <- here::here("07_output")
    params$log_path <- NULL
}
params <- SetupScript(params)

# ---- Function(s) ----

# ---- Config ----
# ===============================================================================

# ---- Load data ----

# ---- Analysis ----


# ===============================================================================

log_info("Finished")
LogSession(params)

For existing R scripts, you can use the snippet r-header to only generate the header:

# ==== Script Information =======================================================
# Author(s):
# Created: 2026-10-31
# Last modified: 2026-10-31
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Project:
# Script Name: files.qmd
# Work directory: /Users/joankant/Coding/style
# Container or conda environment used:
# Script Description/Purpose:
# Notes:
# ===============================================================================

With the VS Code extension Auto Time Stamp, the ‘Last modified’ property will be automatically updated. When you install the VS Code Gaiti Lab Profile from GaitiLab/GaitiLabToolBox/templates/configs this extension will be automatically installed.

1.3 Internal structure

Use commented lines of - and = to break up your file into easily readable chunks. R snippets are available to do this: chunk or create_section

chunk generates:

# chunkName ---------------------------

create_section generates:

# ---- sectionName ----