Parse a codebook file into variable definitions

Rule-based codebook reader. Handles structured tables (CSV/TSV/Excel with a variable-name column and a label column, including wide-format transposition and multi-row header scanning), and embedded haven labels (SPSS/Stata). For rich-text formats (docx/pdf/rtf/odt) it extracts plain text. Files that yield no structured definitions return their raw text lines (character vector) so the caller can route them to an LLM when llm_use(TRUE).

Usage

parse_codebook(
  path,
  header_lookahead = 5L,
  observed = list(),
  group = NA_character_
)

Arguments

path

path to a codebook/readme file

header_lookahead

rows to scan for a header in multi-level CSVs

group

the file's study/experiment group (data_check's structure_df$group for this file), scoping the definitions it yields to that ONE study. NA_character_ (the default) leaves them unscoped, which match_column_labels() then applies to every same-named column PAPER-WIDE – correct for a genuinely paper-wide codebook, but it also lets one study's codebook (e.g. a condition variable coded 1-4 in Study A) leak onto an unrelated same-named column in Study B (coded 1-6). Callers that know the file's group should pass it. Mirrors .extract_haven_labels's group argument.

Value

a data.frame of variable definitions (codebook_variable, label, codebook_source, group, parse_method); a character vector of text lines when only unstructured text is available; or NULL on failure.

Examples

parse_codebook(file.path(demofile("repo"), "documentation",
                          "stroop_data_codebook.csv"))
#>   codebook_variable
#> 1    participant_id
#> 2         congruent
#> 3       incongruent
#> 4              year
#>                                                                                      label
#> 1                                                                   Participant identifier
#> 2   Reaction time (in seconds) to name all words in the congruent block of the Stroop task
#> 3 Reaction time (in seconds) to name all words in the incongruent block of the Stroop task
#> 4                                                    Year in which the data were collected
#>            codebook_source group value_labels missing_values question
#> 1 stroop_data_codebook.csv  <NA>         <NA>           <NA>     <NA>
#> 2 stroop_data_codebook.csv  <NA>         <NA>           <NA>     <NA>
#> 3 stroop_data_codebook.csv  <NA>         <NA>           <NA>     <NA>
#> 4 stroop_data_codebook.csv  <NA>         <NA>           <NA>     <NA>
#>   coding_instructions parse_method
#> 1                <NA>   structured
#> 2                <NA>   structured
#> 3                <NA>   structured
#> 4                <NA>   structured