Data standards and validation

Standard long format

One row represents one respondent-item response within one assessment. The required columns are respondent_id, item_id, direction, and effect. Recommended metadata include project, site, team, role, timepoint, and assessment date.

template <- pcat_template("long", n_respondents = 2)
head(template)
#>   project_id respondent_id site_id team_id role timepoint assessment_date
#> 1 PROJECT_01          R001 SITE_01    <NA> <NA>  planning            <NA>
#> 2 PROJECT_01          R001 SITE_01    <NA> <NA>  planning            <NA>
#> 3 PROJECT_01          R001 SITE_01    <NA> <NA>  planning            <NA>
#> 4 PROJECT_01          R001 SITE_01    <NA> <NA>  planning            <NA>
#> 5 PROJECT_01          R001 SITE_01    <NA> <NA>  planning            <NA>
#> 6 PROJECT_01          R001 SITE_01    <NA> <NA>  planning            <NA>
#>   item_id
#> 1       1
#> 2       2
#> 3       3
#> 4       4
#> 5       5
#> 6       6
#>                                                                                                     item_text
#> 1 People here regularly seek to understand the needs of patients and make changes to better meet those needs.
#> 2                                 I have open lines of communication with everyone needed to make the change.
#> 3                                                    I have access to data to help track changes in outcomes.
#> 4                                                                The change is aligned with leadership goals.
#> 5                                                                The change is aligned with clinician values.
#> 6                                                  The change is compatible with existing clinical processes.
#>   direction effect comment
#> 1        NA     NA    <NA>
#> 2        NA     NA    <NA>
#> 3        NA     NA    <NA>
#> 4        NA     NA    <NA>
#> 5        NA     NA    <NA>
#> 6        NA     NA    <NA>

Direction is coded 1 = potential barrier, 2 = neutral, and 3 = potential facilitator. Effect is coded 0 = weak/no effect and 1 = strong effect. Leave effect missing when direction is neutral.

Import standard files

raw <- pcat_read_csv("completed_pcat.csv", layout = "auto")

For non-standard source columns, import with a general CSV reader and map them explicitly.

standard <- pcat_standardize(
  raw_data,
  respondent_id = "participant_code",
  item_id = "question_number",
  direction = "direction_response",
  effect = "effect_response",
  site_id = "clinic",
  timepoint = "wave"
)

Validation

validation <- pcat_validate(
  pcat_example_data(),
  require_complete = TRUE,
  action = "none"
)
validation
#> <pcat_validation>
#>   valid: yes
#>   rows: 336
#>   errors: 0
#>   warnings: 0
#>   complete assessments required: yes
pcat_validation_issues(validation)
#> [1] .pcat_row  issue_code severity   message   
#> <0 rows> (or 0-length row.names)

The default flags a neutral response with any recorded effect. A barrier or facilitator without an effect remains directionally informative but cannot be placed in one of the five complete categories.

Duplicate keys and completeness

By default, an assessment key is assembled from available project, site, team, timepoint, assessment date, and respondent identifiers. Supply key_cols explicitly when your design uses different boundaries.

pcat_validate(
  data,
  key_cols = c("project_id", "site_id", "timepoint", "respondent_id"),
  require_complete = TRUE,
  action = "error"
)

Denominators

Directional percentages use all eligible records with a valid direction and therefore use n_valid_direction. Complete five-category percentages use only eligible records with a complete direction-plus-effect classification and use n_complete_class. pct_complete_class is n_complete_class divided by n_valid_direction and describes the share of valid-direction records with a complete five-category classification. The directional n_neutral count can exceed n_neutral_complete when a neutral direction has an invalid effect value. Report both denominators rather than silently treating missing or invalid effects as complete classifications.