--- title: "Scoring the HiTOP-BR" output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Scoring the HiTOP-BR} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>" ) ``` ```{r} #| include: false library(tibble) ``` The HiTOP-BR instrument has 45 items and yields 8 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_hitopbr`. 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 45 columns numbered `hbr_01` to `hbr_45` containing each participant's rating on each item of the HiTOP-BR (on a numerical scale from 1 to 4). ```{r} data("ku_hitopbr") ku_hitopbr ``` ## Basic Scoring To turn these item-level ratings into mean scores on the 8 scales, we can use the `score_hitopbr()` 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 47 so we can use `items = 3:47`. I am going to also set `append = FALSE` so that you can quickly see the scale scores. ```{r} scores <- score_hitopbr( data = ku_hitopbr, items = 3:47, 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_hitopbr` tibble with the scale scores added to the end as extra columns. Notice below how we now have 55 columns instead of 47. ```{r} scores <- score_hitopbr( data = ku_hitopbr, items = 3:47 ) scores ``` ## Items as Strings Alternatively, we could provide the item column names as a character string. Typing out all 45 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 "hbr_%02d" format and apply that across the numbers 1 to 45, that will create the zero-padded column names we need. The same pattern names the items in the package's other example dataset (`sim_hitopbr`) and in data collected through its Qualtrics and REDCap exports, so this one expression selects the items in all of them. ```{r} scores <- score_hitopbr( data = ku_hitopbr, items = sprintf("hbr_%02d", 1:45), append = FALSE ) scores ``` ## Scale Prefixes Also note that each scale column has the prefix "hbr_" in its name. You can change the prefix (e.g., setting it to `"hitopbr_"`) or even turn it off (e.g., setting it to `""`) using the `prefix` argument. ```{r} scores <- score_hitopbr( data = ku_hitopbr, items = sprintf("hbr_%02d", 1:45), prefix = "", append = FALSE ) scores ``` ## 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_hitopbr()` 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. ## Confidence Intervals A scale score is measured with error, so it is worth reporting a range rather than a single number. `interval_hitopbr()` 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_hitopbr( data = ku_hitopbr, items = sprintf("hbr_%02d", 1:45), append = FALSE ) interval_hitopbr( data = scored, scores = c("hbr_detachment", "hbr_pFactor"), 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_hitopbr( data = scored, scores = "hbr_detachment", level = 0.80, append = FALSE ) ``` ### What the reference group is The mean, standard deviation and reliability behind every number above are shipped as `hitopbr_devstats`, transcribed from the Superspectra and Spectra block of Table 1 of the HiTOP-SR introduction paper. ```{r} hitopbr_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. Every HiTOP-BR scale is skewed enough for this to show: on all eight, a score at the response floor of 1 returns a lower bound 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. * The eight scales overlap. Externalizing and p-Factor are drawn from the same items as the six spectrum scales rather than added to them, so a respondent contributes the same answers to several of these intervals; read them as eight views of one response set rather than eight independent measurements. ## 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_hitopbr()` 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_hitopbr( data = ku_hitopbr, items = sprintf("hbr_%02d", 1:45) ) ``` ## Labelling Columns Column names like `hbr_01` and `hbr_antagonism` are compact but say nothing about what they hold. The `label_hitopbr()` 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, `"hbr_"`, is how both example datasets and the package's REDCap export name them (`hbr_01` to `hbr_45`), so `sim_hitopbr` needs no `prefix`; data collected through the package's Qualtrics export is named `HBR_01` to `HBR_45` and would pass `prefix = "HBR_"`. The number must be zero-padded to two digits: columns carrying the prefix and a number without the leading zero are not labelled, and the function warns and names them. ```{r label-items} data("sim_hitopbr") labelled_items <- label_hitopbr(sim_hitopbr, target = "items") attr(labelled_items$hbr_01, "label") ``` Set `target = "scales"` to label the output of `score_hitopbr()` instead. Here `prefix` is the one the scoring function put on its output columns. Both functions default to `"hbr_"`, so a scored frame built with default settings labels with none given: ```{r label-scales} sim_scores <- score_hitopbr(sim_hitopbr, items = 1:45, append = FALSE) labelled_scales <- label_hitopbr(sim_scores, target = "scales") attr(labelled_scales$hbr_antagonism, "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.