--- title: "Scoring the HiTOP-SR" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Scoring the HiTOP-SR} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r} #| include: false library(tibble) ``` The HiTOP-SR instrument has 405 items and yields 76 scale scores. To demonstrate the ability of the package to calculate these scale scores, we can use real example data (n=411) that was collected at the University of Kansas (KU) by Girard & Gray in 2024--2025. This data is stored in the package under the name `ku_hitopsr`. First, we load the package into memory using the `library()` function. If this doesn't work, make sure you installed the package properly (see the README on [GitHub](https://github.com/jmgirard/hitop)). ```{r} library(hitop) ``` Next, we can load the example dataset from the package using the `data()` function. It is a large tibble that contains a `participant` column with a unique identifier for each participant, a `biosex` column indicating whether each participant is "female" or "male", and then 405 columns numbered `hsr_001` to `hsr_405` containing each participant's rating on each item of the HiTOP-SR (on a numerical scale from 1 to 4). ```{r} data("ku_hitopsr") ku_hitopsr ``` ## Basic Scoring To turn these item-level ratings into mean scores on the 76 scales, we can use the `score_hitopsr()` function. It needs to know what object contains the data and which columns contain the item-level data. There are several ways we can specify the items. First, we can provide the column numbers and use the `:` shortcut. In this tibble, the items are from column 3 to column 407 so we can use `items = 3:407`. I am going to also set `append = FALSE` so that you can quickly see the scale scores. ```{r} scores <- score_hitopsr( data = ku_hitopsr, items = 3:407, append = FALSE ) scores ``` ## Appending If I had instead set `append = TRUE` (or left it off, as that is the default), we would get back the `ku_hitopsr` tibble with the scale scores added to the end as extra columns. Notice below how we now have 483 columns instead of 407. ```{r} scores <- score_hitopsr( data = ku_hitopsr, items = 3:407 ) scores ``` ## Items as Strings Alternatively, we could provide the item column names as a character string. Typing out all 405 item names would be a hassle, but luckily this dataset named them consistently so we can build the names automatically using `sprintf()`. If we use the "hsr_%03d" format and apply that across the numbers 1 to 405, that will create the zero-padded column names we need. The same pattern names the items in the package's other example dataset (`sim_hitopsr`) and in data collected through its Qualtrics and REDCap exports, so this one expression selects the items in all of them. ```{r} scores <- score_hitopsr( data = ku_hitopsr, items = sprintf("hsr_%03d", 1:405), append = FALSE ) scores ``` ## Scale Prefixes Also note that each scale column has the prefix "hsr_" in its name. You can change the prefix (e.g., setting it to `"hitop_"`) or even turn it off (e.g., setting it to `""`) using the `prefix` argument. ```{r} scores <- score_hitopsr( data = ku_hitopsr, items = sprintf("hsr_%03d", 1:405), prefix = "hitop_", append = FALSE ) scores ``` ## Subscales Six HiTOP-SR scales have subscales, 17 in all, which the `hitopsr_subscales` table lists. Set `include_subscales = TRUE` to score them too. Each subscale column is named for the subscale, such as `hsr_cynicism`, and the subscale columns come after the 76 scale columns. ```{r} scores <- score_hitopsr( data = ku_hitopsr, items = sprintf("hsr_%03d", 1:405), include_subscales = TRUE, append = FALSE ) scores[paste0("hsr_", hitopsr_subscales$camelCase)] ``` `reliability_hitopsr()` takes the same argument and then adds one row per subscale after the scale rows. ## Simple Standard Errors (deprecated) The `calc_se` argument is **deprecated**. It, and the `_se` columns it adds, will be removed in a future release, and a call that passes `calc_se = TRUE` now warns. Use `interval_hitopsr()` instead, shown under [Confidence Intervals](#confidence-intervals) below. What the argument computes, while it lasts: the SD of the items the respondent actually answered divided by the square root of how many of those items they answered. Each one summarizes how much a respondent's answers varied within a scale; it is not an estimate of how precisely the scale measures the underlying trait, so it does not give a confidence interval for a respondent's true score. That is what replaces it: an interval, from the reliability of the scale rather than from one respondent's spread of answers. ## Scale Reliability As we compute scale scores, we can also estimate their inter-item reliability using Cronbach's α (alpha) or McDonald's ω (omega total). α is fast and widely used, but it assumes tau-equivalence (all items load equally on a single factor); violations can make α under- or over-estimate reliability. ω is based on a congeneric single-factor model, allowing items to have different loadings and error variances; it typically provides a more accurate reliability estimate for unit-weighted sums. Both assume the scale is essentially unidimensional; α and ω coincide when tau-equivalence holds. We estimate reliability with the `reliability_hitopsr()` function, which returns a tibble with one row per scale: its printed name (`Scale`), the stem that names its column in the scored output (`camelCase`), the number of items (`nItems`), and the requested coefficients. By default it computes both `alpha` and `omega`; for the latter, we will need the **lavaan** package installed (set `omega = FALSE` to skip it). ```{r reliability} #| warning: false reliability_hitopsr( data = ku_hitopsr, items = sprintf("hsr_%03d", 1:405) ) ``` ## Confidence Intervals A scale score is measured with error, so it is worth reporting a range rather than a single number. `interval_hitopsr()` returns three columns per scale: `_est`, an estimate of the respondent's true score, and `_lo` and `_hi`, the bounds of a confidence interval around it. ```{r} scored <- score_hitopsr( data = ku_hitopsr, items = sprintf("hsr_%03d", 1:405), append = FALSE ) interval_hitopsr( data = scored, scores = c("hsr_agoraphobia", "hsr_wellBeing"), append = FALSE ) ``` The estimate is not the observed score. It is the observed score pulled toward the reference group's mean, because with imperfect measurement a true score tends to lie nearer the mean than the observed score does -- the less reliable the scale, the further it is pulled. The method is the regression approach with scale correction from Schmukle (2026), which puts the estimate back on the same metric as the observed score so the two can be read against each other. The width comes from the scale's reliability and the reference group's standard deviation, so it is the same for every respondent on a given scale and it narrows as reliability rises. Widen or narrow the interval with `level`: ```{r} interval_hitopsr( data = scored, scores = "hsr_agoraphobia", level = 0.80, append = FALSE ) ``` ### What the reference group is The mean, standard deviation and reliability behind every number above are shipped as `hitopsr_devstats`, transcribed from Table 1 of the HiTOP-SR introduction paper. ```{r} hitopsr_devstats ``` **That reference group is the paper's Development Sample 2, N = 780 Prolific Academic participants stratified by sex and age to approximate a community-representative United States population. It is a development sample, and not a community norm.** No census weighting was applied and the paper publishes no raw-score to T-score table. So an interval here says where a score sits relative to the sample the instrument was developed on; it does not say what percentile that score occupies in any population. Three further limits are worth knowing before you report one of these intervals. * The interval is symmetric and the same width for every respondent on a scale, which is what classical test theory implies, and it is **not** clipped to the 1-4 response range. On a strongly skewed scale -- Conversion Symptoms, say, whose mean is 1.12 -- a bound can therefore fall below 1. * The coverage the method demonstrates is across a population of respondents: about `level` of the intervals contain the true score when respondents are drawn from the reference distribution. It is not a guarantee for any one respondent. * A scale scored from fewer than its full items -- from a module form, or from data scored with `missing = "available"` -- is not on the same footing as the reference statistics, which come from complete scales. `interval_hitopsr()` receives scores rather than items, so it cannot tell such a column from a fully scored one; treat the interval as not comparable. ## Scoring Only Some Scales Not every study administers all 405 items. The package can build, field, and score a chosen set of the instrument's scales; that whole workflow has its own walkthrough in [Building HiTOP-SR Modules](https://jmgirard.github.io/hitop/articles/modules-hitopsr.html). ## Renaming Item Columns If your dataset was collected before the item numbers were standardized or used arbitrary variable names, you must rename your columns to the standard format before running the scoring engine. The `rename_hitopsr_items()` function handles this preparation via two approaches. ### Method 1: Legacy "Original" Pool Names If your columns are labeled with older pool names (e.g., HiTOP_659 or Ext_432), use `method = "original"`. The function scans your data frame columns, matches them against the package's built-in item database, and renames them to standard names. ```{r} # Setup a mock dataset with older legacy column names legacy_data <- data.frame( HiTOP_659 = c(1, 2, 4), HiTOP_301 = c(3, 4, 2), ParticipantID = c(101, 102, 103) ) # Rename legacy columns using the native pipe standardized_legacy <- legacy_data |> rename_hitopsr_items(method = "original", prefix = "HSR_") standardized_legacy ``` ### Method 2: Matching via Literal Item Text If your dataset uses completely customized column names but you tracked the exact question prompts presented to your participants, use `method = "text"`. Provide a vector of your current column names alongside a matching vector of literal item text strings. ```{r} # Setup a mock dataset with completely custom column names custom_data <- data.frame( q_party = c(1, 2, 1), q_flawless = c(4, 3, 4), Age = c(21, 25, 30) ) # Define the mapping pairs my_cols <- c("q_party", "q_flawless") my_texts <- c( "I preferred to stay home than to go to a party.", "I felt that my work must be flawless." ) # Rename custom columns based on text matching standardized_custom <- custom_data |> rename_hitopsr_items( method = "text", item_cols = my_cols, item_text = my_texts, prefix = "HSR_" ) standardized_custom ``` *Note: Because these small mock examples contain only some of the full item pool, `rename_hitopsr_items()` will safely issue a cli warning letting you know that fewer than 405 items were matched. This perfectly accommodates researchers who intentionally administer only part of the instrument.* ## Labelling Columns Column names like `hsr_001` and `hsr_agoraphobia` are compact but say nothing about what they hold. The `label_hitopsr()` function attaches a `label` attribute to each column it recognizes: the literal item text for item columns, and the printed scale name for scored columns. Tools that read that attribute — data viewers and reporting packages — can then show the wording instead of the column name, so the labels travel with the data rather than living in a separate lookup table. Which columns it recognizes depends on `prefix`, which must match how your item columns are actually named. The default, `"hsr_"`, is how both example datasets and the package's REDCap export name them (`hsr_001` to `hsr_405`), so `sim_hitopsr` needs no `prefix`; data collected through the package's Qualtrics export is named `HSR_001` to `HSR_405` and would pass `prefix = "HSR_"`. The number must be zero-padded to three digits: columns carrying the prefix and a number without the leading zeros are not labelled, and the function warns and names them. ```{r label-items} data("sim_hitopsr") labelled_items <- label_hitopsr(sim_hitopsr, target = "items") attr(labelled_items$hsr_001, "label") ``` Set `target = "scales"` to label the output of `score_hitopsr()` instead. Here `prefix` is the one the scoring function put on its output columns. Both functions default to `"hsr_"`, so a scored frame built with default settings labels with none given: ```{r label-scales} sim_scores <- score_hitopsr(sim_hitopsr, items = 1:405, append = FALSE) labelled_scales <- label_hitopsr(sim_scores, target = "scales") attr(labelled_scales$hsr_agoraphobia, "label") ``` Columns the function does not recognize are returned untouched, and if no column matches the prefix at all it says so with a warning rather than silently returning the data unchanged.