Skip to contents

Introduction to boilerplate

Source: vignettes/boilerplate-intro.Rmd
boilerplate-intro.Rmd
library(boilerplate)
#> boilerplate 1.1.0

Overview

The boilerplate package provides tools for managing and generating standardised text for methods and results sections of scientific reports. It uses a unified database system with template variable substitution, making it easy to maintain consistent language across projects while allowing for customisation.

New in v1.1.0: The package now defaults to a single unified JSON database, simplifying database management and improving version control integration.

Key Features

  • Single JSON Database: All content types in one human-readable JSON file by default
  • Template Variable Substitution: Use {{variable}} placeholders for dynamic content
  • Hierarchical Organization: Organize content using dot notation (e.g., methods.statistical.longitudinal)
  • Batch Operations: Edit multiple entries at once
  • Safety Features: Confirmation prompts and backup creation
  • Version Control Friendly: JSON format makes Git diffs meaningful and merges easier

Quick Start

1. Initialise Databases

First, create and initialise your boilerplate databases:

# Initialise unified database with default content
# Creates a single boilerplate_unified.json file
boilerplate_init(
  create_dirs = TRUE,
  create_empty = FALSE,  # Use FALSE to get example content
  confirm = FALSE,
  quiet = FALSE
)

2. Import Databases

Import your databases to work with them:

# Import all databases as a unified structure
unified_db <- boilerplate_import()

# Or import specific categories
methods_db <- boilerplate_import("methods")
measures_db <- boilerplate_import("measures")

3. Generate Text

Generate text with variable substitution:

# Generate methods text
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = c("sample", "measures", "statistical_estimator"),
  global_vars = list(
    n_total = 5000,
    exposure_var = "political_conservative",
    outcome_var = "anxiety",
    population = "New Zealand adults"
  ),
  db = unified_db
)

cat(methods_text)

4. Generate Measure Descriptions

Create formatted descriptions of your measures:

# Generate measure descriptions
measures_text <- boilerplate_generate_measures(
  variable_heading = "Outcome Variables",
  variables = c("anxiety", "depression"),
  db = unified_db,
  sample_items = 3  # Show only first 3 items
)

cat(measures_text)

Working with Databases

Viewing Database Content 

# List all paths in a database
all_paths <- boilerplate_list_paths(unified_db)
head(all_paths)

# Get specific content
sample_text <- boilerplate_get_entry(unified_db, "methods.sample.default")
cat(sample_text)

Adding and Updating Content 

# Add a new entry
unified_db <- boilerplate_add_entry(
  db = unified_db,
  path = "methods.sample.online",
  value = "We recruited {{n_total}} participants through online platforms.",
  category = "methods"
)

# Update existing entry
unified_db <- boilerplate_update_entry(
  db = unified_db,
  path = "methods.sample.default",
  value = "Our sample consisted of {{n_total}} {{population}}.",
  category = "methods"
)

# Save changes
boilerplate_save(unified_db)

Batch Operations 

# Update multiple references at once
unified_db <- boilerplate_batch_edit(
  db = unified_db,
  field = "reference",
  new_value = "smith2024",
  target_entries = c("anxiety", "depression", "stress"),
  category = "measures"
)

# Clean text fields
unified_db <- boilerplate_batch_clean(
  db = unified_db,
  field = "description",
  remove_chars = c("@", "[", "]"),
  trim_whitespace = TRUE,
  category = "measures"
)

Template System

The template system uses {{variable}} placeholders that are replaced with actual values:

# Create a template
template_text <- "We analysed data from {{n_total}} {{population}} 
  ({{n_female}} female, {{n_male}} male) with a mean age of {{age_mean}} 
  years (SD = {{age_sd}})."

# Use in your database
unified_db <- boilerplate_add_entry(
  db = unified_db,
  path = "methods.participants.demographics",
  value = template_text,
  category = "methods"
)

# Generate with variables
demographics_text <- boilerplate_generate_text(
  category = "methods",
  sections = "participants.demographics",
  global_vars = list(
    n_total = 1000,
    population = "university students",
    n_female = 600,
    n_male = 400,
    age_mean = 21.3,
    age_sd = 3.2
  ),
  db = unified_db
)

Best Practices

  1. Use Version Control: Export your databases regularly for version control

    boilerplate_export(
  db = unified_db,
  output_file = "boilerplate_backup_2024.rds"
)

  2. Organise Hierarchically: Use dot notation for clear organisation

    # Good organisation
"methods.measures.psychological.anxiety"
"methods.measures.psychological.depression"
"methods.measures.demographic.age"

  3. Document Your Variables: Keep a record of template variables

    # Add a template reference
unified_db <- boilerplate_add_entry(
  db = unified_db,
  path = "templates.variable_reference",
  value = "Common variables: {{n_total}}, {{exposure_var}}, {{outcome_var}}",
  category = "template"
)

  4. Use Meaningful Names: Choose clear, descriptive names for entries

Advanced Features

Measure Standardisation 

# Standardise measure entries
unified_db$measures <- boilerplate_standardise_measures(
  unified_db$measures,
  extract_scale = TRUE,
  clean_descriptions = TRUE
)

# Generate quality report
boilerplate_measures_report(unified_db$measures)

Database Merging 

# Merge databases from different sources
merged_db <- boilerplate_merge_databases(
  db1 = project1_db,
  db2 = project2_db,
  db1_name = "Project 1",
  db2_name = "Project 2"
)

Managing Database Versions

The boilerplate package includes version management features to help you track and restore different versions of your databases.

Listing Available Versions 

# List all database files
files <- boilerplate_list_files()
print(files)

# List files for a specific category
methods_files <- boilerplate_list_files(category = "methods")

# Filter by date pattern
jan_files <- boilerplate_list_files(pattern = "202401")

Working with Timestamped Versions 

# Save with timestamp
boilerplate_save(
  db = unified_db,
  timestamp = TRUE  # Creates boilerplate_unified_20240115_143022.rds
)

# Import a specific timestamped version
old_version <- boilerplate_import(
  data_path = "boilerplate/data/boilerplate_unified_20240110_120000.rds"
)

Backup and Restore 

# View latest backup without restoring
backup_db <- boilerplate_restore_backup(category = "methods")

# Restore backup as current version
boilerplate_restore_backup(
  category = "methods",
  restore = TRUE,
  confirm = TRUE
)

# Restore specific backup by timestamp
boilerplate_restore_backup(
  category = "methods",
  backup_version = "20240110_120000",
  restore = TRUE
)

Getting Help

For more information and examples, see: