Introduction

This tutorial walks you through a complete workflow using the boilerplate package, from initial setup to generating a complete methods section for a scientific paper. We’ll build a real example step by step.

Scenario: Writing a Psychology Research Paper

Imagine you’re writing a paper about the relationship between political attitudes and well-being. You want to:

Use standardised text for common methods
Ensure consistency across co-authors
Manage citations properly
Generate reproducible documentation

Let’s see how boilerplate makes this easier!

Note on Working Directories: This vignette uses relative paths and does not change your working directory with setwd(). All paths are constructed relative to your current location, making the code more reproducible and safer to run.

Step 1: Initial Project Setup

Install and Load the Package

# Install from CRAN (when available)
# install.packages("boilerplate")

# Or install development version
# devtools::install_github("go-bayes/boilerplate")

# Load the package
library(boilerplate)

Create Project Structure

# Set up your project structure (without changing working directory)
# Option 1: Create in current directory
project_name <- "my_wellbeing_study"
data_path <- file.path(project_name, "data", "boilerplate")

# Option 2: Use a specific location (uncomment if preferred)
# Note: Replace with your actual project directory
# project_dir <- "/path/to/your/project"  # e.g., "~/Documents/my_wellbeing_study"
# data_path <- file.path(project_dir, "data", "boilerplate")

# Best practice: Use relative paths or file.path() for project-based paths
# data_path <- file.path("data", "boilerplate")

# Initialise unified database with full path
boilerplate_init(
  data_path = data_path,
  create_dirs = TRUE,
  create_empty = FALSE  # Start with example content
)
#> ✔ Created directory: my_wellbeing_study/data/boilerplate
#> ✔ Initialising unified database with 6 categories
#> ✔ Saved unified database to my_wellbeing_study/data/boilerplate/boilerplate_unified.json

Step 2: Explore the Default Content

View Available Methods

# Import the database using the same path
db <- boilerplate_import(data_path = data_path)

# See what methods are available
methods_db <- boilerplate_methods(db)
# List paths in the methods database
# Note: boilerplate_list_paths() is a helper function that may need to be implemented
# For now, you can explore the structure with:
names(methods_db)
#> [1] "sample"             "causal_assumptions" "statistical"       

# Look at a specific method
cat(methods_db$sample$default)
#> Participants were recruited from {{recruitment_source}}. The final sample 
#> consisted of {{n_total}} participants ({{n_female}} female, {{n_male}} male, 
#> {{n_other}} other/not specified).

View Available Measures

# See what measures are available
measures_db <- boilerplate_measures(db)
names(measures_db)
#> [1] "anxiety"      "depression"   "life_satisfaction"  "political_orientation"

# Examine a measure (if it exists)
if ("political_orientation" %in% names(measures_db)) {
  measures_db$political_orientation
} else {
  # The default database may not include political_orientation
  # Let's look at what's actually available
  str(measures_db[[1]])  # Show structure of first measure
}

Step 3: Customise for Your Study

Add Study-Specific Methods

# The 'db' variable contains our database from Step 2
# Now we'll add custom content for our study

# Add your sampling method
db <- boilerplate_add_entry(
  db,
  path = "methods.sample.nz_national",
  value = paste0(
    "Data were collected as part of the New Zealand Attitudes and Values Study ",
    "(NZAVS), a longitudinal national probability sample of New Zealand adults. ",
    "For this study, we analysed data from Wave {{wave}} ({{year}}), which included ",
    "{{n_total}} participants ({{pct_female}}% female, {{pct_maori}}% Māori, ",
    "Mage = {{m_age}}, SD = {{sd_age}})."
  )
)

# Add your analysis approach
db <- boilerplate_add_entry(
  db,
  path = "methods.analysis.political_wellbeing",
  value = paste0(
    "We examined the relationship between political orientation and well-being ",
    "using {{analysis_type}}. Political orientation was measured on a 7-point scale ",
    "from very liberal (1) to very conservative (7). Well-being was assessed using ",
    "{{wellbeing_measure}}. We controlled for {{covariates}} in all analyses. ",
    "All analyses were conducted in R version {{r_version}} using the ",
    "{{packages}} packages."
  )
)

# Save your customizations
boilerplate_save(db, data_path = data_path)

Add Study-Specific Measures

# Add a well-being measure
db <- boilerplate_add_entry(
  db,
  path = "measures.wellbeing_index",
  value = list(
    name = "wellbeing_index",
    description = "Composite well-being index combining life satisfaction, positive affect, and meaning in life",
    type = "continuous",
    items = c(
      "In general, how satisfied are you with your life?",
      "In general, how often do you experience positive emotions?",
      "To what extent do you feel your life has meaning and purpose?"
    ),
    scale = "0-10",
    reference = "@diener2009"
  )
)

# Update the database
boilerplate_save(db, data_path = data_path)

Step 4: Set Up Bibliography Management

# Continue working with our 'db' from previous steps
# Configure bibliography source
# Using the example bibliography included with the package
example_bib <- system.file("extdata", "example_references.bib", package = "boilerplate")
db <- boilerplate_add_bibliography(
  db,
  url = paste0("file://", example_bib),
  local_path = "references.bib"
)

# Download and copy bibliography
boilerplate_copy_bibliography(db, target_dir = ".")

# Save configuration
boilerplate_save(db, data_path = data_path)

Step 5: Generate Your Methods Section

Define Study Parameters

# Set all your study-specific values
study_params <- list(
  # Sample characteristics
  wave = 13,
  year = "2021-2022",
  n_total = 34782,
  pct_female = 62.3,
  pct_maori = 15.7,
  m_age = 48.2,
  sd_age = 13.9,
  
  # Analysis details
  analysis_type = "multilevel regression models",
  wellbeing_measure = "the Well-being Index",
  covariates = "age, gender, education, and income",
  r_version = "4.3.2",
  packages = "lme4 and marginaleffects",
  
  # Other parameters
  recruitment_source = "electoral rolls",
  n_female = 21680,
  n_male = 13102,
  n_other = 0
)

Generate Complete Methods Section

# Generate methods text with your parameters
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = c(
    "sample.nz_national",
    "statistical.default",  # Use an existing path
    "analysis.political_wellbeing",
    "causal_assumptions.identification"  # Use an existing path
  ),
  global_vars = study_params,
  db = db,
  copy_bibliography = TRUE
)

# View the generated text
cat(methods_text)

Output:

Data were collected as part of the New Zealand Attitudes and Values Study (NZAVS), 
a longitudinal national probability sample of New Zealand adults. For this study, 
we analysed data from Wave 13 (2021-2022), which included 34782 participants 
(62.3% female, 15.7% Māori, Mage = 48.2, SD = 13.9).

We used appropriate statistical methods for causal inference.

We examined the relationship between political orientation and well-being using 
multilevel regression models. Political orientation was measured on a 7-point scale 
from very liberal (1) to very conservative (7). Well-being was assessed using the 
Well-being Index. We controlled for age, gender, education, and income in all 
analyses. All analyses were conducted in R version 4.3.2 using the lme4 and 
marginaleffects packages.

This study relies on the following identification assumptions for estimating the causal effect of political_conservative:

1. **Consistency**: the observed outcome under the observed political_conservative is equal to the potential outcome under that exposure level.

2. **Positivity**: there is a non-zero probability of receiving each level of political_conservative for every combination of values of political_conservative and confounders in the population.

3. **No unmeasured confounding**: all variables that affect both political_conservative and the outcome have been measured and accounted for in the analysis.

Step 6: Generate Measures Section

# Generate description of your measures
measures_text <- boilerplate_generate_measures(
  measures = c("wellbeing_index", "anxiety", "depression"),  # Only include measures we added
  db = db
)

cat(measures_text)

Generate output for political orientation if we added it

if (“political_orientation” %in% names(boilerplate_measures(db))) { pol_text <- boilerplate_generate_measures( measures = “political_orientation”, db = db ) cat(pol_text) }

Step 7: Validate Your Work

Check Database Structure

Ensure your database is properly structured:

# Check that all paths exist
required_paths <- c(
  "methods.sample.nz_national",
  "methods.analysis.political_wellbeing",
  "measures.wellbeing_index"
)

for (path in required_paths) {
  exists <- boilerplate_path_exists(db, path)
  cat(sprintf("%s: %s\n", path, ifelse(exists, "✓", "✗")))
}

# List all available methods paths
methods_db <- boilerplate_methods(db)
cat("\nAvailable methods paths:\n")
print(boilerplate_list_paths(methods_db))

# List all measures
measures_db <- boilerplate_measures(db)
cat("\nAvailable measures:\n")
print(names(measures_db))

Check References

# Ensure all citations are in your bibliography
validation <- boilerplate_validate_references(db)

if (!validation$valid) {
  warning("Missing references found:")
  print(validation$missing)
} else {
  message("All references validated! ✓")
}

Export for Version Control

# Export your complete database for version control
boilerplate_export(
  db,
  paths = c("methods.*", "measures.*"),
  data_path = data_path,
  output_file = "project_boilerplate.json",
  format = "json"  # JSON is git-friendly
)

Step 8: Create Your Manuscript

Quarto Document Example

Create a file manuscript.qmd:

---
title: "Political Orientation and Well-being: A National Study"
author: "Your Name"
bibliography: references.bib
format: 
  pdf:
    keep-tex: true
---

# Method

Measures

Results

[Your results here]

Discussion

[Your discussion here]


# Advanced Tips

## 1. Team Collaboration

Share your boilerplate database with collaborators:


``` r
# Export to shared location
# Note: Replace 'shared_path' with your actual shared folder location
# Examples: Dropbox, OneDrive, network drive, or Git repository
shared_path <- "/path/to/shared/folder"  # e.g., "~/Dropbox/TeamProject"

boilerplate_export(
  db,
  data_path = data_path,
  output_file = file.path(shared_path, "shared_boilerplate.json"),
  format = "json"
)

# Collaborator imports
team_db <- boilerplate_import(file.path(shared_path, "shared_boilerplate.json"))

2. Multiple Papers from Same Dataset

Create variants for different papers:

# Paper 1: Focus on political orientation
db <- boilerplate_add_entry(
  db,
  path = "methods.sample.paper1",
  value = "We analysed data from {{n_conservatives}} conservative and {{n_liberals}} liberal participants..."
)

# Paper 2: Focus on well-being
db <- boilerplate_add_entry(
  db,
  path = "methods.sample.paper2",
  value = "We examined well-being trajectories among {{n_high_wellbeing}} high and {{n_low_wellbeing}} low well-being participants..."
)

# Check all methods entries
methods_db <- boilerplate_methods(db)
cat("Available sample methods:\n")
sample_paths <- grep("^sample\\.", boilerplate_list_paths(methods_db), value = TRUE)
print(sample_paths)

3. Batch Updates

Update multiple entries at once:

# Update all methods to include ethics statement
db <- boilerplate_batch_edit(
  db,
  field = "ethics",
  new_value = "This study was approved by the University Ethics Committee (ref: {{ethics_ref}}).",
  target_entries = "methods.*",
  category = "methods"
)

4. Quality Control

Create a comprehensive reporting function for your team:

check_manuscript_ready <- function(db) {
  cat("Manuscript Checklist:\n")
  cat("==================\n\n")
  
  # Check all sections exist
  cat("Required Sections:\n")
  required_sections <- c(
    "methods.sample", "methods.design", 
    "methods.analysis", "methods.missing"
  )
  
  for (section in required_sections) {
    exists <- boilerplate_path_exists(db, section)
    status <- if (exists) "✓" else "✗"
    cat(sprintf("%s %s\n", status, section))
  }
  
  # Check references
  cat("\nReferences:\n")
  validation <- boilerplate_validate_references(db, quiet = TRUE)
  ref_status <- if (validation$valid) "✓" else "✗"
  cat(sprintf("%s All references validated\n", ref_status))
  
  # Check measures
  cat("\nMeasures:\n")
  measures_db <- boilerplate_measures(db)
  cat(sprintf("✓ %d measures documented\n", length(measures_db)))
  
  # Count total entries
  cat("\nDatabase Summary:\n")
  methods_count <- length(boilerplate_list_paths(boilerplate_methods(db)))
  measures_count <- length(boilerplate_measures(db))
  cat(sprintf("✓ %d methods entries\n", methods_count))
  cat(sprintf("✓ %d measures entries\n", measures_count))
  
  invisible(list(
    sections_ok = all(sapply(required_sections, 
                             function(s) boilerplate_path_exists(db, s))),
    references_ok = validation$valid,
    methods_count = methods_count,
    measures_count = measures_count
  ))
}

# Run the check
readiness <- check_manuscript_ready(db)
#> Manuscript Checklist:
#> ==================
#> 
#> Required Sections:
#> ✓ methods.sample
#> ✓ methods.design
#> ✓ methods.analysis
#> ✓ methods.missing
#> 
#> References:
#> ✓ All references validated
#> 
#> Measures:
#> ✓ 5 measures documented
#> 
#> Database Summary:
#> ✓ 15 methods entries
#> ✓ 5 measures entries

Summary

You’ve learned how to:

Initialise a boilerplate project structure
Explore and understand the default content
Customize methods and measures for your study
Manage bibliography and citations
Generate complete methods sections with parameters
Validate your content for completeness
Export for version control and sharing
Integrate with Quarto/R Markdown documents

The boilerplate package helps you: - ✓ Write consistent, professional methods sections - ✓ Reuse content across multiple papers - ✓ Collaborate effectively with co-authors - ✓ Maintain version control of your text - ✓ Ensure citation completeness

Next Steps

Read the JSON Workflow vignette for advanced database management
See the Architecture vignette to understand the package design
Check the Measures Workflow for detailed measure documentation
Explore the Bibliography Management guide for reference handling

Happy writing!

Getting Started with boilerplate: A Complete Workflow