# Getting Started with boilerplate: A Complete Workflow

# 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:

1. Use standardised text for common methods
2. Ensure consistency across co-authors
3. Manage citations properly
4. 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:

1. Initialise a boilerplate project structure
2. Explore and understand the default content
3. Customize methods and measures for your study
4. Manage bibliography and citations
5. Generate complete methods sections with parameters
6. Validate your content for completeness
7. Export for version control and sharing
8. 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!