---
title: "Getting Started with boilerplate: A Complete Workflow"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with boilerplate: A Complete Workflow}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  eval = FALSE
)
```

# 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

```{r install}
# 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

```{r setup-project}
# 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

```{r explore-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

```{r explore-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

```{r add-custom-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

```{r add-custom-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

```{r setup-bibliography}
# 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

```{r define-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

```{r generate-methods}
# 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

```{r generate-measures}
# 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:

```{r check-structure}
# 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

```{r validate-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

```{r export-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`:

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

# Method

```{r load-methods, echo=FALSE, results='asis'}
library(boilerplate)
db <- boilerplate_import("data/boilerplate")

# Generate and display methods
methods_text <- boilerplate_generate_text(
  category = "methods",
  sections = c(
    "sample.nz_national",
    "design.longitudinal",
    "analysis.political_wellbeing"
  ),
  global_vars = study_params,
  db = db
)

cat(methods_text)
```

## Measures

```{r load-measures, echo=FALSE, results='asis'}
measures_text <- boilerplate_generate_measures(
  measures = c("political_orientation", "wellbeing_index"),
  db = db
)

cat(measures_text)
```

# Results

[Your results here]

# Discussion

[Your discussion here]
```

# Advanced Tips

## 1. Team Collaboration

Share your boilerplate database with collaborators:

```{r team-collaboration}
# 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:

```{r multiple-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:

```{r batch-updates}
# 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:

```{r quality-control}
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](boilerplate-json-workflow.html) vignette for advanced database management
- See the [Architecture](boilerplate-architecture.html) vignette to understand the package design
- Check the [Measures Workflow](boilerplate-measures-workflow.html) for detailed measure documentation
- Explore the [Bibliography Management](boilerplate-bibliography-workflow.html) guide for reference handling

Happy writing!