Score the HiTOP-SR Instrument — score

Create a data frame with scores on all the HiTOP-SR scales and, with include_subscales = TRUE, on its 17 subscales (fewer under a module).

Usage

score_hitopsr(
  data,
  items,
  srange = c(1, 4),
  prefix = "hsr_",
  missing = c("available", "complete"),
  calc_se = FALSE,
  append = TRUE,
  module = NULL,
  layout = c("instrument", "printed"),
  include_subscales = FALSE,
  subset = NULL
)

Arguments

data: A data frame containing the HiTOP-SR items (numerically coded): all 405 of them, or, when module is supplied, that module's items.
items: A vector of column names (as strings) or numbers (as integers) corresponding to the HiTOP-SR items held in data — all 405, or, when module is supplied, that module's items. Items must be supplied in instrument order, or in the form's printed order under layout = "printed"; a misordered mapping silently scores the wrong items, so a warning is issued when the names share a common prefix and trailing number but those numbers are not ascending. Under layout = "printed", names whose trailing numbers equal the module's item_order element by element are in the printed order and pass with no warning. Zero padding does not matter. Other names that are not ascending still warn. Duplicated entries are an error. When items is omitted or NULL, the names on the module's columns attribute are used, which read_module() returns from a descriptor that generate_redcap_hitopsr() or generate_qualtrics_hitopsr() wrote. A call with items omitted is an error if no module is supplied, if the module has no columns attribute, or under layout = "printed". A supplied items is always used, whether or not the module has the attribute. Each column must be numeric or logical, or character holding only numbers (blank cells and NA values count as missing, but the text "NA" is refused). A haven labelled column is read as its plain values. Any other column, such as the choice text of an online export or a factor, is an error of class hitop_nonnumeric_items. So is a 64-bit integer (integer64) column, and, in a UTF-8 session, a column holding text that is not valid UTF-8 (text marked Latin-1 is read as its text); convert such text with iconv(). So is an SPSS column (haven_labelled_spss) that holds a value it declares missing; turn those codes into NA with haven::zap_missing() first. A declared value that is blank is not refused, since blank cells count as missing. The SPSS class of haven before 2.0 (labelled_spss) is refused the same way, but haven::zap_missing() leaves it unchanged, so set the values its na_values or na_range attribute declares to NA first.
srange: An optional numeric vector specifying the minimum and maximum values of the HiTOP-SR items, used for reverse-coding. (default = c(1, 4))
prefix: An optional string to add before each scale column name. If no prefix is desired, set to an empty string "". (default = "hsr_")
missing: A string selecting how missing item responses are handled when computing scale scores. "available" (the default) averages whatever items are present (rowMeans(na.rm = TRUE)); "complete" returns NA for any scale with a missing item (rowMeans(na.rm = FALSE)). (default = "available")
calc_se: Deprecated. This argument, and the _se columns it adds, will be removed in a future release; a call with calc_se = TRUE warns; the warning is classed hitop_deprecated_calc_se, so a caller can silence it by name. Use interval_hitopsr() for an interval around a respondent's true score. What it does while it lasts: an optional logical indicating whether to calculate a standard error for each scale score: 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 a standard error of measurement — no reliability estimate enters it — so it does not give a confidence interval for a respondent's true score; for measurement precision see reliability_hitopsr(). (default = FALSE)
append: An optional logical indicating whether the new columns should be added to the end of the data input. (default = TRUE)
module: An optional hitop_module object, as returned by hitop_module(), describing a module of the instrument. When supplied, data and items hold only that module's item columns — in ascending instrument order, as the generate_*_hitopsr() forms lay them out — and only that module's scales are scored. When NULL, all 405 items are expected and all 76 scales are scored. A module whose items, nItems, camelCase or instrument differ from a fresh hitop_module() build of its scales, as after an edit by hand, or that cannot be rebuilt from its instrument and scales, is refused with an error of class hitop_module_mismatch. (default = NULL)
layout: The order the item columns are in. "instrument" (the default) is ascending HiTOP-SR order, as the generate_*_hitopsr() forms lay the items out. "printed" is the order a shuffled Word form printed them: column k holds the answer to the form's printed item k. It needs a module carrying an item_order attribute, the record a module descriptor written by generate_docx_hitopsr() with randomize = TRUE keeps and read_module() returns; the columns are put back into instrument order through that attribute before scoring. A call with layout = "printed" and no module, a module with no item_order, or an item_order that is not a permutation of the module's items is an error. (default = "instrument")
include_subscales: A logical. If TRUE, the 17 subscales in hitopsr_subscales are also scored, each as the mean of its items under the missing rule. Their columns are named prefix plus the subscale's camelCase name (for example hsr_cynicism) and follow the scale columns, in the row order of hitopsr_subscales. Under calc_se = TRUE, their _se columns follow the scale _se columns in the same order. With a module, only the subscales whose parent scale is in the module are scored. (default = FALSE)
subset: Deprecated. The former name of module; supplying it warns. Supplying both module and subset is an error. (default = NULL)

Value

A tibble containing all scale scores, subscale scores (if requested with include_subscales), standard errors (if requested) and all original data columns (if requested).

Details

For per-scale reliability estimates (Cronbach's alpha, McDonald's omega), use reliability_hitopsr().

Errors. With append = TRUE, a column of data whose name this call would also produce is an error rather than an overwrite or a duplicated column: the message names every colliding column. Re-run with append = FALSE to return only the new columns, or drop the colliding columns from data first. The condition is classed hitop_append_collision, so a caller can catch this refusal by name.

An item column that cannot be read as numbers (see items) is an error of class hitop_nonnumeric_items, raised before the collision check.

Examples

# Score all HiTOP-SR scales from the simulated data
score_hitopsr(sim_hitopsr, items = 1:405, append = FALSE)
#> # A tibble: 100 × 76
#>    hsr_agoraphobia hsr_antisocialBehavior hsr_appearanceFocus hsr_appetiteLoss
#>              <dbl>                  <dbl>               <dbl>            <dbl>
#>  1             2.8                   2.75                 2.8             2.67
#>  2             2.6                   2.75                 2.8             3   
#>  3             2.4                   2.75                 2.4             2.67
#>  4             2.4                   2.38                 3.4             2   
#>  5             2.6                   2.5                  1.8             2   
#>  6             2.4                   3.12                 2.2             2.67
#>  7             2.6                   2.38                 2.4             2.33
#>  8             3                     2.38                 3.2             2.67
#>  9             2.4                   2.38                 2.2             1.67
#> 10             2.4                   2                    3               2.33
#> # ℹ 90 more rows
#> # ℹ 72 more variables: hsr_bingeEating <dbl>, hsr_bodilyDistress <dbl>,
#> #   hsr_bodyDissatisfaction <dbl>, hsr_callousness <dbl>, hsr_checking <dbl>,
#> #   hsr_cleaning <dbl>, hsr_cognitiveProblems <dbl>,
#> #   hsr_conversionSymptoms <dbl>, hsr_counting <dbl>,
#> #   hsr_dietaryRestraint <dbl>, hsr_difficultiesReachingOrgasm <dbl>,
#> #   hsr_diseaseConviction <dbl>, hsr_dishonesty <dbl>, …

# Score the 17 subscales too; their columns follow the 76 scale columns
score_hitopsr(sim_hitopsr, items = 1:405, include_subscales = TRUE,
              append = FALSE)
#> # A tibble: 100 × 93
#>    hsr_agoraphobia hsr_antisocialBehavior hsr_appearanceFocus hsr_appetiteLoss
#>              <dbl>                  <dbl>               <dbl>            <dbl>
#>  1             2.8                   2.75                 2.8             2.67
#>  2             2.6                   2.75                 2.8             3   
#>  3             2.4                   2.75                 2.4             2.67
#>  4             2.4                   2.38                 3.4             2   
#>  5             2.6                   2.5                  1.8             2   
#>  6             2.4                   3.12                 2.2             2.67
#>  7             2.6                   2.38                 2.4             2.33
#>  8             3                     2.38                 3.2             2.67
#>  9             2.4                   2.38                 2.2             1.67
#> 10             2.4                   2                    3               2.33
#> # ℹ 90 more rows
#> # ℹ 89 more variables: hsr_bingeEating <dbl>, hsr_bodilyDistress <dbl>,
#> #   hsr_bodyDissatisfaction <dbl>, hsr_callousness <dbl>, hsr_checking <dbl>,
#> #   hsr_cleaning <dbl>, hsr_cognitiveProblems <dbl>,
#> #   hsr_conversionSymptoms <dbl>, hsr_counting <dbl>,
#> #   hsr_dietaryRestraint <dbl>, hsr_difficultiesReachingOrgasm <dbl>,
#> #   hsr_diseaseConviction <dbl>, hsr_dishonesty <dbl>, …

# Score data collected with a two-scale module. Select the item columns
# by name: `m$items` holds original HiTOP-SR numbers, which are column
# positions only in a data frame that is exactly the 405 items in order.
m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss"))
collected <- sim_hitopsr[sprintf("hsr_%03d", m$items)]
score_hitopsr(collected, items = names(collected), module = m, append = FALSE)
#> # A tibble: 100 × 2
#>    hsr_agoraphobia hsr_appetiteLoss
#>              <dbl>            <dbl>
#>  1             2.8             2.67
#>  2             2.6             3   
#>  3             2.4             2.67
#>  4             2.4             2   
#>  5             2.6             2   
#>  6             2.4             2.67
#>  7             2.6             2.33
#>  8             3               2.67
#>  9             2.4             1.67
#> 10             2.4             2.33
#> # ℹ 90 more rows

# Score data entered off a shuffled form: the columns are in the order the
# form printed its items, recorded on the module's `item_order` attribute
# (here set by hand; a descriptor written with `randomize = TRUE` carries it).
attr(m, "item_order") <- c(144L, 202L, 66L, 389L, 260L, 109L, 291L, 118L)
printed <- collected[match(attr(m, "item_order"), m$items)]
score_hitopsr(printed, items = seq_along(printed), module = m,
              layout = "printed", append = FALSE)
#> # A tibble: 100 × 2
#>    hsr_agoraphobia hsr_appetiteLoss
#>              <dbl>            <dbl>
#>  1             2.8             2.67
#>  2             2.6             3   
#>  3             2.4             2.67
#>  4             2.4             2   
#>  5             2.6             2   
#>  6             2.4             2.67
#>  7             2.6             2.33
#>  8             3               2.67
#>  9             2.4             1.67
#> 10             2.4             2.33
#> # ℹ 90 more rows