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

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

```{r setup}
library(contentvalidR)
```

**Overview**

This vignette introduces the package's three recommended content-pretesting workflows—**item sorting**, **construct ratings**, and **expert panels**. `sort_validity()`, `rating_validity()`, and `expert_validity()` organize quantitative evidence while keeping substantive decisions separate from statistical flags.

**A common workflow contract**

All three fitted workflow objects expose `results`, `scale_summary`, `settings`, `design`, and `details`. Their result tables also contain a common `status` field: `Supported`, `Review`, `Insufficient data`, or `Descriptive only`. Method-specific recommendation wording is preserved alongside that common status. This makes it possible to write reusable code across workflows without pretending that a Howard-Melloy retention decision, Hinkin-Tracey screening result, and expert-panel judgment are substantively identical.

**Sort-based (Psa, Csv, binomial)**
```{r}
toy_sort <- data.frame(
  item = rep(paste0("I", 1:4), each = 12),
  rater = rep(1:12, 4),
  target_construct   = rep(c("A","A","B","B"), each = 12),
  assigned_construct = c(
    sample(c("A","B"), 12, TRUE, c(.80,.20)),
    sample(c("A","B"), 12, TRUE, c(.65,.35)),
    sample(c("A","B"), 12, TRUE, c(.70,.30)),
    sample(c("A","B"), 12, TRUE, c(.45,.55))
  )
)
psa <- compute_psa(toy_sort)
csv <- compute_csv(toy_sort)
csv$decision <- vapply(seq_len(nrow(csv)), function(i) {
  csv_binom_test(csv$n_target[i], csv$n[i])$decision
}, character(1))
psa; csv
```

**Interpretation**
- **Psa** = share assigning the intended construct.
- **Csv** = margin of wins: $ \frac{n_{target} - max_{other}}{N} $.
- Binomial test (H0: $ p ≤ .5 $) flags items with above-chance targeting.

**Construct-rating workflow (HTC, HTD, repeated-measures ANOVA)**
```{r}
set.seed(2)
toy_ratings <- expand.grid(
  item = c("I1", "I2", "I3"),
  rater = 1:16,
  construct = c("A", "B", "C")
)
toy_ratings$target_construct <- ifelse(toy_ratings$item == "I3", "B", "A")
toy_ratings$rating <- ifelse(
  toy_ratings$construct == toy_ratings$target_construct,
  pmin(5, pmax(1, round(rnorm(nrow(toy_ratings), 4.4, .6)))),
  pmin(5, pmax(1, round(rnorm(nrow(toy_ratings), 2.2, .7))))
)

rating_fit <- rating_validity(toy_ratings, scale_min = 1, scale_max = 5)
rating_fit
summary(rating_fit)
```

**Interpretation**
- **HTC** summarizes definitional correspondence with the intended construct.
- **HTD** summarizes distinctiveness from orbiting constructs.
- The repeated-measures ANOVA tests whether construct-definition ratings differ for an item.
- Planned paired contrasts ask the direct screening question: is the target rating significantly higher than every orbiting rating?
- Scale-level HTC/HTD averages can be interpreted using Colquitt et al. (2019) empirical norms when the judge population matches their intended use.

**Expert-panel workflow**
```{r}
expert_ratings <- matrix(
  c(4,4,4,4,4,4,
    4,4,4,3,4,4,
    4,3,4,4,3,4),
  nrow = 6,
  dimnames = list(NULL, paste0("Item", 1:3))
)
expert_fit <- expert_validity(expert_ratings, mode = "relevance", lo = 1, hi = 4)
expert_fit
summary(expert_fit)
```

Relevance, essentiality, and congruence are intentionally separate expert tasks.
Use `mode = "relevance"` for Aiken V + CVI/modified kappa, `mode =
"essentiality"` for Lawshe CVR, and `mode = "congruence"` for IOC.

**Bundled reproducible examples**

The package also installs deterministic CSV examples for the three workflow
families and all expert-panel modes. They are synthetic, contain no participant
data, and are regenerated from `data-raw/build-example-data.R` in the source
repository.

```{r bundled-data}
example_files <- c(
  "sort_example.csv",
  "rating_example.csv",
  "expert_relevance_example.csv",
  "expert_essentiality_example.csv",
  "expert_congruence_example.csv"
)
vapply(example_files, function(x) {
  system.file("extdata", x, package = "contentvalidR")
}, character(1))
```

See `vignette("reporting-examples", package = "contentvalidR")` for
manuscript-ready reporting scaffolds built from those same files.

**Classic indices**
```{r}
R <- matrix(sample(1:5, 5*6, replace = TRUE), nrow = 5)
aikens_v(R, lo = 1, hi = 5)

cvr(essential = c(8,10,5), N = 12)

M <- matrix(sample(0:1, 6*5, replace = TRUE, prob = c(.3,.7)), nrow = 6)
cvi(M)

ioc_df <- data.frame(
  item = rep(paste0("I",1:2), each = 9),
  judge = rep(1:3, times = 6),
  objective = rep(rep(LETTERS[1:3], each = 3), times = 2),
  score = sample(c(-1,0,1), 18, replace = TRUE)
)
ioc(ioc_df)
```

**Diagnostics & reproducibility**
```{r}
truth <- c(TRUE, TRUE, TRUE, FALSE)  # pretend "kept" after CFA
signal_detection(csv$decision == "significant", truth)

csv2_sig <- sample(c(TRUE, FALSE), nrow(csv), replace = TRUE)
reproducibility_phi(csv$decision == "significant", csv2_sig)
```

**Power quick-checks**
```{r}
sort_power(N = c(20, 30), true_p = c(.65, .75))
```