Skip to contents

Score the HiTOP-BR Instrument

Source: R/score_hitopbr.R
score_hitopbr.Rd

Create a data frame with scores on all the HiTOP-BR scales.

Usage

score_hitopbr(
  data,
  items,
  srange = c(1, 4),
  prefix = "hbr_",
  missing = c("available", "complete"),
  calc_se = FALSE,
  append = TRUE
)

Arguments

data

A data frame containing all HiTOP-BR items (numerically coded).

items

A vector of column names (as strings) or numbers (as integers) corresponding to the 45 HiTOP-BR items in order. Items must be supplied in instrument order; 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. Duplicated entries are an error. 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-BR 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 = "hbr_")

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_hitopbr() 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_hitopbr(). (default = FALSE)

append

An optional logical indicating whether the new columns should be added to the end of the data input. (default = TRUE)

Value

A tibble containing all scale scores and 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_hitopbr().

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-BR scales from the simulated data
score_hitopbr(sim_hitopbr, items = 1:45, append = FALSE)
#> # A tibble: 100 × 8
#>    hbr_antagonism hbr_detachment hbr_disinhibition hbr_internalizing
#>             <dbl>          <dbl>             <dbl>             <dbl>
#>  1           2.56            2.8              1.67              2.12
#>  2           2.11            1.6              2.67              2.5 
#>  3           2.44            2.8              2.22              2.38
#>  4           2.67            2.6              2.22              2.12
#>  5           2.78            2.2              2.78              2   
#>  6           2               2.4              3.22              2.88
#>  7           2.44            2.4              3.11              2.12
#>  8           2.78            2.4              2.33              2.25
#>  9           1.89            2.6              2.67              2.5 
#> 10           2.89            2.2              2.78              2.5 
#> # ℹ 90 more rows
#> # ℹ 4 more variables: hbr_somatoform <dbl>, hbr_thoughtDisorder <dbl>,
#> #   hbr_externalizing <dbl>, hbr_pFactor <dbl>