The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

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:

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.