---
title: "Scale reliability and validity"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Scale reliability and validity}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

This vignette focuses on measurement-quality checks. The examples use the
tourism-services demo because it has coherent Likert constructs.

```{r load}
demo <- sframe_demo_data()
instr <- demo$instrument
responses <- demo$responses
```

## Construct-to-item mapping

Scale definitions are stored in the instrument. They define which items form
each construct and how scores should be computed.

```{r scales}
lapply(instr$scales, function(scale) {
  list(
    id = scale$id,
    label = scale$label,
    items = scale$items,
    method = scale$method,
    min_valid = scale$min_valid,
    reverse_items = scale$reverse_items
  )
})
```

## Reverse coding and minimum valid item rules

`score_scales()` applies reverse coding and minimum valid item rules before
returning scale scores.

```{r scoring}
scored <- score_scales(
  responses,
  instr,
  keep_items = TRUE,
  keep_meta = TRUE
)

scale_ids <- vapply(instr$scales, function(scale) scale$id, character(1))
head(scored[, intersect(scale_ids, names(scored)), drop = FALSE])
```

## Reliability

Cronbach's alpha and omega use the optional `psych` package. Interpret these
statistics together with item wording, dimensionality, and study design.

```{r reliability, eval = requireNamespace("psych", quietly = TRUE)}
alpha_only <- reliability_report(
  responses,
  instr,
  omega = FALSE
)

alpha_only
```

```{r omega, eval = requireNamespace("psych", quietly = TRUE)}
omega_report <- reliability_report(
  responses,
  instr,
  alpha = FALSE,
  omega = TRUE
)

omega_report
```

## Item diagnostics

Item diagnostics help identify sparse items, poor item-total relationships,
and floor or ceiling issues.

```{r item-report}
items <- item_report(responses, instr)

names(items)
items[[1]]
```

## EFA readiness

`efa_report()` is a screening step. Interpret it alongside item wording,
sample size, theory, and the study context.

```{r efa, eval = requireNamespace("psych", quietly = TRUE)}
efa_report(responses, instr)
```

## Validity summary from supplied loadings

When standardised loadings are available from a CFA or PLS-SEM workflow, they
can be summarised with `validity_report()`.

```{r validity}
loadings <- list(
  digital_marketing = c(dm_1 = .72, dm_2 = .78, dm_3 = .81),
  service_quality = c(sq_1 = .75, sq_2 = .80, sq_3 = .77),
  satisfaction = c(sat_1 = .76, sat_2 = .82)
)

validity <- validity_report(loadings)

validity
```

## Cautious interpretation

Reliability and validity summaries are diagnostics, not automatic decisions.
They should be interpreted with the questionnaire wording, sampling context,
construct definitions, and planned statistical model.