Generate Formatted Text for Measures — boilerplate_generate

This function generates formatted markdown text describing measures in a study. It creates a simple output with customisable heading levels, focusing on presenting measure information in a clean, consistent format.

Usage

boilerplate_generate_measures(
  variable_heading,
  variables,
  db,
  heading_level = 3,
  subheading_level = 4,
  print_waves = FALSE,
  print_keywords = FALSE,
  appendices_measures = NULL,
  label_mappings = NULL,
  quiet = FALSE,
  sample_items = FALSE,
  table_format = FALSE,
  check_completeness = FALSE,
  extract_scale_info = TRUE
)

Arguments

variable_heading: Character. Heading for the variable section (e.g., "Exposure Variable", "Outcome Variables").
variables: Character vector. Names of the variables to include.
db: List. Measures database. Can be either a measures database or a unified database. If a unified database is provided, the measures category will be extracted.
heading_level: Integer. Heading level for the section header (e.g., 2 for ##, 3 for ###). Default is 3.
subheading_level: Integer. Heading level for individual variables (e.g., 3 for ###, 4 for ####). Default is 4.
print_waves: Logical. Whether to include wave information in the output. Default is FALSE.
print_keywords: Logical. Whether to include keyword information in the output. Default is FALSE.
appendices_measures: Character. Optional reference to appendices containing measure details.
label_mappings: Named character vector. Mappings to transform variable names in the output.
quiet: Logical. If TRUE, suppresses all CLI alerts. Default is FALSE.
sample_items: Integer or FALSE. If numeric (1-3), shows only that many sample items. Default is FALSE (show all).
table_format: Logical. If TRUE, formats output as markdown tables. Default is FALSE.
check_completeness: Logical. If TRUE, adds notes about missing information. Default is FALSE.
extract_scale_info: Logical. If TRUE, attempts to extract scale information from descriptions. Default is TRUE.

Value

Character string with formatted text describing the measures.

Examples

# Create a temporary directory and initialise databases
temp_dir <- tempdir()
data_path <- file.path(temp_dir, "boilerplate_measures_example", "data")

# Initialise measures database with default content
boilerplate_init(
  categories = "measures",
  data_path = data_path,
  create_dirs = TRUE,
  create_empty = FALSE,
  confirm = FALSE,
  quiet = TRUE
)

# Import the unified database
unified_db <- boilerplate_import(data_path = data_path, quiet = TRUE)
measures_db <- unified_db$measures

# Generate with sample items only
exposure_text <- boilerplate_generate_measures(
  variable_heading = "Exposure Variable",
  variables = "anxiety",
  db = measures_db,
  sample_items = 2,  # Show only first 2 items
  quiet = TRUE
)

# Check the output
cat(substr(exposure_text, 1, 150), "...\n")
#> ### Exposure Variable
#> 
#> #### Anxiety Scale
#> 
#> anxiety was measured using a standard anxiety scale [@anxiety_reference].
#> 
#> Items:
#> 
#> * feeling nervous or anx ...

# Generate with table format for multiple variables
outcome_text <- boilerplate_generate_measures(
  variable_heading = "Outcome Variables",
  variables = c("anxiety", "depression"),
  db = measures_db,
  table_format = TRUE,
  quiet = TRUE
)

# Clean up
unlink(file.path(temp_dir, "boilerplate_measures_example"), recursive = TRUE)