Introduction to boilerplate

library(boilerplate)
#> boilerplate 1.3.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

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
# Using a temporary directory for this example
temp_intro <- file.path(tempdir(), "intro_example")
boilerplate_init(
  data_path = temp_intro,
  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(data_path = temp_intro)

# Or import specific categories
methods_db <- boilerplate_import("methods", data_path = temp_intro)
measures_db <- boilerplate_import("measures", data_path = temp_intro)

3. Generate Text

Generate text with variable substitution:

# Generate methods text
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = c("sample.default", "statistical.default"),  # Use valid paths
  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, data_path = temp_intro, confirm = FALSE, quiet = TRUE)

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(
 unified_db,
 data_path = temp_intro,  # Specify where to save
 output_file = "backup_" + format(Sys.Date(), "%Y%m%d") + ".json",
 confirm = FALSE,
 quiet = TRUE
  )
  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)

Cross-Project Workflows

# Work with multiple projects
# Create a project for shared content
boilerplate_init(project = "shared", confirm = FALSE)

# Copy content between projects
boilerplate_copy_from_project(
  from_project = "shared",
  to_project = "default",
  paths = c("methods.statistical", "measures.anxiety"),
  confirm = FALSE
)

# List available projects
projects <- boilerplate_list_projects(details = TRUE)

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: