---
title: "Data standards and validation"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Data standards and validation}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

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

```{r}
template <- pcat_template("long", n_respondents = 2)
head(template)
```

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

```{r, eval=FALSE}
raw <- pcat_read_csv("completed_pcat.csv", layout = "auto")
```

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

```{r, eval=FALSE}
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

```{r}
validation <- pcat_validate(
  pcat_example_data(),
  require_complete = TRUE,
  action = "none"
)
validation
pcat_validation_issues(validation)
```

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.

```{r, eval=FALSE}
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.