| Title: | Score and Distribute HiTOP Society Questionnaire Instruments |
|---|---|
| Description: | Provides item data, scoring, validity screening, and reliability estimation for the questionnaire instruments distributed by the Hierarchical Taxonomy of Psychopathology (HiTOP) Society, including the Personality Inventory for DSM-5 (PID-5) and its short and brief forms, the HiTOP Self-Report and Brief-Report measures, and the HiTOP Harmful Substance Use Measure. Scoring follows published scoring keys and is verified against primary sources. The package also generates ready-to-administer paper forms and 'Qualtrics' and 'REDCap' import files for each instrument. |
| Authors: | Jeffrey Girard [aut, cre] (ORCID: <https://orcid.org/0000-0002-7359-3746>) |
| Maintainer: | Jeffrey Girard <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.2.0 |
| Built: | 2026-10-17 14:00:59 UTC |
| Source: | https://github.com/jmgirard/hitop |
Returns the scales available for building a module, with the
name to print on a form, the camelCase stem that names the scored output
column, how many items the scale contributes, and the scale's brief
clinician-facing definition. Either name column may be passed to
hitop_module().
This is a convenience view of the instrument's own scale table, so a researcher choosing scales need not know which dataset to open.
available_scales(instrument = "hitopsr")available_scales(instrument = "hitopsr")
instrument |
A string naming the instrument. Currently only |
A scale whose definition is missing from the instrument's
definitions table is an error, never a blank cell: the abort carries the
condition class hitop_missing_definition, which a caller may catch. It is
not reachable from the shipped tables, which are built under a check that
the two tables carry the same stems.
A tibble with one row per scale and four columns: Scale (the
display name), camelCase (the scored-output stem), nItems (integer), and Brief
(the clinician-facing definition, as hitopsr_definitions carries it).
hitop_module(), which takes these names;
hitopsr_definitions, which carries the definitions in full.
# Every HiTOP-SR scale, with its item count available_scales("hitopsr") # Pick a few and build a module from them hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss"))# Every HiTOP-SR scale, with its item count available_scales("hitopsr") # Pick a few and build a module from them hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss"))
Computes Cronbach's coefficient alpha for a set of items from the unstandardized covariance matrix. Items are coerced to numeric before calculation. Missing data can be handled via pairwise deletion.
calc_alpha(df)calc_alpha(df)
df |
A data frame or matrix with one row per observation and one column per item. |
Let be the number of items and let
denote the item scores. Define the total score .
Cronbach's alpha can be written without matrix notation as
In words: take the sum of the
item variances and divide by the variance of the total score; subtract this
ratio from 1 and multiply by .
Both and are computed using
pairwise-complete observations. @section Coercion: Each column is coerced via
as.numeric(). This means:
factors are converted to integer level codes (not labels);
characters that are not parsable as numbers become NA;
dates/times become their underlying numeric representations. Ensure your columns are truly numeric item responses or pre-process as needed.
A numeric scalar giving Cronbach's alpha (typically in [0, 1], but can be outside this range for problematic data).
Cronbach, L. J. (1951). Coefficient alpha and the internal structure of tests. Psychometrika, 16(3), 297–334.
Sijtsma, K. (2009). On the use, the misuse, and the very limited usefulness of Cronbach's alpha. Psychometrika, 74(1), 107–120.
# Cronbach's alpha for the HiTOP-BR Detachment scale (items 7, 12, 30, 31, 37) detach_items <- sprintf("hbr_%02d", c(7, 12, 30, 31, 37)) calc_alpha(ku_hitopbr[detach_items])# Cronbach's alpha for the HiTOP-BR Detachment scale (items 7, 12, 30, 31, 37) detach_items <- sprintf("hbr_%02d", c(7, 12, 30, 31, 37)) calc_alpha(ku_hitopbr[detach_items])
Computes McDonald's for a unidimensional scale
using a one-factor confirmatory factor analysis (CFA) fit with lavaan
using MLR estimation. Missing data can be handled via full information
maximum likelihood (FIML).
calc_omega(df)calc_omega(df)
df |
A data frame or matrix with one row per observation and one column per item. |
The model is f =~ item1 + item2 + ... + itemK with std.lv = TRUE
(i.e., ).
, where are unstandardized loadings and
are unstandardized residual variances of the indicators.
The function validates inputs and fails with informative messages if the CFA does not converge or if implied residual variances are invalid. Mixed-sign loadings trigger a warning (often indicates reverse-keying is needed).
Note that the latent variable will be estimated as f, so please avoid
naming any of your items that.
A numeric scalar giving McDonald;s
(typically in [0, 1]; small estimation anomalies can yield values
slightly outside this range).
McDonald, R. P. (1999). Test Theory: A Unified Treatment. Lawrence Erlbaum.
Green, S. B., & Yang, Y. (2009). Reliability of summed item scores using structural equation modeling: An alternative to coefficient alpha. Psychometrika, 74(1), 155–167.
Zinbarg, R. E., Revelle, W., Yovel, I., & Li, W. (2005). Cronbach's α, Revelle's β, and McDonald's ωH. Psychometrika, 70(1), 123–133.
# McDonald's omega-total for the HiTOP-BR Detachment scale detach_items <- sprintf("hbr_%02d", c(7, 12, 30, 31, 37)) calc_omega(ku_hitopbr[detach_items])# McDonald's omega-total for the HiTOP-BR Detachment scale detach_items <- sprintf("hbr_%02d", c(7, 12, 30, 31, 37)) calc_omega(ku_hitopbr[detach_items])
Creates a formatted Microsoft Word document containing the Hierarchical Taxonomy of Psychopathology - Brief Report (HiTOP-BR) items, instructions, and optional scoring keys.
generate_docx_hitopbr( file = "hitopbr.docx", papersize = c("us", "a4"), title = "HiTOP-BR (v1.0)", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )generate_docx_hitopbr( file = "hitopbr.docx", papersize = c("us", "a4"), title = "HiTOP-BR (v1.0)", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. Defaults to
|
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. Defaults to
|
include_scoring |
Logical. If |
font_size |
Numeric value specifying the base font size in points.
Defaults to |
font_family |
Character string specifying the font family to be used.
Defaults to |
Invisibly returns the path to the created file (file).
# Write a HiTOP-BR paper form to a temporary Word document generate_docx_hitopbr(file = tempfile(fileext = ".docx"))# Write a HiTOP-BR paper form to a temporary Word document generate_docx_hitopbr(file = tempfile(fileext = ".docx"))
Write the 382 items of the HiTOP Digital Assessment and Tracker (HiTOP-DAT)
battery as a paper form. The items are numbered 1 to 382 in battery order
(hitopdat_items$Item), through its seven measures: the WHODAS, IDAS-II,
AUDIT, DUDIT, CAPE, CAT-PD and PHQ-15. Each measure's instruction text
comes before its first item; the CAPE has none. Each item shows the values
of its own answer set (hitopdat_choices), and the legend above each run
of items that share an answer set gives that set's values and labels. The
footer credits each measure's authors. The form has no scoring page,
because the package ships no HiTOP-DAT scoring key.
generate_docx_hitopdat( file = "hitopdat.docx", papersize = c("us", "a4"), title = "HiTOP-DAT", font_size = 10, font_family = "Times New Roman" )generate_docx_hitopdat( file = "hitopdat.docx", papersize = c("us", "a4"), title = "HiTOP-DAT", font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. Defaults to
|
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. Defaults to
|
font_size |
Numeric value greater than 0 specifying the base font size
in points. Defaults to |
font_family |
Character string specifying the font family to be used.
Defaults to |
Invisibly returns the path to the created file (file).
hitopdat_items, hitopdat_choices,
generate_qualtrics_hitopdat() for the Qualtrics import file, and
generate_redcap_hitopdat() for the REDCap import file.
# Write a HiTOP-DAT paper form to a temporary Word document generate_docx_hitopdat(file = tempfile(fileext = ".docx"))# Write a HiTOP-DAT paper form to a temporary Word document generate_docx_hitopdat(file = tempfile(fileext = ".docx"))
Creates a formatted Microsoft Word document containing the Hierarchical Taxonomy of Psychopathology - Substance Use Module (HSUM) overview, branching logic, and items.
generate_docx_hitophsum( file = "hitophsum_overview.docx", papersize = c("us", "a4"), title = "HiTOP-HSUM (v1.0) Overview", font_size = 10, font_family = "Times New Roman" )generate_docx_hitophsum( file = "hitophsum_overview.docx", papersize = c("us", "a4"), title = "HiTOP-HSUM (v1.0) Overview", font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. Defaults to
|
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. Defaults to
|
font_size |
Numeric value specifying the base font size in points.
Defaults to |
font_family |
Character string specifying the font family to be used.
Defaults to |
Invisibly returns the path to the created file (file).
# Write a HiTOP-HSUM paper form to a temporary Word document generate_docx_hitophsum(file = tempfile(fileext = ".docx"))# Write a HiTOP-HSUM paper form to a temporary Word document generate_docx_hitophsum(file = tempfile(fileext = ".docx"))
Creates a formatted Microsoft Word document containing the Hierarchical Taxonomy of Psychopathology - Self-Report (HiTOP-SR) items, instructions, and optional scoring keys. The 405 items are formatted into a single continuous table.
generate_docx_hitopsr( file = "hitopsr.docx", papersize = c("us", "a4"), title = NULL, include_scoring = TRUE, include_subscales = FALSE, font_size = 10, font_family = "Times New Roman", module = NULL, renumber = TRUE, randomize = FALSE, descriptor = NULL, subset = NULL )generate_docx_hitopsr( file = "hitopsr.docx", papersize = c("us", "a4"), title = NULL, include_scoring = TRUE, include_subscales = FALSE, font_size = 10, font_family = "Times New Roman", module = NULL, renumber = TRUE, randomize = FALSE, descriptor = NULL, subset = NULL )
file |
Character string specifying the output file path. Defaults to
|
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title, printed
verbatim. The default ( |
include_scoring |
Logical. If |
include_subscales |
Logical. If |
font_size |
Numeric value specifying the base font size in points.
Defaults to |
font_family |
Character string specifying the font family to be used.
Defaults to |
module |
An optional |
renumber |
Logical. If |
randomize |
Logical. If Scoring data collected on a shuffled form. By default |
descriptor |
An optional path to write a module descriptor to, beside
the Word file. The saved file records which scales the form covers and
which instrument items they draw on, so |
subset |
Deprecated. The former name of |
Invisibly returns the path to the created file (file), carrying an
item_order attribute: the original HiTOP-SR item numbers in the order
they were printed. It is present on every call, and is simply ascending
unless randomize = TRUE.
write_module() and read_module() for the descriptor file.
# Write a HiTOP-SR paper form to a temporary Word document generate_docx_hitopsr(file = tempfile(fileext = ".docx")) # A module containing only two scales, printed as items 1 to 8 generate_docx_hitopsr( file = tempfile(fileext = ".docx"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")) ) # The same module keeping the full instrument's own item numbers generate_docx_hitopsr( file = tempfile(fileext = ".docx"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")), renumber = FALSE ) # A shuffled form; the scoring page carries the crosswalk back set.seed(1) out <- generate_docx_hitopsr( file = tempfile(fileext = ".docx"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")), randomize = TRUE ) attr(out, "item_order") # The same form with a descriptor saved beside it; the descriptor carries # the printed order, so the collected columns can be put back in order # without keeping a note by hand f <- tempfile(fileext = ".json") generate_docx_hitopsr( file = tempfile(fileext = ".docx"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")), randomize = TRUE, descriptor = f ) attr(read_module(f), "item_order")# Write a HiTOP-SR paper form to a temporary Word document generate_docx_hitopsr(file = tempfile(fileext = ".docx")) # A module containing only two scales, printed as items 1 to 8 generate_docx_hitopsr( file = tempfile(fileext = ".docx"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")) ) # The same module keeping the full instrument's own item numbers generate_docx_hitopsr( file = tempfile(fileext = ".docx"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")), renumber = FALSE ) # A shuffled form; the scoring page carries the crosswalk back set.seed(1) out <- generate_docx_hitopsr( file = tempfile(fileext = ".docx"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")), randomize = TRUE ) attr(out, "item_order") # The same form with a descriptor saved beside it; the descriptor carries # the printed order, so the collected columns can be put back in order # without keeping a note by hand f <- tempfile(fileext = ".json") generate_docx_hitopsr( file = tempfile(fileext = ".docx"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")), randomize = TRUE, descriptor = f ) attr(read_module(f), "item_order")
Generate a Word Document for the PID-5 (Full)
generate_docx_pid5( file = "pid5.docx", papersize = c("us", "a4"), title = "PID-5 (Full)", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )generate_docx_pid5( file = "pid5.docx", papersize = c("us", "a4"), title = "PID-5 (Full)", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. |
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. |
include_scoring |
Logical. If |
font_size |
Numeric value specifying the base font size in points. |
font_family |
Character string specifying the font family to be used. |
# Write a PID-5 (full) paper form to a temporary Word document generate_docx_pid5(file = tempfile(fileext = ".docx"))# Write a PID-5 (full) paper form to a temporary Word document generate_docx_pid5(file = tempfile(fileext = ".docx"))
Generate a Word Document for the PID-5-BF
generate_docx_pid5bf( file = "pid5bf.docx", papersize = c("us", "a4"), title = "PID-5-BF", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )generate_docx_pid5bf( file = "pid5bf.docx", papersize = c("us", "a4"), title = "PID-5-BF", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. |
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. |
include_scoring |
Logical. If |
font_size |
Numeric value specifying the base font size in points. |
font_family |
Character string specifying the font family to be used. |
# Write a PID-5-BF paper form to a temporary Word document generate_docx_pid5bf(file = tempfile(fileext = ".docx"))# Write a PID-5-BF paper form to a temporary Word document generate_docx_pid5bf(file = tempfile(fileext = ".docx"))
Write the 25-item PID-5-BF child form for ages 11 to 17 (Krueger et al.,
2013) as a paper form. Its items, their order and their keying are those
of the adult brief form, so the items are pid_items$Text numbered 1 to
25 and the scoring page is the one generate_docx_pid5bf() prints. The
instructions are the child form's, and the footer carries the APA
copyright and permission notice the child form prints. Score the
responses with score_pid5(version = "BF").
generate_docx_pid5bfchild( file = "pid5bfchild.docx", papersize = c("us", "a4"), title = "PID-5-BF, Child Age 11–17", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )generate_docx_pid5bfchild( file = "pid5bfchild.docx", papersize = c("us", "a4"), title = "PID-5-BF, Child Age 11–17", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. |
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. |
include_scoring |
Logical. If |
font_size |
Numeric value specifying the base font size in points. |
font_family |
Character string specifying the font family to be used. |
Krueger, R. F., Derringer, J., Markon, K. E., Watson, D., & Skodol, A. E. (2013). The Personality Inventory for DSM-5—Brief Form (PID-5-BF)—Child Age 11–17. American Psychiatric Association.
# Write a PID-5-BF child form to a temporary Word document generate_docx_pid5bfchild(file = tempfile(fileext = ".docx"))# Write a PID-5-BF child form to a temporary Word document generate_docx_pid5bfchild(file = tempfile(fileext = ".docx"))
Write the 36-item modified brief form of the PID-5 (PID5BF+M; Bach et al.,
2020) as a paper form. The items are numbered 1 to 36 in BF+M order, with
their PID-5 text, and the instructions and response options are those of
the other PID-5 forms. The scoring page lists the 2 items of each of the
18 facets, then the 3 facets each of the 6 domains averages, as
score_pid5() scores them with version = "BFPM".
generate_docx_pid5bfpm( file = "pid5bfpm.docx", papersize = c("us", "a4"), title = "PID5BF+M", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )generate_docx_pid5bfpm( file = "pid5bfpm.docx", papersize = c("us", "a4"), title = "PID5BF+M", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. |
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. |
include_scoring |
Logical. If |
font_size |
Numeric value specifying the base font size in points. |
font_family |
Character string specifying the font family to be used. |
Bach, B., Kerber, A., Aluja, A., Bastiaens, T., Keeley, J. W., Claes, L., Fossati, A., Gutierrez, F., Oliveira, S. E. S., Pires, R., Riegel, K. D., Rolland, J.-P., Roskam, I., Sellbom, M., Somma, A., Spanemberg, L., Strus, W., Thimm, J. C., Wright, A. G. C., & Zimmermann, J. (2020). International assessment of DSM-5 and ICD-11 personality disorder traits: Toward a common nosology in DSM-5.1. Psychopathology, 53(3-4), 179-188. doi:10.1159/000507589
# Write a PID5BF+M paper form to a temporary Word document generate_docx_pid5bfpm(file = tempfile(fileext = ".docx"))# Write a PID5BF+M paper form to a temporary Word document generate_docx_pid5bfpm(file = tempfile(fileext = ".docx"))
Write the 220-item PID-5 child form for ages 11 to 17 (Krueger et al.,
2013) as a paper form. Its items, their order and their keying are those
of the adult full form, so the items are pid_items$Text numbered 1 to
220 and the scoring page is the one generate_docx_pid5() prints. The
instructions are the child form's, and the footer carries the APA
copyright and permission notice the child form prints. Score the
responses with score_pid5(version = "FULL").
generate_docx_pid5child( file = "pid5child.docx", papersize = c("us", "a4"), title = "PID-5 (Full), Child Age 11–17", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )generate_docx_pid5child( file = "pid5child.docx", papersize = c("us", "a4"), title = "PID-5 (Full), Child Age 11–17", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. |
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. |
include_scoring |
Logical. If |
font_size |
Numeric value specifying the base font size in points. |
font_family |
Character string specifying the font family to be used. |
Krueger, R. F., Derringer, J., Markon, K. E., Watson, D., & Skodol, A. E. (2013). The Personality Inventory for DSM-5 (PID-5)—Child Age 11–17. American Psychiatric Association.
# Write a PID-5 child form to a temporary Word document generate_docx_pid5child(file = tempfile(fileext = ".docx"))# Write a PID-5 child form to a temporary Word document generate_docx_pid5child(file = tempfile(fileext = ".docx"))
Write the 218-item PID-5 Informant Form (PID-5-IRF; Markon et al., 2013),
on which an adult informant rates the person receiving care, as a paper
form. The items are numbered 1 to 218 in the form's order, with the
informant wording (pid_items$TextIRF). The form's opening instructions
come first; its rating prompt and the stem "He or she…" that each item
completes head the item table on every page, as on the printed form.
The scoring page lists each of the 25 facets with its informant item
numbers, marking the 14 reverse-scored items with (R), as score_pid5()
scores them with version = "IRF". The footer carries the APA copyright
and permission notice the form prints.
generate_docx_pid5irf( file = "pid5irf.docx", papersize = c("us", "a4"), title = "PID-5-IRF (Informant Form)", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )generate_docx_pid5irf( file = "pid5irf.docx", papersize = c("us", "a4"), title = "PID-5-IRF (Informant Form)", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. |
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. |
include_scoring |
Logical. If |
font_size |
Numeric value specifying the base font size in points. |
font_family |
Character string specifying the font family to be used. |
Markon, K. E., Quilty, L. C., Bagby, R. M., & Krueger, R. F. (2013). The Personality Inventory for DSM-5—Informant Form (PID-5-IRF)—Adult. American Psychiatric Association. See also Markon et al. (2013), Assessment, 20(3), 370-383. doi:10.1177/1073191113486513
# Write a PID-5 Informant Form paper form to a temporary Word document generate_docx_pid5irf(file = tempfile(fileext = ".docx"))# Write a PID-5 Informant Form paper form to a temporary Word document generate_docx_pid5irf(file = tempfile(fileext = ".docx"))
Generate a Word Document for the PID-5-SF
generate_docx_pid5sf( file = "pid5sf.docx", papersize = c("us", "a4"), title = "PID-5-SF", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )generate_docx_pid5sf( file = "pid5sf.docx", papersize = c("us", "a4"), title = "PID-5-SF", include_scoring = TRUE, font_size = 10, font_family = "Times New Roman" )
file |
Character string specifying the output file path. |
papersize |
Character string specifying the paper dimensions. Must be
one of |
title |
Character string for the document header title. |
include_scoring |
Logical. If |
font_size |
Numeric value specifying the base font size in points. |
font_family |
Character string specifying the font family to be used. |
# Write a PID-5-SF paper form to a temporary Word document generate_docx_pid5sf(file = tempfile(fileext = ".docx"))# Write a PID-5-SF paper form to a temporary Word document generate_docx_pid5sf(file = tempfile(fileext = ".docx"))
Creates a text file formatted for the Qualtrics Advanced Format import tool containing the Hierarchical Taxonomy of Psychopathology - Brief Report (HiTOP-BR) items and instructions.
generate_qualtrics_hitopbr( file = "hitopbr_qualtrics.txt", block_name = "HiTOP-BR", id_prefix = "HBR", include_instructions = TRUE, breaks = 15 )generate_qualtrics_hitopbr( file = "hitopbr_qualtrics.txt", block_name = "HiTOP-BR", id_prefix = "HBR", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. Defaults to
|
block_name |
Character string specifying the name of the block in
Qualtrics. Defaults to |
id_prefix |
Character string specifying the prefix for the question IDs.
Defaults to |
include_instructions |
Logical. If |
breaks |
Integer or |
Invisibly returns the path to the created file (file).
# Write a HiTOP-BR Qualtrics import file to a temporary location generate_qualtrics_hitopbr(file = tempfile(fileext = ".txt"))# Write a HiTOP-BR Qualtrics import file to a temporary location generate_qualtrics_hitopbr(file = tempfile(fileext = ".txt"))
Creates a text file formatted for the Qualtrics Advanced Format
import tool containing the 382 items of the HiTOP Digital Assessment and
Tracker (HiTOP-DAT) battery. The item questions are hdat_001 to
hdat_382 in battery order (hitopdat_items$Item), each a single-answer
multiple-choice question whose choices are the values and labels of the
item's own answer set (hitopdat_choices). Each answer carries its
scoring value from hitopdat_choices$Value as its Qualtrics recode
value, written in the file as the answer's [[Choice:<value>]] tag.
With include_instructions = TRUE, each measure that has instruction
text opens with a descriptive text question holding it: six of the
seven measures, all but the CAPE. That question's ID is
<id_prefix>_<measure>_instructions, where <measure> is the measure's
name in lower case with each run of other characters made _
(hdat_whodas_instructions, hdat_idas_ii_instructions). Each measure
after the first starts a new page.
generate_qualtrics_hitopdat( file = "hitopdat_qualtrics.txt", block_name = "HiTOP-DAT", id_prefix = "hdat", include_instructions = TRUE, breaks = 15 )generate_qualtrics_hitopdat( file = "hitopdat_qualtrics.txt", block_name = "HiTOP-DAT", id_prefix = "hdat", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. Defaults to
|
block_name |
Character string specifying the name of the block in
Qualtrics. Defaults to |
id_prefix |
Character string specifying the prefix for the question IDs.
Defaults to |
include_instructions |
Logical. If |
breaks |
Integer or |
Invisibly returns the path to the created file (file).
generate_docx_hitopdat() and generate_redcap_hitopdat() for
the Word forms and the REDCap import file. Step-by-step import
instructions for Qualtrics and REDCap:
https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a HiTOP-DAT Qualtrics import file to a temporary location generate_qualtrics_hitopdat(file = tempfile(fileext = ".txt"))# Write a HiTOP-DAT Qualtrics import file to a temporary location generate_qualtrics_hitopdat(file = tempfile(fileext = ".txt"))
Creates a text file formatted for the Qualtrics Advanced Format import tool containing the Hierarchical Taxonomy of Psychopathology - Self-Report (HiTOP-SR) items and instructions.
generate_qualtrics_hitopsr( file = "hitopsr_qualtrics.txt", block_name = "HiTOP-SR", id_prefix = "HSR", include_instructions = TRUE, breaks = 15, module = NULL, descriptor = NULL, subset = NULL )generate_qualtrics_hitopsr( file = "hitopsr_qualtrics.txt", block_name = "HiTOP-SR", id_prefix = "HSR", include_instructions = TRUE, breaks = 15, module = NULL, descriptor = NULL, subset = NULL )
file |
Character string specifying the output file path. Defaults to
|
block_name |
Character string specifying the name of the block in
Qualtrics. Defaults to |
id_prefix |
Character string specifying the prefix for the question IDs.
Defaults to |
include_instructions |
Logical. If |
breaks |
Integer or |
module |
An optional |
descriptor |
An optional path to write a module descriptor to, beside
the instrument file. The saved file records which scales the form covers
and which instrument items they draw on, so |
subset |
Deprecated. The former name of |
Invisibly returns the path to the created file (file).
write_module() and read_module() for the descriptor file.
# Write a HiTOP-SR Qualtrics import file to a temporary location generate_qualtrics_hitopsr(file = tempfile(fileext = ".txt")) # A two-scale module, original numbering preserved (unlike the Word form) generate_qualtrics_hitopsr( file = tempfile(fileext = ".txt"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")) )# Write a HiTOP-SR Qualtrics import file to a temporary location generate_qualtrics_hitopsr(file = tempfile(fileext = ".txt")) # A two-scale module, original numbering preserved (unlike the Word form) generate_qualtrics_hitopsr( file = tempfile(fileext = ".txt"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")) )
Generate a Qualtrics Import File for the PID-5 (Full)
generate_qualtrics_pid5( file = "pid5_qualtrics.txt", block_name = "PID-5", id_prefix = "PID5", include_instructions = TRUE, breaks = 15 )generate_qualtrics_pid5( file = "pid5_qualtrics.txt", block_name = "PID-5", id_prefix = "PID5", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. |
block_name |
Character string specifying the name of the block in Qualtrics. |
id_prefix |
Character string specifying the prefix for the question IDs. |
include_instructions |
Logical. If |
breaks |
Integer or |
# Write a PID-5 (full) Qualtrics import file to a temporary location generate_qualtrics_pid5(file = tempfile(fileext = ".txt"))# Write a PID-5 (full) Qualtrics import file to a temporary location generate_qualtrics_pid5(file = tempfile(fileext = ".txt"))
Generate a Qualtrics Import File for the PID-5-BF
generate_qualtrics_pid5bf( file = "pid5bf_qualtrics.txt", block_name = "PID-5-BF", id_prefix = "PID5BF", include_instructions = TRUE, breaks = 15 )generate_qualtrics_pid5bf( file = "pid5bf_qualtrics.txt", block_name = "PID-5-BF", id_prefix = "PID5BF", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. |
block_name |
Character string specifying the name of the block in Qualtrics. |
id_prefix |
Character string specifying the prefix for the question IDs. |
include_instructions |
Logical. If |
breaks |
Integer or |
# Write a PID-5-BF Qualtrics import file to a temporary location generate_qualtrics_pid5bf(file = tempfile(fileext = ".txt"))# Write a PID-5-BF Qualtrics import file to a temporary location generate_qualtrics_pid5bf(file = tempfile(fileext = ".txt"))
The 25 items of the PID-5-BF child form for ages 11 to 17, which are the
adult brief form's items in the same order with the same keying, and the
child form's instructions and response options. The question IDs are the
adult form's, PID5BF_01 to PID5BF_25, so the export scores with
score_pid5(version = "BF") as an adult export does.
generate_qualtrics_pid5bfchild( file = "pid5bfchild_qualtrics.txt", block_name = "PID-5-BF Child", id_prefix = "PID5BF", include_instructions = TRUE, breaks = 15 )generate_qualtrics_pid5bfchild( file = "pid5bfchild_qualtrics.txt", block_name = "PID-5-BF Child", id_prefix = "PID5BF", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. |
block_name |
Character string specifying the name of the block in Qualtrics. |
id_prefix |
Character string specifying the prefix for the question IDs. |
include_instructions |
Logical. If |
breaks |
Integer or |
Krueger, R. F., Derringer, J., Markon, K. E., Watson, D., & Skodol, A. E. (2013). The Personality Inventory for DSM-5—Brief Form (PID-5-BF)—Child Age 11–17. American Psychiatric Association.
# Write a PID-5-BF child form Qualtrics import file to a temporary location generate_qualtrics_pid5bfchild(file = tempfile(fileext = ".txt"))# Write a PID-5-BF child form Qualtrics import file to a temporary location generate_qualtrics_pid5bfchild(file = tempfile(fileext = ".txt"))
The 36 items of the modified brief form of the PID-5 (PID5BF+M), in BF+M
order with their PID-5 text, and the instructions and response options of
the other PID-5 forms. Score the export with
score_pid5(version = "BFPM").
generate_qualtrics_pid5bfpm( file = "pid5bfpm_qualtrics.txt", block_name = "PID5BF+M", id_prefix = "PID5BFPM", include_instructions = TRUE, breaks = 15 )generate_qualtrics_pid5bfpm( file = "pid5bfpm_qualtrics.txt", block_name = "PID5BF+M", id_prefix = "PID5BFPM", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. |
block_name |
Character string specifying the name of the block in Qualtrics. |
id_prefix |
Character string specifying the prefix for the question IDs. |
include_instructions |
Logical. If |
breaks |
Integer or |
# Write a PID5BF+M Qualtrics import file to a temporary location generate_qualtrics_pid5bfpm(file = tempfile(fileext = ".txt"))# Write a PID5BF+M Qualtrics import file to a temporary location generate_qualtrics_pid5bfpm(file = tempfile(fileext = ".txt"))
The 220 items of the PID-5 child form for ages 11 to 17, which are the
adult full form's items in the same order with the same keying, and the
child form's instructions and response options. The question IDs are the
adult form's, PID5_001 to PID5_220, so the export scores with
score_pid5(version = "FULL") as an adult export does.
generate_qualtrics_pid5child( file = "pid5child_qualtrics.txt", block_name = "PID-5 Child", id_prefix = "PID5", include_instructions = TRUE, breaks = 15 )generate_qualtrics_pid5child( file = "pid5child_qualtrics.txt", block_name = "PID-5 Child", id_prefix = "PID5", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. |
block_name |
Character string specifying the name of the block in Qualtrics. |
id_prefix |
Character string specifying the prefix for the question IDs. |
include_instructions |
Logical. If |
breaks |
Integer or |
Krueger, R. F., Derringer, J., Markon, K. E., Watson, D., & Skodol, A. E. (2013). The Personality Inventory for DSM-5 (PID-5)—Child Age 11–17. American Psychiatric Association.
# Write a PID-5 child form Qualtrics import file to a temporary location generate_qualtrics_pid5child(file = tempfile(fileext = ".txt"))# Write a PID-5 child form Qualtrics import file to a temporary location generate_qualtrics_pid5child(file = tempfile(fileext = ".txt"))
The 218 items of the PID-5 Informant Form (PID-5-IRF), in the form's order
with the informant wording (pid_items$TextIRF). The instructions block
ends with the form's rating prompt and the stem "He or she…" that each
item completes, and the response options are the form's 0 to 3 labels.
With breaks, a descriptive block restating the prompt and stem opens
every page after the first. The
question IDs are PID5IRF_001 to PID5IRF_218. Score the export with
score_pid5(version = "IRF").
generate_qualtrics_pid5irf( file = "pid5irf_qualtrics.txt", block_name = "PID-5-IRF", id_prefix = "PID5IRF", include_instructions = TRUE, breaks = 15 )generate_qualtrics_pid5irf( file = "pid5irf_qualtrics.txt", block_name = "PID-5-IRF", id_prefix = "PID5IRF", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. |
block_name |
Character string specifying the name of the block in Qualtrics. |
id_prefix |
Character string specifying the prefix for the question IDs. |
include_instructions |
Logical. If |
breaks |
Integer or |
# Write a PID-5 Informant Form Qualtrics import file to a temporary location generate_qualtrics_pid5irf(file = tempfile(fileext = ".txt"))# Write a PID-5 Informant Form Qualtrics import file to a temporary location generate_qualtrics_pid5irf(file = tempfile(fileext = ".txt"))
Generate a Qualtrics Import File for the PID-5-SF
generate_qualtrics_pid5sf( file = "pid5sf_qualtrics.txt", block_name = "PID-5-SF", id_prefix = "PID5SF", include_instructions = TRUE, breaks = 15 )generate_qualtrics_pid5sf( file = "pid5sf_qualtrics.txt", block_name = "PID-5-SF", id_prefix = "PID5SF", include_instructions = TRUE, breaks = 15 )
file |
Character string specifying the output file path. |
block_name |
Character string specifying the name of the block in Qualtrics. |
id_prefix |
Character string specifying the prefix for the question IDs. |
include_instructions |
Logical. If |
breaks |
Integer or |
# Write a PID-5-SF Qualtrics import file to a temporary location generate_qualtrics_pid5sf(file = tempfile(fileext = ".txt"))# Write a PID-5-SF Qualtrics import file to a temporary location generate_qualtrics_pid5sf(file = tempfile(fileext = ".txt"))
Generates a REDCap-compatible data dictionary for the Hierarchical Taxonomy of Psychopathology - Brief Report (HiTOP-BR) and packages it into an Instrument ZIP file for easy uploading.
generate_redcap_hitopbr( file = "hitopbr_redcap.zip", form_name = "hitopbr_questionnaire", required = TRUE, breaks = 15 )generate_redcap_hitopbr( file = "hitopbr_redcap.zip", form_name = "hitopbr_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file.
Defaults to |
form_name |
Character string. The internal name of the form in REDCap.
Defaults to |
required |
Logical. Whether the items should be marked as required.
Defaults to |
breaks |
Integer or |
Invisibly returns the path to the created file (file).
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a HiTOP-BR REDCap instrument ZIP to a temporary location generate_redcap_hitopbr(file = tempfile(fileext = ".zip"))# Write a HiTOP-BR REDCap instrument ZIP to a temporary location generate_redcap_hitopbr(file = tempfile(fileext = ".zip"))
Generates a REDCap data dictionary for the HiTOP Digital
Assessment and Tracker (HiTOP-DAT) battery and packages it into an
Instrument ZIP file for uploading. The 382 item fields are hdat_001 to
hdat_382 in battery order (hitopdat_items$Item), each a radio field
whose choices are the values and labels of the item's own answer set
(hitopdat_choices). Each of the seven measures opens with a
descriptive field holding its instruction text, except the CAPE, which
has none. The field is named hdat_<measure>_instructions, where
<measure> is the measure's name in lower case with each run of other
characters made _ (hdat_whodas_instructions,
hdat_idas_ii_instructions). Each measure after the first starts a
new page. A page break inside a measure restates the measure's
instruction text in the section header of the page's first item.
generate_redcap_hitopdat( file = "hitopdat_redcap.zip", form_name = "hitopdat_questionnaire", required = TRUE, breaks = 15 )generate_redcap_hitopdat( file = "hitopdat_redcap.zip", form_name = "hitopdat_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file.
Defaults to |
form_name |
Character string. The internal name of the form in REDCap.
Defaults to |
required |
Logical. Whether the items should be marked as required.
Defaults to |
breaks |
Integer or |
Invisibly returns the path to the created file (file).
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a HiTOP-DAT REDCap instrument ZIP to a temporary location generate_redcap_hitopdat(file = tempfile(fileext = ".zip"))# Write a HiTOP-DAT REDCap instrument ZIP to a temporary location generate_redcap_hitopdat(file = tempfile(fileext = ".zip"))
Generates a REDCap-compatible data dictionary for the Hierarchical Taxonomy of Psychopathology - Substance Use Module (HiTOP-HSUM) and packages it into an Instrument ZIP file for easy uploading.
generate_redcap_hitophsum( file = "hitophsum_redcap.zip", form_name = "hitophsum_questionnaire", required = TRUE, other_drug_rule = c("most_frequent", "per_drug") )generate_redcap_hitophsum( file = "hitophsum_redcap.zip", form_name = "hitophsum_questionnaire", required = TRUE, other_drug_rule = c("most_frequent", "per_drug") )
file |
Character string. The destination path for the output ZIP file.
Defaults to |
form_name |
Character string. The internal name of the form in REDCap.
Defaults to |
required |
Logical. Whether the items should be marked as required.
Defaults to |
other_drug_rule |
Character string. How symptom items are gated for
the "other drug" substances (every substance except alcohol and
nicotine). The default, |
Invisibly returns the path to the created file (file).
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a HiTOP-HSUM REDCap instrument ZIP to a temporary location generate_redcap_hitophsum(file = tempfile(fileext = ".zip"))# Write a HiTOP-HSUM REDCap instrument ZIP to a temporary location generate_redcap_hitophsum(file = tempfile(fileext = ".zip"))
Generates a REDCap-compatible data dictionary for the Hierarchical Taxonomy of Psychopathology - Self-Report (HiTOP-SR) and packages it into an Instrument ZIP file for easy uploading.
generate_redcap_hitopsr( file = "hitopsr_redcap.zip", form_name = "hitopsr_questionnaire", required = TRUE, breaks = 15, module = NULL, descriptor = NULL, subset = NULL )generate_redcap_hitopsr( file = "hitopsr_redcap.zip", form_name = "hitopsr_questionnaire", required = TRUE, breaks = 15, module = NULL, descriptor = NULL, subset = NULL )
file |
Character string. The destination path for the output ZIP file.
Defaults to |
form_name |
Character string. The internal name of the form in REDCap.
Defaults to |
required |
Logical. Whether the items should be marked as required.
Defaults to |
breaks |
Integer or |
module |
An optional |
descriptor |
An optional path to write a module descriptor to, beside
the instrument file. The saved file records which scales the form covers
and which instrument items they draw on, so |
subset |
Deprecated. The former name of |
Invisibly returns the path to the created file (file).
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
write_module() and read_module() for the descriptor file.
# Write a HiTOP-SR REDCap instrument ZIP to a temporary location generate_redcap_hitopsr(file = tempfile(fileext = ".zip")) # A two-scale module, original numbering preserved (unlike the Word form) generate_redcap_hitopsr( file = tempfile(fileext = ".zip"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")) )# Write a HiTOP-SR REDCap instrument ZIP to a temporary location generate_redcap_hitopsr(file = tempfile(fileext = ".zip")) # A two-scale module, original numbering preserved (unlike the Word form) generate_redcap_hitopsr( file = tempfile(fileext = ".zip"), module = hitop_module("hitopsr", c("Agoraphobia", "Appetite Loss")) )
Generate a REDCap Instrument ZIP File for the PID-5 (Full)
generate_redcap_pid5( file = "pid5_redcap.zip", form_name = "pid5_questionnaire", required = TRUE, breaks = 15 )generate_redcap_pid5( file = "pid5_redcap.zip", form_name = "pid5_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file. |
form_name |
Character string. The internal name of the form in REDCap. |
required |
Logical. Whether the items should be marked as required. |
breaks |
Integer or |
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a PID-5 (full) REDCap instrument ZIP to a temporary location generate_redcap_pid5(file = tempfile(fileext = ".zip"))# Write a PID-5 (full) REDCap instrument ZIP to a temporary location generate_redcap_pid5(file = tempfile(fileext = ".zip"))
Generate a REDCap Instrument ZIP File for the PID-5-BF
generate_redcap_pid5bf( file = "pid5bf_redcap.zip", form_name = "pid5bf_questionnaire", required = TRUE, breaks = 15 )generate_redcap_pid5bf( file = "pid5bf_redcap.zip", form_name = "pid5bf_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file. |
form_name |
Character string. The internal name of the form in REDCap. |
required |
Logical. Whether the items should be marked as required. |
breaks |
Integer or |
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a PID-5-BF REDCap instrument ZIP to a temporary location generate_redcap_pid5bf(file = tempfile(fileext = ".zip"))# Write a PID-5-BF REDCap instrument ZIP to a temporary location generate_redcap_pid5bf(file = tempfile(fileext = ".zip"))
The 25 items of the PID-5-BF child form for ages 11 to 17, which are the
adult brief form's items in the same order with the same keying, and the
child form's instructions and response options. The item fields are the
adult form's, pid5bf_01 to pid5bf_25, the names rename_pid5_items()
and label_pid5() use with version = "BF". Score them with
score_pid5(version = "BF"). Because the field names are the adult
form's, one REDCap project cannot hold this instrument and the one
generate_redcap_pid5bf() writes.
generate_redcap_pid5bfchild( file = "pid5bfchild_redcap.zip", form_name = "pid5bfchild_questionnaire", required = TRUE, breaks = 15 )generate_redcap_pid5bfchild( file = "pid5bfchild_redcap.zip", form_name = "pid5bfchild_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file. |
form_name |
Character string. The internal name of the form in REDCap. |
required |
Logical. Whether the items should be marked as required. |
breaks |
Integer or |
Krueger, R. F., Derringer, J., Markon, K. E., Watson, D., & Skodol, A. E. (2013). The Personality Inventory for DSM-5—Brief Form (PID-5-BF)—Child Age 11–17. American Psychiatric Association.
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a PID-5-BF child form REDCap instrument ZIP to a temporary location generate_redcap_pid5bfchild(file = tempfile(fileext = ".zip"))# Write a PID-5-BF child form REDCap instrument ZIP to a temporary location generate_redcap_pid5bfchild(file = tempfile(fileext = ".zip"))
The 36 items of the modified brief form of the PID-5 (PID5BF+M), in BF+M
order with their PID-5 text, and the instructions and response options of
the other PID-5 forms. The item fields are pid5bfpm_01 to pid5bfpm_36,
the names rename_pid5_items() and label_pid5() use with
version = "BFPM". Score them with score_pid5(version = "BFPM").
generate_redcap_pid5bfpm( file = "pid5bfpm_redcap.zip", form_name = "pid5bfpm_questionnaire", required = TRUE, breaks = 15 )generate_redcap_pid5bfpm( file = "pid5bfpm_redcap.zip", form_name = "pid5bfpm_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file. |
form_name |
Character string. The internal name of the form in REDCap. |
required |
Logical. Whether the items should be marked as required. |
breaks |
Integer or |
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a PID5BF+M REDCap instrument ZIP to a temporary location generate_redcap_pid5bfpm(file = tempfile(fileext = ".zip"))# Write a PID5BF+M REDCap instrument ZIP to a temporary location generate_redcap_pid5bfpm(file = tempfile(fileext = ".zip"))
The 220 items of the PID-5 child form for ages 11 to 17, which are the
adult full form's items in the same order with the same keying, and the
child form's instructions and response options. The item fields are the
adult form's, pid5_001 to pid5_220, the names rename_pid5_items()
and label_pid5() use with version = "FULL". Score them with
score_pid5(version = "FULL"). Because the field names are the adult
form's, one REDCap project cannot hold this instrument and the one
generate_redcap_pid5() writes.
generate_redcap_pid5child( file = "pid5child_redcap.zip", form_name = "pid5child_questionnaire", required = TRUE, breaks = 15 )generate_redcap_pid5child( file = "pid5child_redcap.zip", form_name = "pid5child_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file. |
form_name |
Character string. The internal name of the form in REDCap. |
required |
Logical. Whether the items should be marked as required. |
breaks |
Integer or |
Krueger, R. F., Derringer, J., Markon, K. E., Watson, D., & Skodol, A. E. (2013). The Personality Inventory for DSM-5 (PID-5)—Child Age 11–17. American Psychiatric Association.
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a PID-5 child form REDCap instrument ZIP to a temporary location generate_redcap_pid5child(file = tempfile(fileext = ".zip"))# Write a PID-5 child form REDCap instrument ZIP to a temporary location generate_redcap_pid5child(file = tempfile(fileext = ".zip"))
The 218 items of the PID-5 Informant Form (PID-5-IRF), in the form's order
with the informant wording (pid_items$TextIRF). The instructions field
ends with the form's rating prompt and the stem "He or she…" that each
item completes, and the response options are the form's 0 to 3 labels.
With breaks, the section header that starts each later page restates the
prompt and stem. The
item fields are pid5irf_001 to pid5irf_218, the names
rename_pid5_items() and label_pid5() use with version = "IRF". Score
them with score_pid5(version = "IRF").
generate_redcap_pid5irf( file = "pid5irf_redcap.zip", form_name = "pid5irf_questionnaire", required = TRUE, breaks = 15 )generate_redcap_pid5irf( file = "pid5irf_redcap.zip", form_name = "pid5irf_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file. |
form_name |
Character string. The internal name of the form in REDCap. |
required |
Logical. Whether the items should be marked as required. |
breaks |
Integer or |
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a PID-5 Informant Form REDCap instrument ZIP to a temporary location generate_redcap_pid5irf(file = tempfile(fileext = ".zip"))# Write a PID-5 Informant Form REDCap instrument ZIP to a temporary location generate_redcap_pid5irf(file = tempfile(fileext = ".zip"))
Generate a REDCap Instrument ZIP File for the PID-5-SF
generate_redcap_pid5sf( file = "pid5sf_redcap.zip", form_name = "pid5sf_questionnaire", required = TRUE, breaks = 15 )generate_redcap_pid5sf( file = "pid5sf_redcap.zip", form_name = "pid5sf_questionnaire", required = TRUE, breaks = 15 )
file |
Character string. The destination path for the output ZIP file. |
form_name |
Character string. The internal name of the form in REDCap. |
required |
Logical. Whether the items should be marked as required. |
breaks |
Integer or |
Step-by-step import instructions for Qualtrics and REDCap: https://jmgirard.github.io/hitop/articles/import-instructions.html
# Write a PID-5-SF REDCap instrument ZIP to a temporary location generate_redcap_pid5sf(file = tempfile(fileext = ".zip"))# Write a PID-5-SF REDCap instrument ZIP to a temporary location generate_redcap_pid5sf(file = tempfile(fileext = ".zip"))
Version manifest for the prebuilt instrument artifacts. They ship in the
package at inst/extdata/ and are distributed from the package website's
download pages, which serve their own byte-identical copy. Each build of
an artifact adds a row (the full history is kept), so the latest row per
file describes the currently distributed file. Artifact revisions are
identified by build date; the instrument version (e.g., "1.0") is the
version of the instrument itself and changes only when its publisher
revises it. To check which build you have, compare your downloaded file's
MD5 checksum (e.g., tools::md5sum()) against the md5 column.
hitop_artifactshitop_artifacts
A tibble with one row per artifact build and 7 columns:
Artifact file name, the same in inst/extdata/ and on the
website's download pages
Instrument the artifact administers
Artifact format: "docx_us", "docx_a4", "qualtrics",
"redcap", or "json"
Version of the instrument itself
Date this build of the artifact was generated
MD5 checksum of the built file
What changed in this build
hitop_artifactshitop_artifacts
Builds a validated description of a module: a chosen set of
an instrument's scales, administered and scored on its own. Supplying the
result as the module argument of a generator produces an instrument
containing only the items belonging to those scales. The items field
below always holds the original instrument numbers, whatever a
generator prints: the online exports keep those numbers, while
generate_docx_hitopsr() numbers a Word form 1 to n down the page
unless asked not to. Supplying the module again to score_hitopsr() or
reliability_hitopsr() scores the collected columns either way.
A module naming every scale holds exactly the instrument's own items –
all 405 of them for the HiTOP-SR – but it is still a module, and
generate_docx_hitopsr() frames it as one: the form is headed
"HiTOP-SR Module (v1.0)", and with randomize = TRUE it also carries a
405-row crosswalk. Supply no module at all to get the full instrument's
framing. The Qualtrics and REDCap exports are the same either way.
Use available_scales() to see which scales an instrument offers.
hitop_module(instrument = "hitopsr", scales, call = rlang::current_env())hitop_module(instrument = "hitopsr", scales, call = rlang::current_env())
instrument |
A string naming the instrument to build a module from.
Currently only |
scales |
A character vector of scale names to keep. Names may be given
either as they are printed on the instrument ( |
call |
Internal. The environment blamed by any error this raises. A
default argument is evaluated in this function's own frame, so a direct
call blames |
An object of class hitop_module: a list with the resolved
instrument, the canonical display scales and their camelCase stems,
the integer items kept (original instrument numbering, ascending), the
parallel reverse keying flags, and nItems.
available_scales() for the scale names this accepts;
generate_docx_hitopsr(), generate_qualtrics_hitopsr(), and
generate_redcap_hitopsr(), each of which takes a module argument;
score_hitopsr() and reliability_hitopsr() for scoring the result.
# Describe a two-scale module of the HiTOP-SR m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss")) m # `$items` holds the original HiTOP-SR numbers, not 1..8 -- this is the # descriptor, not what any particular generator prints m$items # Select the collected item columns by NAME, never by position: `m$items` # holds item numbers, which are column positions only in a frame that is # exactly the 405 items in order. `ku_hitopsr` leads with `participant` and # `biosex`, so `ku_hitopsr[m$items]` would quietly return the wrong columns. collected <- ku_hitopsr[sprintf("hsr_%03d", m$items)] ncol(collected) == m$nItems# Describe a two-scale module of the HiTOP-SR m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss")) m # `$items` holds the original HiTOP-SR numbers, not 1..8 -- this is the # descriptor, not what any particular generator prints m$items # Select the collected item columns by NAME, never by position: `m$items` # holds item numbers, which are column positions only in a frame that is # exactly the 405 items in order. `ku_hitopsr` leads with `participant` and # `biosex`, so `ku_hitopsr[m$items]` would quietly return the wrong columns. collected <- ku_hitopsr[sprintf("hsr_%03d", m$items)] ncol(collected) == m$nItems
Descriptive statistics for each HiTOP-BR scale, as printed in the "Superspectra and Spectra Scales" block of Table 1 of the HiTOP-SR introduction paper. The reference group is that 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, not a community norm: no weighting to a census frame was applied and the paper publishes no raw-score to T-score table. Read a score against these statistics as a comparison with the sample the instrument was developed on.
hitopbr_devstatshitopbr_devstats
A tibble with 8 rows and 8 columns:
The name of the scale. Matches hitopbr_scales$Scale.
That name converted to camel case – the stem
score_hitopbr() appends to its prefix when it names a score column
"scale" throughout. Table 1 prints all eight rows under one
heading and labels none of them a superspectrum or a spectrum, so no such
distinction is recorded here.
The number of items in the scale (integer)
The internal-consistency reliability coefficient printed for that scale
What that coefficient is. "alpha" throughout:
Cronbach's alpha is what the paper prints. Supplied by this package, not
read from the table.
The scale score's mean in the development sample
The scale score's standard deviation in the development sample
Every statistic is a printed cell of that table, transcribed and verified
against it; nothing here is computed from data by this package. The mean and
sd are on the HiTOP-BR's own four-option 1-4 response coding, and scale
scores are item means, so a score computed on another coding is not comparable
to them. interval_hitopbr() reads this table.
The HiTOP-BR scales were developed independently of the HiTOP-SR primary scales, drawing on the same item pool, and are not a short form of them (Table 1's Note), so these statistics are not comparable with hitopsr_devstats.
Table 1's printed # Items agrees with the item count
hitopbr_scales derives from hitopbr_items for all eight scales. It did
not always: item 36 ("I had a hard time asserting myself to others.") was
keyed to Detachment in this package until it was corrected to
Internalizing, the scale the instrument's development workbook gives it in
both its item-to-scale sheet and its scoring syntax, and the scale the
paper's own factor table loads it on. Detachment therefore has 5 items and
Internalizing 8, which is what Table 1 prints for each.
hitopbr_devstatshitopbr_devstats
Information about items in the HiTOP-BR.
hitopbr_itemshitopbr_items
A tibble with 45 rows and 8 columns:
Item number on the HITOP-BR (integer)
Whether the item needs to be reverse scored
Name of the scale
Whether the item is part of the Externalizing scale
Whether the item is part of the p-Factor scale
Item text
Item number on the HiTOP-SR (integer)
Item ID in the original, development item pool
hitopbr_itemshitopbr_items
Information about scales in the HiTOP-BR.
hitopbr_scaleshitopbr_scales
A tibble with 8 rows and 5 columns:
Name of the scale
A list column containing one item-data tibble per scale; its two item-number columns are integers
The number of items in the scale (integer)
A list column containing one integer item-number vector per scale
The name of the scale converted to camel case
hitopbr_scaleshitopbr_scales
The answer sets referenced by hitopdat_items$Choice_Set, one row per
answer. Value is the value the battery's Qualtrics file gives the answer
when it scores an item in the forward direction. The file also offers a
"Skip" answer on every item, which is not included.
hitopdat_choiceshitopdat_choices
A tibble with 58 rows and 3 columns:
Name of the answer set
Coded response value (integer)
Response label displayed to respondents
hitopdat_choiceshitopdat_choices
The items of the HiTOP-DAT (HiTOP Digital Assessment and Tracker), a battery of seven measures: the WHODAS (12 items), the IDAS-II (99), the AUDIT (10), the DUDIT (11), the positive items of the CAPE (20), the CAT-PD static form (216) and the PHQ-15 (14). The battery numbers run from 1 to 382 in the order the battery gives the measures, which is the order listed here.
hitopdat_itemshitopdat_items
A tibble with 382 rows and 5 columns:
The item's number in the battery, 1 to 382 (integer)
The measure the item belongs to
The item's number in its own measure (integer)
Item text
Name of the item's answer set (see hitopdat_choices)
The item text is taken from the battery's Qualtrics file, with its markup removed and line breaks within an item made spaces. CAT-PD item 194, cut short in the file, is completed from the IPIP key. The file moves the PHQ-15's item 4 (menstrual problems) out of the battery, so the PHQ-15 has 14 items here and its own numbers skip 4. The battery gives only the CAPE's positive items, and they keep their CAPE numbers (2 to 42, with gaps). The battery has no scoring function in this package yet.
hitopdat_choices, hitopdat_scales
hitopdat_itemshitopdat_items
The scales the HiTOP-DAT scores, one row per scale: the 19 IDAS-II scales,
the 33 CAT-PD facets, and one total each for the WHODAS, AUDIT, DUDIT, CAPE
positive items and PHQ-15. Scale is the name the revised HiTOP-DAT
manual (Jonas et al., unpublished revised version of 2026-10-15) gives the
scale. Item numbers are battery numbers, as in hitopdat_items$Item.
hitopdat_scaleshitopdat_scales
A tibble with 57 rows and 6 columns:
The measure the scale belongs to, as in
hitopdat_items$Measure
Name of the scale
The name of the scale converted to camel case
A list column containing one integer item-number vector per scale
A list column containing, per scale, the integer numbers of the items that scale reverses (empty when it reverses none)
The number of items in the scale (integer)
Scale membership and reverse keying come from the scoring of the battery's Qualtrics file. The CAT-PD facets are checked against the IPIP CAT-PD-SF v1.1 key, and the IDAS-II scales against the IDAS-II scoring key (Watson, 2011). An item can be reversed in one scale and not in another: the IDAS-II's General Depression reverses two Well-Being items that Well-Being scores forward.
hitopdat_scaleshitopdat_scales
Response choice sets referenced by hitophsum_items$Choice_Set. Used by the
HiTOP-HSUM instrument generators (e.g. generate_redcap_hitophsum()).
hitophsum_choiceshitophsum_choices
A tibble with 185 rows and 3 columns:
Name of the choice set
Coded response value
Response label displayed to respondents
hitophsum_choiceshitophsum_choices
Information about the items in the HiTOP-HSUM (Harmful Substance Use Measure).
Used by the HiTOP-HSUM instrument generators (e.g. generate_redcap_hitophsum()).
hitophsum_itemshitophsum_items
A tibble with 650 rows and 9 columns:
Item number (integer)
Variable name for the item
Name of the substance the item refers to
The assessment tier the item belongs to (e.g. Screening)
The response field type (e.g. radio)
Name of the gating variable, or NA if ungated
Value of the gating variable required to show the item, or NA
Name of the response choice set (see hitophsum_choices)
Item text
hitophsum_itemshitophsum_items
Brief clinician and client-facing definitions of each scale and subscale in the HiTOP-SR
hitopsr_definitionshitopsr_definitions
A tibble with 93 rows and 5 columns:
The name of the scale
The name of the subscale (or NA if not a subscale)
The brief clinician-facing definition (10-20 words)
The client-facing definition with examples (30-40 words)
The camel case name of whatever the row defines: the subscale where there is one, otherwise the scale. Matches hitopsr_scales$camelCase on the scale rows and hitopsr_subscales$camelCase on the subscale rows.
hitopsr_definitionshitopsr_definitions
Descriptive statistics for each HiTOP-SR primary scale and subscale, as printed in Table 1 of the HiTOP-SR introduction paper. The reference group is that 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, not a community norm: no weighting to a census frame was applied and the paper publishes no raw-score to T-score table. Read a score against these statistics as a comparison with the sample the instrument was developed on.
hitopsr_devstatshitopsr_devstats
A tibble with 93 rows and 8 columns:
The name of the scale or subscale. Matches hitopsr_scales$Scale on the scale rows and hitopsr_subscales$Subscale on the subscale rows.
That name converted to camel case – the stem
score_hitopsr() appends to its prefix when it names a score column
Either "scale" (76 rows) or "subscale" (17 rows)
The number of items in the scale or subscale (integer)
The internal-consistency reliability coefficient printed for that scale
What that coefficient is. "alpha" throughout:
Cronbach's alpha is what the paper prints. Supplied by this package, not
read from the table.
The scale score's mean in the development sample
The scale score's standard deviation in the development sample
Every statistic is a printed cell of that table, transcribed and verified
against it; nothing here is computed from data by this package. The mean and
sd are on the HiTOP-SR's own four-option 1-4 response coding, and scale
scores are item means, so a score computed on another coding is not comparable
to them. interval_hitopsr() reads this table.
hitopsr_devstatshitopsr_devstats
Information about items in the HiTOP-SR.
hitopsr_itemshitopsr_items
A tibble with 405 rows and 6 columns:
Item number on the full HiTOP-SR (integer)
Whether the item needs to be reverse scored
Name of the scale (level 2)
Name of the subscale (level 1)
Item text
Item ID in the original, development item pool
Two scales carry other names in the literature and in earlier versions of
this package. The scale this table calls Non-suicidal Self-injury is
widely written by its abbreviation, NSSI, and was named that way here
before version 0.2.0; the scale it calls Appearance Focus was named Body
Focus here before version 0.2.0. Both names are the ones printed in the
HiTOP-SR introduction paper's Table 1. Scoring functions derive a column
name from each scale name, so those scales' scored columns are
hsr_nonSuicidalSelfInjury and hsr_appearanceFocus.
hitopsr_itemshitopsr_items
Information about scales in the HiTOP-SR.
hitopsr_scaleshitopsr_scales
A tibble with 76 rows and 5 columns:
Name of the scale
A list column containing one item-data tibble per scale; its item-number column is an integer
The number of items in the scale (integer)
A list column containing one integer item-number vector per scale
The name of the scale converted to camel case
hitopsr_scaleshitopsr_scales
Information about subscales in the HiTOP-SR.
hitopsr_subscaleshitopsr_subscales
A tibble with 17 rows and 6 columns:
Name of the subscale
Name of the scale that the subscale is part of
A list column containing one item-data tibble per subscale; its item-number column is an integer
The number of items in the subscale (integer)
A list column containing one integer item-number vector per subscale
The name of the subscale converted to camel case
hitopsr_subscaleshitopsr_subscales
Converts scored HiTOP-BR columns into a regression-based true-score estimate
and a confidence interval around it, using the development-sample mean,
standard deviation and reliability shipped as hitopbr_devstats. This
function converts already-scored columns and never rescores: the 8 scale
columns score_hitopbr() produces are the ones it is built for, and
hitopbr_devstats carries a row for each of them.
interval_hitopbr( data, scores, srange = c(1, 4), prefix = "hbr_", level = 0.95, append = TRUE )interval_hitopbr( data, scores, srange = c(1, 4), prefix = "hbr_", level = 0.95, append = TRUE )
data |
A data frame containing scored HiTOP-BR columns. |
scores |
The score columns to convert, as column names or column
positions (mirroring the |
srange |
The response range the items were scored on, as
|
prefix |
The prefix |
level |
The confidence level, as a proportion between 0 and 1. Defaults
to |
append |
Whether to return the input |
What is computed. For a score on a scale whose reference
group has mean , standard deviation and reliability
, the estimate and bounds are Schmukle's (2026) Equations (10) to
(12), p. 821:
where is the two-sided standard normal quantile for level
(1.959964 at the default 0.95). The estimate is the observed score pulled
toward the reference mean, because with imperfect measurement a true score
tends to lie nearer the mean than the observed score does; the
factor is Schmukle's scale correction, which returns the
estimate to the metric the observed score is on so the two can be read
against each other.
The reference group is a development sample. hitopbr_devstats carries the statistics printed for the HiTOP-SR introduction paper's Development Sample 2: N = 780 Prolific Academic participants stratified by sex and age to approximate a community-representative United States population. That is a development sample and not a community norm – no census weighting was applied and no raw-score to T-score table is published – so an interval from this function says where a score sits relative to the sample the instrument was developed on, and not what percentile it occupies in any population.
Two limitations worth stating. Equation (12)'s interval is symmetric
about the estimate and the same width for every respondent on a given scale,
which is what classical test theory implies and what the source computes. On
a floor-heavy scale that width can put a bound outside the response range,
and the bounds are not clamped, because clamping would report something
other than the equation this function cites. Every HiTOP-BR scale is
floor-heavy enough for this to bite: on all eight, a score of 1 – the
response floor – returns a lower bound below 1. And the coverage Schmukle
demonstrates is marginal: over a population of respondents drawn from the
reference distribution, about level of the intervals contain the true
score. It is established under a linear measurement model with
approximately normal item responses, so it is not a guarantee for any one
respondent, nor a demonstration on scales as skewed as these.
The 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, not as eight independent measurements.
Reporting and silence. Both things this function reports are warning
conditions, so a single suppressWarnings() call silences it and either
report can still be caught and tested for on its own.
A score column with no hitopbr_devstats row returns NA in all three
columns, with a warning of class hitop_interval_uncovered naming the
columns. A column is matched by stripping prefix and looking the rest up
in hitopbr_devstats$camelCase, so this fires for a mistyped prefix as
well as for a column that is not a HiTOP-BR scale score.
A call whose srange is not the c(1, 4) coding the reference mean and
standard deviation are printed on returns NA in every interval column,
with a warning of class hitop_interval_coding. Nothing is reconciled: a
shift or a stretch of the response range moves a scale score, and no
mapping from another coding onto these statistics is published.
Partly scored scales are not detected. A score computed from fewer than
a scale's full items – from data with items missing under
missing = "available" – is not on the same footing as the reference
statistics, which come from complete scales. This function receives scores
and not items, so it cannot tell such a column from a fully scored one and
does not try: it converts what it is given. Treat an interval on a partly
scored scale as not comparable to the reference group.
Errors. scores is checked before anything is converted. Naming the
same score column twice is an error rather than a duplicated set of output
columns, and a factor or character score column is an error rather than a
silent coercion – a factor's integer codes are not its scores, and a
character column would coerce to NA. Logical columns are accepted.
A scores argument that names no columns is an error, reported ahead of the
other selection arguments, so the cause named is the empty selection and
not a consequence of it. The condition is classed
hitop_empty_selection, so a caller can catch this refusal by name.
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.
A tibble with an _est, _lo and _hi column for
every requested score column, alongside all original data columns if
requested. An NA score returns NA in all three.
Schmukle, S. C. (2026). Unbiased confidence intervals for psychological testing: The regression-based true score approach with scale correction. Assessment, 33(5), 817-825. Equations (10) to (12), p. 821, are what this function computes; Box 1, p. 823, works two examples.
# Score the HiTOP-BR, then put an interval around two scales scored <- score_hitopbr(sim_hitopbr, items = 1:45) interval_hitopbr( scored, scores = c("hbr_detachment", "hbr_pFactor"), append = FALSE ) # A 90% interval is narrower interval_hitopbr( scored, scores = "hbr_detachment", level = 0.90, append = FALSE )# Score the HiTOP-BR, then put an interval around two scales scored <- score_hitopbr(sim_hitopbr, items = 1:45) interval_hitopbr( scored, scores = c("hbr_detachment", "hbr_pFactor"), append = FALSE ) # A 90% interval is narrower interval_hitopbr( scored, scores = "hbr_detachment", level = 0.90, append = FALSE )
Converts scored HiTOP-SR columns into a regression-based true-score estimate
and a confidence interval around it, using the development-sample mean,
standard deviation and reliability shipped as hitopsr_devstats. This
function converts already-scored columns and never rescores. It is built for
the 76 scale columns score_hitopsr() produces and for the 17 subscale
columns that score_hitopsr(include_subscales = TRUE) produces. Each
subscale column converts on its own subscale row of hitopsr_devstats.
interval_hitopsr( data, scores, srange = c(1, 4), prefix = "hsr_", level = 0.95, append = TRUE )interval_hitopsr( data, scores, srange = c(1, 4), prefix = "hsr_", level = 0.95, append = TRUE )
data |
A data frame containing scored HiTOP-SR columns. |
scores |
The score columns to convert, as column names or column
positions (mirroring the |
srange |
The response range the items were scored on, as
|
prefix |
The prefix |
level |
The confidence level, as a proportion between 0 and 1. Defaults
to |
append |
Whether to return the input |
What is computed. For a score on a scale whose reference
group has mean , standard deviation and reliability
, the estimate and bounds are Schmukle's (2026) Equations (10) to
(12), p. 821:
where is the two-sided standard normal quantile for level
(1.959964 at the default 0.95). The estimate is the observed score pulled
toward the reference mean, because with imperfect measurement a true score
tends to lie nearer the mean than the observed score does; the
factor is Schmukle's scale correction, which returns the
estimate to the metric the observed score is on so the two can be read
against each other.
The reference group is a development sample. hitopsr_devstats carries the statistics printed for the HiTOP-SR introduction paper's Development Sample 2: N = 780 Prolific Academic participants stratified by sex and age to approximate a community-representative United States population. That is a development sample and not a community norm – no census weighting was applied and no raw-score to T-score table is published – so an interval from this function says where a score sits relative to the sample the instrument was developed on, and not what percentile it occupies in any population.
Two limitations worth stating. Equation (12)'s interval is symmetric
about the estimate and the same width for every respondent on a given scale,
which is what classical test theory implies and what the source computes. On
a strongly skewed scale that width can put a bound outside the response
range – the floor of hsr_conversionSymptoms is one such case – and the
bounds are not clamped, because clamping would report something other
than the equation this function cites. And the coverage Schmukle
demonstrates is marginal: over a population of respondents drawn from the
reference distribution, about level of the intervals contain the true
score. It is established under a linear measurement model with
approximately normal item responses, so it is not a guarantee for any one
respondent, nor a demonstration on scales as skewed as the rarer HiTOP-SR
ones.
Reporting and silence. Both things this function reports are warning
conditions, so a single suppressWarnings() call silences it and either
report can still be caught and tested for on its own.
A score column with no hitopsr_devstats row returns NA in all three
columns, with a warning of class hitop_interval_uncovered naming the
columns. A column is matched by stripping prefix and looking the rest up
in hitopsr_devstats$camelCase, so this fires for a mistyped prefix as
well as for a scale the table does not carry.
A call whose srange is not the c(1, 4) coding the reference mean and
standard deviation are printed on returns NA in every interval column,
with a warning of class hitop_interval_coding. Nothing is reconciled: a
shift or a stretch of the response range moves a scale score, and no
mapping from another coding onto these statistics is published.
Partly scored scales are not detected. A score computed from fewer than
a scale's full items – from a module form, or from data with items missing
under missing = "available" – is not on the same footing as the reference
statistics, which come from complete scales. This function receives scores
and not items, so it cannot tell such a column from a fully scored one and
does not try: it converts what it is given. Treat an interval on a partly
scored scale as not comparable to the reference group.
Errors. scores is checked before anything is converted. Naming the
same score column twice is an error rather than a duplicated set of output
columns, and a factor or character score column is an error rather than a
silent coercion – a factor's integer codes are not its scores, and a
character column would coerce to NA. Logical columns are accepted.
A scores argument that names no columns is an error, reported ahead of the
other selection arguments, so the cause named is the empty selection and
not a consequence of it. The condition is classed
hitop_empty_selection, so a caller can catch this refusal by name.
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.
A tibble with an _est, _lo and _hi column for
every requested score column, alongside all original data columns if
requested. An NA score returns NA in all three.
Schmukle, S. C. (2026). Unbiased confidence intervals for psychological testing: The regression-based true score approach with scale correction. Assessment, 33(5), 817-825. Equations (10) to (12), p. 821, are what this function computes; Box 1, p. 823, works two examples.
# Score the HiTOP-SR, then put an interval around two scales scored <- score_hitopsr(sim_hitopsr, items = 1:405) interval_hitopsr( scored, scores = c("hsr_agoraphobia", "hsr_wellBeing"), append = FALSE ) # A 90% interval is narrower interval_hitopsr( scored, scores = "hsr_agoraphobia", level = 0.90, append = FALSE )# Score the HiTOP-SR, then put an interval around two scales scored <- score_hitopsr(sim_hitopsr, items = 1:405) interval_hitopsr( scored, scores = c("hsr_agoraphobia", "hsr_wellBeing"), append = FALSE ) # A 90% interval is narrower interval_hitopsr( scored, scores = "hsr_agoraphobia", level = 0.90, append = FALSE )
Real responses to items on the HiTOP-BR from University of Kansas students.
ku_hitopbrku_hitopbr
A tibble with 411 rows and 47 columns.
An anonymized id for each participant
A factor indicating each participant's biological sex
Responses on each item
ku_hitopbrku_hitopbr
Real responses to items on the HiTOP-SR from University of Kansas students.
ku_hitopsrku_hitopsr
A tibble with 411 rows and 407 columns.
An anonymized id for each participant
A factor indicating each participant's biological sex
Responses on each item
ku_hitopsrku_hitopsr
Real responses to items on the PID-5-SF (with 100 items) from University of Kansas students.
ku_pid5sfku_pid5sf
A tibble with 386 rows and 101 columns.
An anonymized id for each participant
Responses on each item
ku_pid5sfku_pid5sf
Add literal item text or clean scale names as attributes to data frame columns for the HiTOP Brief Report (HiTOP-BR), making them readable by data viewers and reporting packages.
label_hitopbr(data, target = c("items", "scales"), prefix = "hbr_")label_hitopbr(data, target = c("items", "scales"), prefix = "hbr_")
data |
A data frame containing HiTOP-BR items or scales. |
target |
A string specifying what to label: |
prefix |
A string specifying the prefix used on the column names. Item
columns are expected as the prefix followed by the item number zero-padded
to two digits ( |
A data frame with labeled columns. If no column matched the expected
names at all, data is returned unchanged and a warning of class
hitop_no_columns_matched says so; the hitop_unpadded_items report
still names every prefixed item column it found. Both classes may be
caught or suppressed by callers.
# Attach item text as a `label` attribute to the raw item columns labeled <- label_hitopbr(sim_hitopbr, target = "items") attr(labeled$hbr_01, "label")# Attach item text as a `label` attribute to the raw item columns labeled <- label_hitopbr(sim_hitopbr, target = "items") attr(labeled$hbr_01, "label")
Add literal item text or clean scale names as attributes to data frame columns, making them readable by data viewers and reporting packages.
label_hitopsr(data, target = c("items", "scales"), prefix = "hsr_")label_hitopsr(data, target = c("items", "scales"), prefix = "hsr_")
data |
A data frame containing HiTOP-SR items or scales. |
target |
A string specifying what to label: |
prefix |
A string specifying the prefix used on the column names. Item
columns are expected as the prefix followed by the item number zero-padded
to three digits ( |
A data frame with labeled columns. If no column matched the expected
names at all, data is returned unchanged and a warning of class
hitop_no_columns_matched says so; the hitop_unpadded_items report
still names every prefixed item column it found. Both classes may be
caught or suppressed by callers.
# Attach item text as a `label` attribute to the raw item columns labeled <- label_hitopsr(sim_hitopsr, target = "items") attr(labeled$hsr_001, "label")# Attach item text as a `label` attribute to the raw item columns labeled <- label_hitopsr(sim_hitopsr, target = "items") attr(labeled$hsr_001, "label")
Add literal item text or clean scale names as attributes to data frame columns, making them readable by data viewers and reporting packages.
label_pid5( data, target = c("items", "scales"), version = c("FULL", "SF", "BF", "BFPM", "IRF", "FFBF"), prefix = NULL )label_pid5( data, target = c("items", "scales"), version = c("FULL", "SF", "BF", "BFPM", "IRF", "FFBF"), prefix = NULL )
data |
A data frame containing PID-5 items or scales. |
target |
A string specifying what to label: |
version |
A string specifying the PID-5 form the columns belong to:
|
prefix |
A string specifying the prefix used on the column names.
Item columns are expected as the prefix followed by the item number
zero-padded to the width of the form's largest item number ( |
A data frame with labeled columns. Columns the named form does not
recognize keep whatever attributes they had. The validity-scale columns
validity_pid5() writes and the _se columns
score_pid5(calc_se = TRUE) writes are not labelled. If no column matched
the expected names at all, data is returned unchanged and a warning of
class hitop_no_columns_matched says so; the hitop_unpadded_items
report still names every prefixed item column it found. Both classes may
be caught or suppressed by callers.
Markon, K. E., Quilty, L. C., Bagby, R. M., & Krueger, R. F.
(2013). The Personality Inventory for DSM-5—Informant Form
(PID-5-IRF)—Adult. American Psychiatric Association. The source of the
informant wording that version = "IRF" labels items with. See also
Markon et al. (2013), Assessment, 20(3), 370-383.
doi:10.1177/1073191113486513
# Attach item text as a `label` attribute to the raw item columns labeled <- label_pid5(sim_pid5bf, target = "items", version = "BF") attr(labeled$pid5bf_01, "label")# Attach item text as a `label` attribute to the raw item columns labeled <- label_pid5(sim_pid5bf, target = "items", version = "BF") attr(labeled$pid5bf_01, "label")
Looks up scored PID-5 columns in the published normative tables shipped as
pid_norms and returns a T score and a percentile for each. Scores are
produced by score_pid5() and validity_pid5(); this function converts them
and never rescores.
norm_pid5( data, scores, version = c("FULL", "SF", "BF"), srange = c(0, 3), prefix = "pid_", append = TRUE )norm_pid5( data, scores, version = c("FULL", "SF", "BF"), srange = c(0, 3), prefix = "pid_", append = TRUE )
data |
A data frame containing scored PID-5 columns. |
scores |
The score columns to convert, as column names or column
positions (mirroring the |
version |
Which PID-5 version the scores came from: |
srange |
The response range the items were coded on, as
|
prefix |
The prefix |
append |
Whether to return the input |
For each named score column the tables are searched for the printed row whose raw score is nearest the observed value, and that one row's printed T score and printed percentile are returned. Nothing is interpolated: every returned number is a cell of Markon et al. (2024).
Markon et al. print the tables but give no instruction for reading them — no rounding, interpolation, or tie rule appears anywhere in the book — so the rules below are this package's, chosen and defended rather than quoted. They were settled by an independent review of the tables recorded in the package's development history as report RR02 (in the project repository, not the installed package).
Between printed rows. The nearer row wins. Printed raws step by 0.01-0.07 while attainable scores fall on much coarser grids (a 5-item brief-form domain mean can only be a multiple of 0.2), so most lookups land between rows.
Ties. Where two or more rows are equally near – a raw printed in several rows, or a value exactly midway between two rows – the row whose T score is nearest 50 is returned. The four validity scales carry no T score, so a tie there returns the row whose percentile is nearest 0.50.
Scores of 0. Nearly every tabled scale prints raw 0.00 across a run of low T scores, because the linear T the book tabulated predicts a negative raw there and 0.00 is printed instead. The tie rule returns the run's highest T, the one row of the run that renders an attainable score. (Two columns – full-form detachment and risk taking – print 0.00 just once, so no tie arises there.) Its printed percentile is positive on some scales and 0.00 on others; that asymmetry is a property of the published tables, not of this function.
Scores outside the table. A score above the highest printed raw
returns whatever an observation at that raw returns, rather than an
extrapolation – the last printed row on most scales, but the lowest-T
row of the run where the top raw is printed several times (see
"Unattainable printed rows" below). A score below
the lowest returns whatever an observation at the lowest printed raw
returns – which, on the scales whose tables print a run of 0.00, is that
run's highest-T row and not the table's first row, so the two agree
instead of jumping. A warning reports how many observations were capped
at each end. This is reachable in ordinary data: PRD is a 22-item sum
reaching 66 while its table stops at 55.
Unattainable printed rows. 47 of the 66 tabled scales print rows above the 3.00 ceiling a 0-3 item mean can reach – five domain scales and 42 of the 50 facet columns – so the top of those T ranges cannot be attained. A maximum score returns T = 84 (brief-form negative affectivity), 87 (brief-form detachment), 93 (brief-form disinhibition), 87 (full-form negative affectivity), 85 (short-form negative affectivity), or, on a facet, a T between 76 and 98 depending on the facet and the form – each at percentile 1.00. Nineteen facet columns go further and print the same top raw, 4.00, on several consecutive T rows (12 of them for short-form anxiousness); those rows ship as published, and the tie rule above returns the lowest T of the run. Nothing is wrong with such data and nothing is reported.
Comparison tolerance. All comparisons use an absolute tolerance of 1e-8, so that scores on grids with no exact binary representation (a short-form domain mean is a twelfth) match the printed 2-decimal raws as intended.
Columns the tables do not cover for the requested version – SD-TD, or
any facet on the brief form, for instance – return NA in both conversion
columns with a warning naming them. An NA score returns NA.
Reporting and silence. Everything this function reports – the capping
count above, the uncovered-column warning, and the two response-coding
reports below – is a warning condition, so a single suppressWarnings()
call silences the function and any one report can still be caught and
tested for individually.
Errors. scores is checked before anything is converted. Naming the
same score column twice is an error rather than a duplicated pair of output
columns, and a factor or character score column is an error rather than a
silent coercion – a factor's integer codes are not its scores, and a
character column would coerce to NA. Logical columns are accepted, since
a 0/1 indicator converts as it reads.
A scores argument that names no columns is an error, reported ahead of the
other selection arguments, so the cause named is the empty selection and
not a consequence of it. The condition is classed
hitop_empty_selection, so a caller can catch this refusal by name.
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.
Response coding. The normative tables are built on the official
four-option 0-3 coding. Data collected on a four-option coding that merely
starts elsewhere – 1-4, say – carries the same information, so each score
is reconciled to the official range before lookup and the conversion
proceeds. A coding with a different number of options is a different
metric: no mapping onto a four-option norm table is defined, so every
conversion column is returned as NA with a warning, and the items must be
recoded and rescored.
How much a shift moves a score depends on how the scale is computed, so the reconciliation is applied per scale rather than per item. No published source states these rules – Markon et al. give the tables for the official coding only – so, like the reading rules above, they are this package's, derived from each scale's own definition:
Item means (the 25 facets, the five domains, and the brief form's
total) are
reconciled by subtracting srange[[1]]. Shifting every item by a constant
shifts their mean by the same constant.
PRD is a plain sum over its 22 items, so the same shift moves it by
srange[[1]] times the number of items, which is what is subtracted. The
item count is read from pid_items rather than assumed.
INC and INC-S are sums of absolute differences within item
pairs. A constant added to both members of a pair cancels in the
difference, so these are unchanged by a shift and nothing is subtracted.
ORS is a count of items answered at the top of the response range –
validity_pid5() computes it by comparing each item to srange[[2]]
rather than to a fixed value (R/validity_pid5.R:153 in the package
sources). A shift moves the top of the range along with the answers, so
the same items are counted and the score is unchanged.
A shifted coding raises one warning per call naming which of the requested scales were adjusted and which were left alone; where every requested scale turns out to be coding-invariant, it says so rather than claiming an adjustment. The warning covers the scales the tables actually carry, so a request the tables cover nowhere raises the coverage warning above instead and nothing about coding. The official coding is silent.
One consequence is worth stating plainly, because it can put two differently
grounded numbers side by side in the same session: validity_pid5()'s
published cut scores are not reconciled to a shifted coding. PRD and
SD-TD are compared against fixed thresholds that assume 0-3 items, and
validity_pid5() warns rather than adapting them. So a respondent scored on
a 1-4 coding can receive a reconciled percentile from this function and, from
validity_pid5(), a validity flag still read against the 0-3 thresholds.
Adapting those cut scores is a separate, deliberately deferred question.
A tibble with a _t column for every converted scale
whose normative rows carry a T score (the five domains, the 25 facets of
the full and short forms, and the brief form's total) and a _ptl column
for every converted scale, alongside all original data columns if
requested. The four validity scales (INC, INCS, ORS, PRD) are
distributed as percentiles only and get no _t column.
Markon, K. E., Fossati, A., Somma, A., & Krueger, R. F. (2024). Understanding the Personality Inventory for DSM-5 (PID-5). American Psychiatric Association Publishing. The normative tables in pid_norms, Appendix "Normative Score Distributions" (pp. 113-219), are the source for every value this function returns.
# Score the brief form, then convert its domains and total scored <- score_pid5(sim_pid5bf, items = 1:25, version = "BF") norm_pid5(scored, scores = paste0("pid_", c("detachment", "total")), version = "BF", append = FALSE)# Score the brief form, then convert its domains and total scored <- score_pid5(sim_pid5bf, items = 1:25, version = "BF") norm_pid5(scored, scores = paste0("pid_", c("detachment", "total")), version = "BF", append = FALSE)
The map from each of the 6 domains of the PID5BF+M (the 36-item modified
brief form of the PID-5) to its 3 facets, used to compute the domain scores
of score_pid5(version = "BFPM") and the domain rows of
reliability_pid5(version = "BFPM"). Each domain score is the mean of its 3
facet scores (Bach et al., 2020). The rows are in the order of the form's
key, with Anankastia fifth.
pid_bfpm_domainspid_bfpm_domains
A tibble with 6 rows and 4 columns, the columns of pid_domains:
Name of the domain. The five domains the form shares with the PID-5 are spelled as in pid_domains
The domain name in camel case (the score-output column stem)
A list column of the 3 facet names per domain, as
pid_scales$BFPM$Facet spells them
A list column of those 3 facet names in camel case (the facet score-output column stems)
Bach, B., Kerber, A., Aluja, A., Bastiaens, T., Keeley, J. W., Claes, L., Fossati, A., Gutierrez, F., Oliveira, S. E. S., Pires, R., Riegel, K. D., Rolland, J.-P., Roskam, I., Sellbom, M., Somma, A., Spanemberg, L., Strus, W., Thimm, J. C., Wright, A. G. C., & Zimmermann, J. (2020). International assessment of DSM-5 and ICD-11 personality disorder traits: Toward a common nosology in DSM-5.1. Psychopathology, 53(3-4), 179-188. doi:10.1159/000507589
The keying itself is transcribed from the form's coding scheme: Kerber, A. (2020). Persönlichkeitsinventar für DSM-5 und ICD-11: Kurzform Modifiziert (PID5BF+ M) [Questionnaire and coding scheme, German]. Freie Universität Berlin, p. 2.
pid_bfpm_domainspid_bfpm_domains
The map from each of the 5 PID-5 personality-trait domains to the 3 facets
contributing primarily to it, used to compute domain scores for the FULL, SF
and IRF versions (APA scoring keys, Step 3; the PID-5 Informant Form's Domain
Table names the same primary facets). This is the 15-facet primary subset,
not the broader pid_items$Domain grouping.
pid_domainspid_domains
A tibble with 5 rows and 4 columns:
Name of the domain (matches pid_items$Domain)
The domain name in camel case (the score-output column stem)
A list column of the 3 primary facet names per domain
A list column of those 3 facet names in camel case (the facet score-output column stems)
pid_domainspid_domains
The map from each of the 7 domains that score_pid5(version = "FFBF")
returns to its 3 facets. The first 5 rows are the APA domains of
pid_domains, each the mean of its 3 primary facets (Niemeyer et al.,
2022, p. 33). The last 2 rows are the domains of the paper's four-factor
solution that are not APA domains, Disinhibited Aggression and Insecurity,
with the facets of the authors' analysis code. The paper's four-factor
Antagonism and Detachment have the facets of the APA domains of the same
names, so they are not repeated.
pid_ffbf_domainspid_ffbf_domains
A tibble with 7 rows and 4 columns, the columns of pid_domains:
Name of the domain. The APA domains are spelled as in pid_domains and the two forensic domains as the paper prints them
The domain name in camel case (the score-output column stem)
A list column of the 3 facet names per domain
A list column of those 3 facet names in camel case (the facet score-output column stems)
Niemeyer, L. M., Grosz, M. P., Zimmermann, J., & Back, M. D. (2022). Journal of Personality Assessment, 104(1), 30-43. doi:10.1080/00223891.2021.1923522. The four-factor domain facets are from the authors' analysis code on the paper's OSF project (https://osf.io/m42gn/).
pid_ffbf_domainspid_ffbf_domains
The 100 items of the PID-5 Forensic Faceted Brief Form (PID-5-FFBF), an
adaptation of the PID-5 faceted short form for people in prison, with self-
and informant-report versions in English and German. Most items are
rewritten for the prison setting, so they have their own table rather than
columns of pid_items. The form was validated in German. Its English text
is the authors' English version, from Table S3, and the study validated
only the German version (Niemeyer et al., 2022, p. 40). Items they did not
adapt keep the APA PID-5 wording. Scored by score_pid5(version = "FFBF").
pid_ffbf_itemspid_ffbf_items
A tibble with 100 rows and 7 columns:
Item number on the PID-5-FFBF (integer)
Name of the PID-5 facet, spelled as in pid_items$Facet. Each
facet has 4 items: facet k, in alphabetical order, holds items k, k + 25,
k + 50, and k + 75
Whether the item needs to be reverse scored (items 12 and 26)
Self-report item text, English
Informant-report item text, English, without a subject (Table S3 prints each with a leading ellipsis)
Self-report item text, German
Informant-report item text, German, without a subject
The texts are those of Table S3 of the form's supplement, without its source notes, its reverse marks, the stray markers E14, E18 and E77, a leading ellipsis, or the final period, and with straight quotes and apostrophes (including an acute accent used as an apostrophe in item 50). Hyphens inside German words are removed, and English words split at a hyphen across a line are joined with the hyphen kept. The printed wording is otherwise kept, typos included.
Niemeyer, L. M., Grosz, M. P., Zimmermann, J., & Back, M. D. (2022). Assessing maladaptive personality in the forensic context: Development and validation of the Personality Inventory for DSM-5 Forensic Faceted Brief Form (PID-5-FFBF). Journal of Personality Assessment, 104(1), 30-43. doi:10.1080/00223891.2021.1923522. Item text from its supplement, Table S3 (https://osf.io/fzyvr/): Copyright 2013 American Psychiatric Association, German version 2015, developed with permission from Hogrefe and the APA.
pid_ffbf_itemspid_ffbf_items
Information about the items in different versions of the PID-5.
pid_itemspid_items
A tibble with 220 rows and 18 columns:
Item number on the full PID-5, PID-5 faceted short form, and PID-5 brief form (integer)
Item number on the PID5BF+M, the 36-item modified brief form (integer). Its keying is in pid_scales$BFPM and pid_bfpm_domains
Item number on the PID-5 Informant Form, the 218-item
informant-report form (integer). It is NA on self-report items 96 and
177, which the informant form does not have, so IRF item n is self-report
item n, n + 1 or n + 2. Each informant item shares its row's facet and
reverse keying
Whether the item needs to be reverse scored
Item number on the response inconsistency scale full and short forms (integer)
Item number on the overreporting scale full and short forms (integer)
Item number on the positive impression management response distortion scale full and short forms (integer)
Item number on the social desirability-total denial scale full and short forms (integer)
Name of the PID-5 facet. The PID5BF+M regroups six of the
Rigid Perfectionism items into its three anankastia facets, whose item
membership is held only in pid_scales$BFPM
Name of the domain
Item text, copyright APA
Informant Form item text, copyright APA, from Markon, K. E., Quilty, L. C., Bagby, R. M., & Krueger, R. F. (2013), The Personality Inventory for DSM-5—Informant Form (PID-5-IRF)—Adult, American Psychiatric Association. Each item completes the stem "He or she..."; this column does not include the stem, the leading ellipsis or the final period, and uses straight quotes and apostrophes
pid_itemspid_items
Published normative score distributions for the PID-5, PID-5-SF, and PID-5-BF, in long form: the raw score and percentile at each T score for the five domain scales, the 25 facet (trait) scales of the full and short forms, and the brief form's total score; and the percentile at each raw score for the validity scales, which are tabled without T scores.
pid_normspid_norms
A tibble with 4606 rows and 5 columns:
The PID-5 version the row norms: "FULL", "SF", or "BF"
Name of the scale, as the score-output column stem used by
score_pid5() and validity_pid5() (i.e., without their prefix), so a
lookup joins to scored output with no crosswalk. Every scale normed here is
produced by one of those two functions, the brief form's "total"
included (see score_pid5())
The T score, or NA for the validity scales, whose tables
print none
The raw scale score, on the metric score_pid5() and
validity_pid5() return: for the FULL and SF domains, the mean of the
three primary facet scores (themselves item means, and the facets differ
in length, so this is not a mean over the domain's items); for the FULL and
SF facets and for the BF domains and total, a mean item response; for the
validity scales, an item sum. 42 of the 50 facet columns print raws above
the 3.00 a mean of 0-3 items can reach, up to 4.00, and 19 of those repeat
their top raw across consecutive T scores; all such rows ship as published
and are simply unattainable (see norm_pid5())
The percentile of the normative distribution at that score, as a proportion between 0 and 1
The INC and INCS scales are called the Variable Response
Inconsistency (VRIN) scale by Markon et al. (2024), so a reader coming from
the book will find those tables here under the package's own names.
Markon et al. call the 25 facets trait scales; they are tabled under the book's own captions, which the package maps onto the pid_scales facet names.
Norms come from a sample of 1,082 individuals from a U.S. Census-matched panel. The validity-scale distributions use all 1,082; the FULL and SF domain and facet distributions use the 995 respondents who scored below 17 on the inconsistency scale, left no more than a quarter of responses missing, and did not endorse both infrequency items. The source states no separate sample size for the brief form tables. All T scores and percentiles were computed with sampling weights reflecting U.S. Census data.
The published informant-form tables are not included.
Markon, K. E., Fossati, A., Somma, A., & Krueger, R. F. (2024). Understanding the Personality Inventory for DSM-5 (PID-5). American Psychiatric Association Publishing. Appendix, Tables A-1 to A-9 (pp. 113-219).
pid_normspid_norms
Information about the scales (facets) in different versions of the PID-5,
used by score_pid5() to map each scale to its item numbers. It is also read
by reliability_pid5() and by the printed scoring table in
generate_docx_pid5*(), so adding or removing a row changes all three.
pid_scalespid_scales
A named list of length 6 (elements FULL, SF, BF,
BFPM, IRF, and FFBF), one per PID-5 version. Each element is a
tibble with one row per scale and 5 columns:
Domain in the BF element)Name of the scale: the
facet for the FULL, SF, BFPM, IRF, and FFBF versions, the domain for the BF
version. The BF element carries a sixth row, Total, which is not a
domain but the whole 25-item form scored as one scale (see
score_pid5()). The BFPM element holds the 18 facets of the PID5BF+M, 2
items each, grouped by domain in the order of its key; its domains are in
pid_bfpm_domains. The IRF element holds the 25 facets of the Informant
Form in the FULL element's order, numbered by informant item, with the
informant text in itemdata. The FFBF element holds the 25 facets of the
PID-5 Forensic Faceted Brief Form in the SF element's order, numbered by
FFBF item, with the English self-report text in itemdata; its items are
in pid_ffbf_items and its domains in pid_ffbf_domains
A list column containing one item-data tibble per scale; its item-number column is an integer
The number of items in the scale (integer)
A list column containing one integer item-number vector per scale
The name of the scale converted to camel case (the score-output column stem)
pid_scales[["BF"]]pid_scales[["BF"]]
Renders one respondent's normed PID-5 scores as a profile against the published normative tables in pid_norms. The plot presents scores against norms and characterizes none of them: it carries no severity bands, no elevation thresholds, and no annotation about what a score means. Judging a profile is the clinician's job, not this package's.
plot_pid5( data, version = c("FULL", "SF", "BF"), level = c("domain", "facet"), metric = c("t", "percentile"), labels = TRUE, prefix = "pid_" )plot_pid5( data, version = c("FULL", "SF", "BF"), level = c("domain", "facet"), metric = c("t", "percentile"), labels = TRUE, prefix = "pid_" )
data |
A data frame with exactly one row, carrying the |
version |
Which PID-5 version the scores came from: |
level |
Which scales to plot. |
metric |
Which normed metric to plot: |
labels |
Whether to label each point with its rounded value. |
prefix |
The column-name prefix used when the scores were computed, as
passed to |
Each plotted scale gets a point at its normed value, labelled with that
value just to its right (set labels = FALSE to drop the labels), and the
points are joined by a profile line. A single reference line
marks the normative sample's midpoint – T = 50, or the 50th percentile.
Both are definitional properties of the metrics themselves rather than
thresholds this package chose.
The score axis spans the range the normative tables actually print for the plotted scales, so the axis does not rescale from respondent to respondent and two profiles on the same version and level are directly comparable. Scales are listed top to bottom in the order their scoring table gives them, under their printed names rather than their column stems.
On the brief form the profile line stops before total: the total is an
overall elevation across the five domains rather than a sixth domain, so
joining it to the profile line would imply a comparability it does not have.
The point itself is still plotted.
A scale whose normed value is NA – because the respondent's items were
missing, or because the score fell outside what could be converted – is
dropped from the profile with a warning naming it, and the remaining scales
are still plotted. A scale whose column is absent from data altogether is
an error rather than a warning: it means data was not normed at the level
being plotted.
A ggplot object. Print it to draw the profile, or add further ggplot2 layers to restyle it.
Markon, K. E., Fossati, A., Somma, A., & Krueger, R. F. (2024). Understanding the Personality Inventory for DSM-5 (PID-5). American Psychiatric Association Publishing. The normative tables in pid_norms, Appendix "Normative Score Distributions" (pp. 113-219), supply every value and every axis bound this function draws.
score_pid5() to compute the scores, norm_pid5() to convert them
against the normative tables, and pid_norms for the tables themselves.
# Score, norm, and plot one respondent's brief-form domain profile scored <- score_pid5(sim_pid5bf[1, ], items = 1:25, version = "BF") normed <- norm_pid5(scored, scores = paste0("pid_", pid_scales[["BF"]]$camelCase), version = "BF") plot_pid5(normed, version = "BF")# Score, norm, and plot one respondent's brief-form domain profile scored <- score_pid5(sim_pid5bf[1, ], items = 1:25, version = "BF") normed <- norm_pid5(scored, scores = paste0("pid_", pid_scales[["BF"]]$camelCase), version = "BF") plot_pid5(normed, version = "BF")
For each row of selected scale columns, return a comma-separated string of
the top highest (or lowest) scale names, optionally removing a common
prefix from the column names and optionally appending the result to
the original data as a tibble.
rank_scales( data, scales, prefix = NULL, top = 5, dir = "high", reverse = NULL, srange = NULL, name = "top_scales", append = TRUE )rank_scales( data, scales, prefix = NULL, top = 5, dir = "high", reverse = NULL, srange = NULL, name = "top_scales", append = TRUE )
data |
A data frame containing the scale columns. |
scales |
A character or integer vector identifying the columns in
|
prefix |
A length-1 string giving a leading string to strip from each
selected column name before concatenation, or |
top |
Integer (length 1). The number of columns to include per row after
ranking. Must be between 1 and |
dir |
Direction of ranking: |
reverse |
A subset of |
srange |
A numeric vector of length 2 giving the minimum and maximum of
the scale scores, used to reflect the |
name |
A length-1 string giving the name of the output column holding the
ranked-scale strings. (default = |
append |
Logical. If |
Ranking is performed row-wise using order() on the selected
columns. Ties are resolved by the original column order (the default
behavior of order). Missing values are placed last by order() and
will be included only if there are fewer than top non-missing values
in a row.
If prefix is not NULL, the function removes that exact leading
string from each selected column name before concatenation. Names that do not
begin with it are carried through whole.
The output column is named by name. When append = TRUE it is
added after the existing columns of data (whose order is preserved);
when append = FALSE the result is a one-column tibble.
Errors. A scales argument that names no columns is an error, reported
ahead of the other selection arguments, so the cause named is the empty
selection and not a consequence of it. The condition is classed
hitop_empty_selection, so a caller can catch this refusal by name.
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.
A tibble. If append = TRUE, it is data
with an added character column named by name. If append =
FALSE, it is a one-column tibble (named by name) whose values are
the comma-separated ranked scale names, one per row of data.
# List each respondent's 3 highest-scoring HiTOP-BR scales scored <- score_hitopbr(sim_hitopbr, items = 1:45, append = FALSE) rank_scales(scored, scales = names(scored), prefix = "hbr_", top = 3, append = FALSE)# List each respondent's 3 highest-scoring HiTOP-BR scales scored <- score_hitopbr(sim_hitopbr, items = 1:45, append = FALSE) rank_scales(scored, scales = names(scored), prefix = "hbr_", top = 3, append = FALSE)
Reads the CSV files that the hitop-form web page saves, one file per participant, or the CSV download of a store the page sends to, one row per participant, and binds them into one tibble that the scoring functions take as it is. The page is at https://jmgirard.github.io/hitop-form/.
read_form_responses(path)read_form_responses(path)
path |
A directory that holds the response files, or a character
vector of paths to them. A directory is read as every file in it whose
name ends in |
A file the page saves holds one header row and one response row.
A store's download, such as a Google Sheet's CSV export or a Supabase
table's, holds one header row and one row per participant. Every response
row of every file is a row of the result, the files in path order and the
rows in file order. The first eight columns of the result are study,
participant, instrument, form_build, submitted, item_order,
prolific_study and prolific_session. The item columns follow from the
ninth, one per item, named by the instrument's file
stem and the item number (hitopsr_001, hitopbr_01, pid5_001,
pid5sf_001, pid5bf_01). A module form saves only the module's items.
The page keeps the item columns in the order it showed the items, except
under a study link that asks for a random order: the page then draws a
new order for each participant, keeps the item columns in the
instrument's order (a module's items in the order its descriptor lists
them, which write_module() writes ascending and the page requires
ascending), and writes item_order.
form_build is the build date of the instrument's export the page
showed, as YYYY-MM-DD. The result keeps each cell as written, so the
column is character. Convert it with as.Date() when you need a date
and the file holds one instrument.
Several instruments in one file. A file's item columns may form two
or more groups, one per instrument. The columns of each group sit side
by side and hold one stem, and no stem appears in two groups. The
optional lead columns and the answer columns may sit anywhere after
submitted, between two groups or inside one, and they do not split a
group. The instrument cell holds the stems in the order of the groups,
joined by single spaces (hitopbr pid5bf). The form_build cell holds
one date per stem, in the same order, joined by single spaces
(2026-09-20 2026-09-18). The result holds the item columns in file
order. Score each instrument in its own call, with its columns chosen by
stem, as grep("^pid5bf_", names(responses), value = TRUE) chooses the
PID-5-BF's. The hitop-form page writes such a file for a study link
whose instruments field lists two or three instruments.
item_order is the order the participant saw the items, as item numbers
with no leading zero, joined by single spaces with none at either end
(hitopbr_01 is 1). In a file of several instruments it holds one group
per stem, in the order of the instrument cell, joined by a space, a bar
and a space (2 1 | 3 1 2), each group that instrument's item numbers
in the order shown. The page writes it under a random order and not
otherwise. A file may hold the column
anywhere after submitted, as a store's download may append it after the
item columns, and the result places it sixth. A file may also lack it:
its rows then hold NA there. Scoring does not read the column, and it is
not an item column, so it does not enter the check that every file holds
the same item columns. A cell that is not blank and does not list the
file's item numbers, each once, in one group per stem, is an error
naming the file and the response row. A group does not name its stem,
so the reader cannot tell two groups apart when their instruments hold
the same item numbers: swapped, they read as written.
prolific_study and prolific_session hold the study and session
identifiers that Prolific adds to a study link, when the file records
them for a study recruited through Prolific. The hitop-form page writes
them when the link builder's recruiting site is Prolific, and then takes
the participant identifier from the Prolific ID in the page's address.
Under another recruiting site (SONA, CloudResearch Connect) the page
takes the identifier from that site's address parameter into
participant and writes no further column. A file may hold
either or both anywhere after submitted, and the result places
prolific_study seventh and prolific_session eighth. A row from a file
without a column holds NA in it, and so does a blank cell. Scoring does
not read them, and they are not item columns, so neither enters the
check that every file holds the same item columns. The cells are read as
written, with no check on their content.
A column whose name starts with q_ is an answer column: it holds the
answer to a question of the researcher's own, named q_ and then the
question's name (q_age). A file may hold answer columns
anywhere after submitted, and the result places them after the item
columns. They come in the order the reader first meets them, with the
files in path order and each file read from left to right. Each is
character, read as written with no conversion, and a blank cell is NA.
Files that hold different answer columns read together, and a row from a
file without a column holds NA in it. Answer columns are not item
columns, so they do not enter the check that every file holds the same
item columns. After q_, a name must hold a lower-case letter and then
up to 29 lower-case letters, digits or underscores, the pattern
^q_[a-z][a-z0-9_]{0,29}$. A name that starts with q_ and does not
match is an error naming the file and the column.
Every file must carry the same item columns in the same order, because
a set of files that differ cannot be one data frame: a full HiTOP-SR
beside a module, or two modules that shuffled their items differently,
need separate calls. A file that does not look like one the page saved
is an error naming the file: a UTF-16 or UTF-32 file (described below), a
line holding a NUL byte or a byte
sequence that is not UTF-8, a line outside a quoted cell made only of
spaces and tabs, no header row (a zero-byte file, blank
lines only, a UTF-8 byte-order mark only), first columns other than the five
the page writes first, a column that appears twice, a header with no
response row, a response row holding fewer or more fields than the
header, an answer column whose name does not match the pattern above, an
item column whose name is not a stem of lower-case letters
and digits, an underscore and the item number (hitopbr_01, not foo
or Hitopbr_01), a stem whose columns another stem's columns split
(hitopbr_01, pid5bf_01, hitopbr_02), an instrument cell that
differs from the item columns' stems in file order (pid5bf beside
hitopbr_01, or hitopbr beside hitopbr_01 and pid5bf_01), an
item value that is not a whole number or is outside R's integer range,
a form_build cell whose date count differs from the stem count, or a
date that does not parse. An error on a line names the lines at fault,
counted from the file's first line. An error on a row names the response
rows at fault,
counted from the first row after the header. An error on an item value
names each cell at fault as its response row, its column and the value
as written, the first five cells and a count of the rest. The errors on
a NUL byte or a byte sequence that is not UTF-8, on a line of spaces and
tabs, on a row's field count and on an instrument cell likewise name
the first five lines or rows at fault and a count of the rest. The error
on a UTF-16 or UTF-32 file names the encoding and no line, and asks that
the file be saved as UTF-8. A file that starts with the byte-order mark
FF FE 00 00 or 00 00 FE FF is taken as UTF-32, and one that starts with
FF FE or FE FF as UTF-16. A file with no mark is read as UTF-32 and then
as UTF-16, each little-endian and then big-endian. In each encoding the
lines are split on that encoding's line feed. Empty lines and lines of a
lone carriage return at the top are skipped. The first line that is not
blank then has its trailing carriage return dropped. If it holds only
printable ASCII characters and tabs, the file is taken as that encoding.
A file of blank lines only in one of these encodings is also taken as
that encoding when it holds at least one line feed. A file taken as
UTF-32 is refused as UTF-32, not as UTF-16. A UTF-16 or UTF-32 file the
rule does not take is read as UTF-8, and a NUL byte in it meets the
byte error.
The field
count of a row reads # as data and a quoted cell holding a line break
as one cell, as the read does. A submitted stamp may carry fractional
seconds.
Errors. Files whose item columns differ from the first file's in
name, in count or in order stop the read under the condition class
hitop_form_responses_mismatch, and the message names each file that
differs and how. A directory holding no .csv file stops it under
hitop_form_responses_none. Both classes are a public contract a caller
can catch by name.
A tibble with one row per response row. The first
eight columns are study, participant, instrument and form_build
as character, submitted as POSIXct in UTC, and item_order,
prolific_study and prolific_session as character, each NA on a row
from a file without that column and on a blank cell. The item columns
follow as integers, in the column order of the first file after sorting.
An item the participant left blank is NA. The answer columns, when any
file holds one, come last as character, in order of first appearance,
each NA on a row from a file without it and on a blank cell.
score_hitopsr(), score_hitopbr(), score_pid5() and
read_module(), which score the item columns; the Collecting Responses
Online article walks the Google Sheet route from the study link to the
scores, and the modules article and vignette("pid5_scoring") show the
hand-off for a module and for the PID-5.
# Two files as the page saves them, here written by hand. dir <- tempfile("responses") dir.create(dir) writeLines( c("study,participant,instrument,form_build,submitted,hitopbr_01,hitopbr_02", "demo,p001,hitopbr,2026-09-20,2026-09-20T21:20:36Z,4,1"), file.path(dir, "demo_p001.csv") ) writeLines( c("study,participant,instrument,form_build,submitted,hitopbr_01,hitopbr_02", "demo,p002,hitopbr,2026-09-20,2026-09-21T09:02:11Z,2,"), file.path(dir, "demo_p002.csv") ) responses <- read_form_responses(dir) responses unlink(dir, recursive = TRUE)# Two files as the page saves them, here written by hand. dir <- tempfile("responses") dir.create(dir) writeLines( c("study,participant,instrument,form_build,submitted,hitopbr_01,hitopbr_02", "demo,p001,hitopbr,2026-09-20,2026-09-20T21:20:36Z,4,1"), file.path(dir, "demo_p001.csv") ) writeLines( c("study,participant,instrument,form_build,submitted,hitopbr_01,hitopbr_02", "demo,p002,hitopbr,2026-09-20,2026-09-21T09:02:11Z,2,"), file.path(dir, "demo_p002.csv") ) responses <- read_form_responses(dir) responses unlink(dir, recursive = TRUE)
Reads a module descriptor written by write_module() (or
written by hand to the same format) and returns the hitop_module()
object it describes, ready to pass to score_hitopsr(),
reliability_hitopsr(), or any of the generators.
The file never supplies keying. The module is rebuilt by passing the
file's scales through hitop_module(), so this package's own tables
remain the only source of which items belong to a scale. The file's
recorded items and nItems, where present, are checked against that
rebuild, and a disagreement is an error: a descriptor written against
scale tables that have since moved fails loudly rather than scoring
quietly.
read_module(file)read_module(file)
file |
A string giving the path to read from. |
A hitop_module object with integer items. This is also true for a
file written from the deprecated hitop_subset class, or from a module
whose items are doubles. If the file carries an itemOrder, it is
returned on the object's item_order attribute — the same attribute
generate_docx_hitopsr() returns for a shuffled form. Pass the module to
score_hitopsr() or reliability_hitopsr() with layout = "printed" to
score columns entered in that printed order. If the file carries
columns, the names are returned as a character vector on the object's
columns attribute. A bare JSON string reads as one name. Pass the module
to score_hitopsr() or reliability_hitopsr() with items omitted to
score the columns it names. A file with no columns, or with
"columns": null, gives a module with no such attribute.
Every failure below aborts with a condition naming the file, so a caller
may catch a particular one by class: hitop_module_file_missing,
hitop_module_file_invalid_json, hitop_module_file_missing_field,
hitop_module_file_unsupported_format, hitop_module_file_unknown_scales
(which carries hitop_module()'s own refusal as its parent),
hitop_module_file_items_mismatch, hitop_module_file_bad_item_order,
and hitop_module_file_bad_columns.
The list is exhaustive by design: a descriptor that is malformed rather
than merely wrong — a top level that is a JSON array instead of an
object, or a number field that is not a flat array of numbers — is
refused as hitop_module_file_invalid_json or as the mismatch condition
for the field it spoils, never as a bare R coercion error.
In items, nItems, and itemOrder, every value must be a JSON number
with a whole value. A JSON string, a JSON boolean, or a number such as
12.4 is refused, even where it would convert to the right item number.
A JSON null inside an array is also refused. items and nItems raise
hitop_module_file_items_mismatch, and itemOrder raises
hitop_module_file_bad_item_order. A whole number written as 2.0 or
3e0 is accepted. A field whose whole value is JSON null reads as
absent.
columns raises hitop_module_file_bad_columns when it is an object or
a number, when an element is not a non-empty JSON string, when it holds
a different number of names than the module has items, or when it
repeats a name.
The file is JSON, with these fields:
formatThe format version, a "major.minor" string. This
release writes "1.0".
package, packageVersion, buildDate
The package that wrote
the file, its version, and the date it was written. Recorded for the
reader; read_module() ignores all three.
instrumentThe instrument the module belongs to.
scalesThe module's scales, as they are printed on the instrument. Required: these are what the module is rebuilt from.
items, nItems
The original instrument item numbers the module
covers, and how many there are. write_module() writes them in
ascending order, and the hitop-form web page requires that order,
refusing a descriptor whose items are not ascending. Cross-checked
on read: read_module() compares them as a set, so their order
carries no meaning to it, but a repeated number is an error, and the
printed order of a shuffled form belongs in itemOrder instead.
itemOrderThe printed order of a shuffled form: a permutation
of items. Optional — a form printed in instrument order carries
none. read_module() returns it on the module's item_order
attribute, the same attribute generate_docx_hitopsr() returns, and
write_module() writes it back from that attribute, so a descriptor
read and written again keeps the order it recorded. The generators'
descriptor argument sets the attribute for you, and
score_hitopsr() and reliability_hitopsr() read it under
layout = "printed" to score columns entered in the form's printed
order.
columnsThe names that an online export gives the module's
items: one string per item, in ascending item-number order.
Optional. generate_redcap_hitopsr()'s descriptor writes the
dictionary's item field names here, and
generate_qualtrics_hitopsr()'s writes the questions' [[ID:]]
values. A Word form has no columns, so
its descriptor has no field. read_module() returns the field on the
module's columns attribute, and write_module() writes it back
from that attribute as a JSON array. score_hitopsr() and
reliability_hitopsr() use the attribute as items when items is
omitted.
format, instrument, and scales are required. A reader of format
"1.0" ignores a field it does not know, so release 0.2.0, the first
with read_module(), and later releases read a file with columns and
ignore the field. The fields and the
version string are a public contract and change only deliberately.
write_module() to write the file; hitop_module() to build a
module without one.
m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss")) f <- tempfile(fileext = ".json") write_module(m, f) m2 <- read_module(f) m2 identical(m2, m) file.remove(f)m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss")) f <- tempfile(fileext = ".json") write_module(m, f) m2 <- read_module(f) m2 identical(m2, m) file.remove(f)
Compute per-scale internal-consistency reliability — Cronbach's alpha and
McDonald's omega — for the HiTOP Brief-Report (45 items). Reliability is
estimated on the item responses for each of the scales that score_hitopbr()
outputs (the HiTOP-BR has no reverse-keyed items).
reliability_hitopbr(data, items, srange = c(1, 4), alpha = TRUE, omega = TRUE)reliability_hitopbr(data, items, srange = c(1, 4), alpha = TRUE, omega = TRUE)
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; duplicated entries are an error.
Each column must be numeric or logical, or character holding only
numbers (blank cells and |
srange |
An optional numeric vector specifying the minimum and maximum
values of the HiTOP-BR items, used for reverse-coding. (default = |
alpha |
Optional logical; if |
omega |
Optional logical; if |
Alpha is computed by calc_alpha() (covariance-based, pairwise
deletion) and omega by calc_omega() (one-factor lavaan CFA, FIML). A scale
whose estimate cannot be computed (e.g. too few items or, for omega, a
non-converging CFA or an uninstalled lavaan) is returned as NA
rather than aborting the call. Omega needs at least 3 items: for a scale
with fewer, no model is fitted and omega is NA. The overlapping externalizing and pFactor
scales are included alongside the six base spectra.
A tibble with one row per scale and columns Scale
(the scale's canonical display name, as the instrument's keying table spells
it), camelCase (the stem that names the scale's column in the matching
score_*() output, read from the same keying-table row), nItems
(integer), and (when requested) alpha and omega.
# Per-scale alpha for the HiTOP-BR reliability_hitopbr(sim_hitopbr, items = 1:45, omega = FALSE)# Per-scale alpha for the HiTOP-BR reliability_hitopbr(sim_hitopbr, items = 1:45, omega = FALSE)
Compute per-scale internal-consistency reliability — Cronbach's alpha and
McDonald's omega — for the HiTOP Self-Report (405 items). Reliability is
estimated on the reverse-keyed item responses for each of the scales that
score_hitopsr() outputs and, with include_subscales = TRUE, for each of
its 17 subscales (fewer under a module).
reliability_hitopsr( data, items, srange = c(1, 4), alpha = TRUE, omega = TRUE, module = NULL, layout = c("instrument", "printed"), include_subscales = FALSE, subset = NULL )reliability_hitopsr( data, items, srange = c(1, 4), alpha = TRUE, omega = TRUE, module = NULL, layout = c("instrument", "printed"), include_subscales = FALSE, subset = NULL )
data |
A data frame containing the HiTOP-SR items (numerically coded):
all 405 of them, or, when |
items |
A vector of column names (as strings) or numbers (as integers)
corresponding to the HiTOP-SR items held in |
srange |
An optional numeric vector specifying the minimum and maximum
values of the HiTOP-SR items, used for reverse-coding. (default = |
alpha |
Optional logical; if |
omega |
Optional logical; if |
module |
An optional |
layout |
The order the item columns are in. |
include_subscales |
A logical. If |
subset |
Deprecated. The former name of |
Alpha is computed by calc_alpha() (covariance-based, pairwise
deletion) and omega by calc_omega() (one-factor lavaan CFA, FIML). A scale
whose estimate cannot be computed (e.g. too few items or, for omega, a
non-converging CFA or an uninstalled lavaan) is returned as NA
rather than aborting the call. Omega needs at least 3 items: for a scale
with fewer, no model is fitted and omega is NA.
A tibble with one row per scale (and per subscale
under include_subscales = TRUE) and columns Scale
(the scale's canonical display name, as the instrument's keying table spells
it), camelCase (the stem that names the scale's column in the matching
score_*() output, read from the same keying-table row), nItems
(integer), and (when requested) alpha and omega.
# Per-scale alpha for the HiTOP-SR reliability_hitopsr(sim_hitopsr, items = 1:405, omega = FALSE) # Per-scale alpha for 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)] reliability_hitopsr(collected, items = names(collected), module = m, omega = FALSE) # The same for 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)] reliability_hitopsr(printed, items = seq_along(printed), module = m, layout = "printed", omega = FALSE)# Per-scale alpha for the HiTOP-SR reliability_hitopsr(sim_hitopsr, items = 1:405, omega = FALSE) # Per-scale alpha for 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)] reliability_hitopsr(collected, items = names(collected), module = m, omega = FALSE) # The same for 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)] reliability_hitopsr(printed, items = seq_along(printed), module = m, layout = "printed", omega = FALSE)
Compute per-scale internal-consistency reliability — Cronbach's alpha and
McDonald's omega — for the Personality Inventory for DSM-5: full version
(PID-5, 220 items), short form (PID-5-SF, 100 items), brief form (PID-5-BF,
25 items), modified brief form (PID5BF+M, 36 items), Informant Form
(PID-5-IRF, 218 items; Markon et al., 2013), or Forensic Faceted Brief Form
(PID-5-FFBF, 100 items; Niemeyer et al., 2022). Reliability is
estimated on the reverse-keyed item responses, at the facet level for
FULL/SF/IRF/FFBF and the domain level for BF (the same scales score_pid5()
outputs, before FULL/SF/IRF/FFBF domain aggregation). The FFBF facets are its
25 four-item facets in the SF's order (see score_pid5()). The IRF facets are the full
form's 25, numbered by informant item and reverse-keyed as the APA IRF key's
Facet Table marks (see score_pid5()). The BF version also returns a Total row
covering all 25 items; note that this scale spans five heterogeneous domains,
so its internal consistency is not comparable to a domain's and is reported
without further interpretation.
reliability_pid5( data, items, version = c("FULL", "SF", "BF", "BFPM", "IRF", "FFBF"), srange = c(0, 3), alpha = TRUE, omega = TRUE )reliability_pid5( data, items, version = c("FULL", "SF", "BF", "BFPM", "IRF", "FFBF"), srange = c(0, 3), alpha = TRUE, omega = TRUE )
data |
A data frame containing (at least) all the PID items (numerically scored and in order). |
items |
A vector of column names (as strings) or numbers (as integers)
corresponding to the PID items in order. Items must be supplied in
instrument order; duplicated entries are an error.
Each column must be numeric or logical, or character holding only
numbers (blank cells and |
version |
A string indicating the version of the PID to score: "FULL",
"SF", "BF", "BFPM" (the 36-item PID5BF+M), "IRF" (the 218-item
Informant Form), or "FFBF" (the 100-item Forensic Faceted Brief Form).
Only a full name is accepted, in any letter case. Any other value, a
start of a name such as |
srange |
An optional numeric vector specifying the minimum and maximum
values of the items, used for reverse-coding. (default = |
alpha |
Optional logical; if |
omega |
Optional logical; if |
The BFPM version returns both levels: its 18 two-item facets, then its 6
domains, each estimated over the 6 items of its 3 facets (the map is in
pid_bfpm_domains). Omega is NA for every facet, because a one-factor
model of 2 items is not identified; alpha is reported for all 24 rows.
Alpha is computed by calc_alpha() (covariance-based, pairwise
deletion) and omega by calc_omega() (one-factor lavaan CFA, FIML). A scale
whose estimate cannot be computed (e.g. too few items or, for omega, a
non-converging CFA or an uninstalled lavaan) is returned as NA
rather than aborting the call. Omega needs at least 3 items: for a scale
with fewer, no model is fitted and omega is NA.
A tibble with one row per scale and columns Scale
(the scale's canonical display name, as the instrument's keying table spells
it), camelCase (the stem that names the scale's column in the matching
score_*() output, read from the same keying-table row), nItems
(integer), and (when requested) alpha and omega.
Markon, K. E., Quilty, L. C., Bagby, R. M., & Krueger, R. F.
(2013). The development and psychometric properties of an informant-report
form of the Personality Inventory for DSM-5 (PID-5). Assessment, 20(3),
370-383. doi:10.1177/1073191113486513 The scoring key for
version = "IRF" is the APA's The Personality Inventory for
DSM-5—Informant Form (PID-5-IRF)—Adult (2013).
Niemeyer, L. M., Grosz, M. P., Zimmermann, J., & Back, M. D.
(2022). Assessing maladaptive personality in the forensic context:
Development and validation of the Personality Inventory for DSM-5
Forensic Faceted Brief Form (PID-5-FFBF). Journal of Personality
Assessment, 104(1), 30-43. doi:10.1080/00223891.2021.1923522 The
source of version = "FFBF".
# Facet-level reliability for the full PID-5 (alpha only) reliability_pid5(sim_pid5, items = 1:220, version = "FULL", omega = FALSE)# Facet-level reliability for the full PID-5 (alpha only) reliability_pid5(sim_pid5, items = 1:220, version = "FULL", omega = FALSE)
Rename data frame columns to standard HiTOP-SR item names based on either legacy ("Original") variable names or item text matching.
rename_hitopsr_items( data, method = c("original", "text"), item_cols = NULL, item_text = NULL, prefix = "hsr_" )rename_hitopsr_items( data, method = c("original", "text"), item_cols = NULL, item_text = NULL, prefix = "hsr_" )
data |
A data frame containing the HiTOP-SR items. |
method |
A string specifying the matching method: |
item_cols |
An optional character vector of current column names to
be renamed. Required if |
item_text |
An optional character vector of item texts corresponding
exactly to the columns specified in |
prefix |
A string pasted literally before each standardized item
number, which is zero-padded to three digits: |
A data frame with renamed column names for the matched HiTOP-SR
items. Inputs that could not be matched keep their names, and each of the
three warnings this function raises carries a condition class callers may
catch or suppress by. Under method = "original", if no column matches a
legacy name, nothing is renamed and the report is
hitop_no_columns_matched. Under method = "text", an item_text entry
matching no item is skipped and named in a hitop_unmatched_items report.
Under either method, if some but not all of the 405 items were renamed,
the completeness report is hitop_incomplete_rename.
# Rename legacy item-pool columns to standard HiTOP-SR item names legacy <- head(hitopsr_items$Original, 3) df <- as.data.frame(matrix(0, nrow = 2, ncol = 3, dimnames = list(NULL, legacy))) names(rename_hitopsr_items(df, method = "original"))# Rename legacy item-pool columns to standard HiTOP-SR item names legacy <- head(hitopsr_items$Original, 3) df <- as.data.frame(matrix(0, nrow = 2, ncol = 3, dimnames = list(NULL, legacy))) names(rename_hitopsr_items(df, method = "original"))
Rename data frame columns to the standard PID-5 item names of one form,
matching either on the item number carried in the current column name or on
the literal item prompt text. The standard names are the ones the package's
REDCap and Qualtrics exports write and the shipped datasets carry:
pid5_001 to pid5_220 for the full form, pid5sf_001 to pid5sf_100 for
the short form, and pid5bf_01 to pid5bf_25 for the brief form. The
PID5BF+M names, pid5bfpm_01 to pid5bfpm_36, the Informant Form names,
pid5irf_001 to pid5irf_218, and the Forensic Faceted Brief Form names,
pid5ffbf_001 to pid5ffbf_100, follow the same pattern.
rename_pid5_items( data, version = c("FULL", "SF", "BF", "BFPM", "IRF", "FFBF"), method = c("number", "text"), item_cols = NULL, item_text = NULL, from_prefix = "pid_", prefix = NULL )rename_pid5_items( data, version = c("FULL", "SF", "BF", "BFPM", "IRF", "FFBF"), method = c("number", "text"), item_cols = NULL, item_text = NULL, from_prefix = "pid_", prefix = NULL )
data |
A data frame containing the PID-5 items. |
version |
A string specifying the PID-5 form the items belong to:
|
method |
A string specifying the matching method: The forms number their items independently, so |
item_cols |
An optional character vector of current column names to
be renamed. Required if |
item_text |
An optional character vector of item texts corresponding
exactly to the columns specified in |
from_prefix |
A string matched literally at the start of a column name
under |
prefix |
A string pasted literally before each standardized item
number, which is zero-padded to the width of the form's largest item
number. |
A data frame with renamed column names for the matched PID-5 items.
Columns that could not be matched keep their names. Under
method = "number", a column spelled like an item of the instrument whose
number names no item of this form, and under method = "text", an
item_text entry matching no item of this form, are skipped and named in
a warning of class hitop_unmatched_items, which callers may catch or
suppress by class. A column not spelled like an item number is left alone
and not reported.
Two other warnings carry a class of their own. Under method = "number",
if no column at all is named from_prefix followed by a number, nothing
is renamed and the report is hitop_no_columns_matched. Under either
method, if some but not all of the form's items were renamed, the
completeness report is hitop_incomplete_rename.
Under method = "text", a call in which two columns match the same item
is an error of class hitop_duplicate_item_match, since both would take
the same name. The message names the item and the columns. For the FFBF
this happens when a data frame holds two texts of one item, for example
its self-report and informant texts, or its English and German texts.
Rename each form's columns in its own data frame, or give each call its
own prefix.
Markon, K. E., Quilty, L. C., Bagby, R. M., & Krueger, R. F.
(2013). The Personality Inventory for DSM-5—Informant Form
(PID-5-IRF)—Adult. American Psychiatric Association. The source of the
informant wording that version = "IRF" matches under
method = "text". See also Markon et al. (2013), Assessment, 20(3),
370-383. doi:10.1177/1073191113486513
# Rename columns named as this package's datasets were before the rename df <- data.frame(pid_1 = c(0, 1), pid_2 = c(2, 3), age = c(30, 40)) names(suppressWarnings(rename_pid5_items(df, version = "FULL")))# Rename columns named as this package's datasets were before the rename df <- data.frame(pid_1 = c(0, 1), pid_2 = c(2, 3), age = c(30, 40)) names(suppressWarnings(rename_pid5_items(df, version = "FULL")))
Create a data frame with scores on all the HiTOP-BR scales.
score_hitopbr( data, items, srange = c(1, 4), prefix = "hbr_", missing = c("available", "complete"), calc_se = FALSE, append = TRUE )score_hitopbr( data, items, srange = c(1, 4), prefix = "hbr_", missing = c("available", "complete"), calc_se = FALSE, append = TRUE )
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 |
srange |
An optional numeric vector specifying the minimum and maximum
values of the HiTOP-BR items, used for reverse-coding. (default = |
prefix |
An optional string to add before each scale column name. If no
prefix is desired, set to an empty string |
missing |
A string selecting how missing item responses are handled when
computing scale scores. |
calc_se |
Deprecated. This argument, and the |
append |
An optional logical indicating whether the new columns should
be added to the end of the |
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.
A tibble containing all scale scores and standard
errors (if requested) and all original data columns (if requested).
# Score all HiTOP-BR scales from the simulated data score_hitopbr(sim_hitopbr, items = 1:45, append = FALSE)# Score all HiTOP-BR scales from the simulated data score_hitopbr(sim_hitopbr, items = 1:45, append = FALSE)
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).
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 )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 )
data |
A data frame containing the HiTOP-SR items (numerically coded):
all 405 of them, or, when |
items |
A vector of column names (as strings) or numbers (as integers)
corresponding to the HiTOP-SR items held in |
srange |
An optional numeric vector specifying the minimum and maximum
values of the HiTOP-SR items, used for reverse-coding. (default = |
prefix |
An optional string to add before each scale column name. If no
prefix is desired, set to an empty string |
missing |
A string selecting how missing item responses are handled when
computing scale scores. |
calc_se |
Deprecated. This argument, and the |
append |
An optional logical indicating whether the new columns should
be added to the end of the |
module |
An optional |
layout |
The order the item columns are in. |
include_subscales |
A logical. If |
subset |
Deprecated. The former name of |
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.
A tibble containing all scale scores, subscale scores
(if requested with include_subscales), standard errors (if requested)
and all original data columns (if requested).
# Score all HiTOP-SR scales from the simulated data score_hitopsr(sim_hitopsr, items = 1:405, append = FALSE) # Score the 17 subscales too; their columns follow the 76 scale columns score_hitopsr(sim_hitopsr, items = 1:405, include_subscales = TRUE, append = FALSE) # 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) # 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)# Score all HiTOP-SR scales from the simulated data score_hitopsr(sim_hitopsr, items = 1:405, append = FALSE) # Score the 17 subscales too; their columns follow the 76 scale columns score_hitopsr(sim_hitopsr, items = 1:405, include_subscales = TRUE, append = FALSE) # 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) # 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)
Calculate scale scores on the Personality Inventory for DSM-5: full version (PID-5, 220 items), short form version (PID-5-SF, 100 items), brief form version (PID-5-BF, 25 items), modified brief form (PID5BF+M, 36 items; Bach et al., 2020), Informant Form (PID-5-IRF, 218 items; Markon et al., 2013), or Forensic Faceted Brief Form (PID-5-FFBF, 100 items; Niemeyer et al., 2022) from item-level data.
score_pid5( data, items, version = c("FULL", "SF", "BF", "BFPM", "IRF", "FFBF"), srange = c(0, 3), prefix = "pid_", missing = c("apa", "available", "complete"), calc_se = FALSE, append = TRUE )score_pid5( data, items, version = c("FULL", "SF", "BF", "BFPM", "IRF", "FFBF"), srange = c(0, 3), prefix = "pid_", missing = c("apa", "available", "complete"), calc_se = FALSE, append = TRUE )
data |
A data frame containing (at least) all the PID items (numerically scored and in order). |
items |
A vector of column names (as strings) or numbers (as integers)
corresponding to the PID 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 |
version |
A string indicating the version of the PID to score: "FULL",
"SF", "BF", "BFPM" (the 36-item PID5BF+M), "IRF" (the 218-item
Informant Form), or "FFBF" (the 100-item Forensic Faceted Brief Form).
Only a full name is accepted, in any letter case. Any other value, a
start of a name such as |
srange |
An optional numeric vector specifying the minimum and maximum
values of the items, used for reverse-coding. (default = |
prefix |
An optional string to add before each scale column name. If no
prefix is desired, set to an empty string |
missing |
A string selecting how missing item responses are handled when
computing scale scores. |
calc_se |
Deprecated. This argument, and the |
append |
An optional logical indicating whether the new columns should
be added to the end of the |
For the FULL, SF and IRF versions, the output includes the 25 facet
scores followed by the 5 personality-trait domain scores; the FFBF version
adds 2 forensic domains after them (see below). Following the APA
scoring key (Step 3), each domain score is the mean of the average scores of
its 3 primary facets (the map is stored in pid_domains). The BF version
scores its 5 domains directly from its items, and adds a total score. By
default (missing = "apa") all versions apply the APA missing-data and
proration rule; use missing = "available" or missing = "complete" for
the traditional rowMeans() behaviors. For per-scale reliability estimates
(Cronbach's alpha, McDonald's omega), use reliability_pid5().
version = "BFPM" scores the PID5BF+M of Bach et al. (2020), a 36-item
form with 6 domains: the 5 PID-5 trait domains and Anankastia. Every item
is a PID-5 item, and none is reverse-keyed. The output
is 18 facets of 2 items each, then 6 domains, in the order of the form's
key: Negative affectivity, Detachment, Antagonism, Disinhibition,
Anankastia and Psychoticism. Each domain score is the mean of its 3 facet
scores (the map is stored in pid_bfpm_domains). The 15 facets the form
shares with the PID-5 keep their PID-5 column names. The three Anankastia
facets are perfectionism, rigidity and orderliness. All six of their
items are PID-5 Rigid Perfectionism items, but these facets are not parts
of rigidPerfectionism, which this version does not score.
Scores are item means on the 0 to 3 scale, as for the other versions. The
form's published key sums the 2 items of a facet and averages the facet
sums for a domain. On complete data, the key's facet sum is
2 * pid_<facet> and its domain score is 2 * pid_<domain>.
No missing-data rule is published for this form. Under the default
missing = "apa", the 25% rule applied to a 2-item facet means that any
missing item makes the facet NA, and an NA facet makes its domain
NA. So with whole-number responses "apa" gives the same output as
"complete" here. (The APA rule rounds each scale's sum, so responses
with decimals can differ.) Under missing = "available", a facet can be
scored from one item and a domain from one or two of its facets.
version = "IRF" scores the PID-5 Informant Form (PID-5-IRF; Markon et
al., 2013), the APA's 218-item form on which an informant rates the person
receiving care. Its output is the FULL version's: the same 25 facets and 5
domains, with the same column names and domain map (pid_domains). The
form has no counterpart to self-report items 96 and 177, so its
Anxiousness facet has 8 items and its Suspiciousness facet 6. Informant
item n is self-report item n through 95, n + 1 through 175, and n + 2
after that; pid_items$IRF holds the mapping and pid_items$TextIRF the
informant wording.
Fourteen items are reverse-scored: 7, 30, 35, 58, 87, 90, 96, 97, 130, 141, 154, 163, 208 and 213, the items the key's Facet Table marks R. The key's Step 1 also lists items 98 and 176, which the Facet Table does not mark and whose wording is not reversed; the package does not reverse them.
The key prints its proration step as "round up to the nearest whole
number". The package applies the nearest-whole-number rule of every other
APA PID-5 key, with a prorated half rounded away from zero (see
missing). For a non-negative prorated raw score, the choice matters
only under missing = "apa", for a facet with at least one but no more
than 25% of its items unanswered whose prorated raw score has a
fractional part strictly between 0 and one half. There the package's
facet score is 1/n lower than a ceiling would give, for a facet of n
items. Under a negative srange a negative prorated raw score can also
differ from a ceiling at other fractions.
Informant scores have the full form's column names, and nothing in the
output records the version. Do not pass them to norm_pid5() or
plot_pid5() as version = "FULL": those use self-report norms, and the
informant norms (Markon et al., 2024, Tables A–10 and A–11) are not in
pid_norms. validity_pid5() has no informant validity scales.
version = "FFBF" scores the PID-5 Forensic Faceted Brief Form
(PID-5-FFBF; Niemeyer et al., 2022), an adaptation of the 100-item faceted
short form for people in prison, with a self-report and an informant
version. The form was validated in German. The English text in
pid_ffbf_items is the authors' English version, and the study
validated only the German version (p. 40). Items they did not adapt keep
the APA PID-5 wording. Many items are rewritten for prisoners, and the
authors numbered the form afresh, so its items are not the SF's: matched by number, 98 of the
100 SF items fall in a different facet. Facet k, in alphabetical
order, holds items k, k + 25, k + 50 and k + 75. Items 12 and 26 are
reverse-scored.
The output is 25 facets, named and ordered as the SF's, then 7 domains: the 5 APA domains of pid_domains and the two domains of the paper's four-factor solution that are not APA domains, Disinhibited Aggression (Emotional Lability, Hostility, Impulsivity) and Insecurity (Separation Insecurity, Anxiousness, Perceptual Dysregulation). The paper's four-factor Antagonism and Detachment have the facets of the APA domains of the same names, so they are not repeated. pid_ffbf_domains holds the map. The four-factor structure comes from one exploratory study of 199 male prisoners, and the authors leave open whether Insecurity is needed (Niemeyer et al., 2022, p. 39). The seven domains share facets, so they are not independent scores.
Missing data. The paper prints no missing-data rule. Under
missing = "apa" the package applies the full-form APA rule, as it does
for the SF: a facet with 1 of its 4 items missing is prorated and
rounded, a facet with 2 or more missing is NA, and a domain with an
NA facet is NA. The authors' published analysis code scores
differently. It takes the unrounded mean of the answered items for a
facet with 1 item missing, and it scores a domain as the mean of its 12
items when up to 3 of them are missing, wherever they fall. With complete
data the two rules agree. With missing items a facet can differ by up to
1/12 (for example 1.75 here against 1.67 for answers 0, 2 and 3), and a
domain can be NA here where the code gives a value. The paper's
descriptive statistics were computed under the code's rule. No missing
mode reproduces it.
Informant reports. Informant data are scored with the same version.
The paper averaged the responses of two informants item by item before
scoring (p. 33), and the authors' code uses one informant's response
where the other is missing; do that step first, for example with
rowMeans(cbind(x1, x2), na.rm = TRUE) for each item, then set an item
that both informants skipped (NaN from that call) to NA. Averaged responses
can be halves, and they score like any other values. Under
missing = "apa" the proration step rounds them too: a facet with one
item missing and answers 0.5, 1 and 1 scores 0.75, where
missing = "available" gives 0.833. One informant's responses score
directly.
norm_pid5(), plot_pid5() and validity_pid5() do not take the FFBF,
because no FFBF norms or validity keys are published. The FFBF facet and
APA domain columns carry the SF's names, so norm_pid5() converts them
as version = "SF" with no version warning and plot_pid5() plots the
result; do not do that, as it compares them with SF self-report norms
from another population.
version = "FULL" scores the APA's 220-item PID-5 child form for ages 11
to 17, and version = "BF" scores its 25-item PID-5-BF child form
(Krueger et al., 2013). The child forms print the adult forms' items in
the same order, and their keys reverse the same items and assign them to
the same facets and domains. So no separate version is needed, and data
collected with
generate_docx_pid5child(), generate_qualtrics_pid5child() or
generate_redcap_pid5child() (or their pid5bfchild counterparts) score
as adult data do. pid_norms holds no child norms, so norm_pid5() and
plot_pid5() would compare child scores with norms from another
population. The child forms print no validity scales, and no source on
this package's shelf gives validity cut scores for them, so the cut
scores validity_pid5() applies are not established for child data.
version = "BF" returns a total column after its 5 domains. Markon et al.
(2024, p. 23) define it as the item-level mean over all 25 items, not
the mean of the 5 domain means: the total "can be computed by averaging the
overall score by the total number of items in the measure (i.e., 25)". With
five equal-sized domains the two definitions coincide on complete data and
differ only when items are missing, where the published rule above governs.
The total is scored like any other scale, so missing applies to it at the
25-item level. Under missing = "apa" that means it is NA when more than
a quarter of the 25 items are unanswered (7 or more) and prorated otherwise,
independently of the domains. Because a 5-item domain is dropped at 2
unanswered items while the total tolerates 6, a total can be reported
alongside one or more NA domains (at most 3 of the 5; blanking all five
requires 10 unanswered items, which blanks the total as well). This is the
published rule applied as written, not an oversight.
The FULL, SF, IRF, FFBF and BFPM versions have no total score: the PID-5 book defines one only for the brief form, and the PID5BF+M, PID-5-IRF and PID-5-FFBF sources define none.
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.
A tibble containing all scale scores and standard
errors (if requested) and all original data columns (if requested)
Krueger, R. F., Derringer, J., Markon, K. E., Watson, D., & Skodol, A. E. (2012). Initial construction of a maladaptive personality trait model and inventory for DSM-5. Psychological Medicine, 42, 1879-1890. doi:10.1017/s0033291711002674
Anderson, J. L., Sellbom, M., & Salekin, R. T. (2016). Utility of the Personality Inventory for DSM-5-Brief Form (PID-5-BF) in the measurement of maladaptive personality and psychopathology. Assessment, 25(5), 596–607. doi:10.1177/1073191116676889
Markon, K. E., Fossati, A., Somma, A., & Krueger, R. F. (2024).
Understanding the Personality Inventory for DSM-5 (PID-5). American
Psychiatric Association Publishing. The source for the PID-5-BF total
score's definition (p. 23) and for the normative tables in pid_norms.
Maples, J. L., Carter, N. T., Few, L. R., Crego, C., Gore, W. L., Samuel, D. B., Williamson, R. L., Lynam, D. R., Widiger, T. A., Markon, K. E., Krueger, R. F., & Miller, J. D. (2015). Testing whether the DSM-5 personality disorder trait model can be measured with a reduced set of items: An item response theory investigation of the personality inventory for DSM-5. Psychological Assessment, 27(4), 1195–1210. doi:10.1037/pas0000120
Bach, B., Kerber, A., Aluja, A., Bastiaens, T., Keeley, J. W., Claes, L., Fossati, A., Gutierrez, F., Oliveira, S. E. S., Pires, R., Riegel, K. D., Rolland, J.-P., Roskam, I., Sellbom, M., Somma, A., Spanemberg, L., Strus, W., Thimm, J. C., Wright, A. G. C., & Zimmermann, J. (2020). International assessment of DSM-5 and ICD-11 personality disorder traits: Toward a common nosology in DSM-5.1. Psychopathology, 53(3-4), 179-188. doi:10.1159/000507589 The source of the PID5BF+M.
Markon, K. E., Quilty, L. C., Bagby, R. M., & Krueger, R. F. (2013). The development and psychometric properties of an informant-report form of the Personality Inventory for DSM-5 (PID-5). Assessment, 20(3), 370-383. doi:10.1177/1073191113486513
Markon, K. E., Quilty, L. C., Bagby, R. M., & Krueger, R. F.
(2013). The Personality Inventory for DSM-5—Informant Form
(PID-5-IRF)—Adult. American Psychiatric Association. The scoring key for
version = "IRF".
Niemeyer, L. M., Grosz, M. P., Zimmermann, J., & Back, M. D. (2022). Assessing maladaptive personality in the forensic context: Development and validation of the Personality Inventory for DSM-5 Forensic Faceted Brief Form (PID-5-FFBF). Journal of Personality Assessment, 104(1), 30-43. doi:10.1080/00223891.2021.1923522 The source of the PID-5-FFBF, its items (supplement Table S3) and its domains.
Krueger, R. F., Derringer, J., Markon, K. E., Watson, D., &
Skodol, A. E. (2013). The Personality Inventory for DSM-5 (PID-5)—Child
Age 11–17 and The Personality Inventory for DSM-5—Brief Form
(PID-5-BF)—Child Age 11–17. American Psychiatric Association. The child
forms that version = "FULL" and version = "BF" also score.
# Score the full PID-5 (25 facets + 5 domains) from the simulated data score_pid5(sim_pid5, items = 1:220, version = "FULL", append = FALSE) # Short form, using the item column names instead of positions score_pid5(sim_pid5sf, items = sprintf("pid5sf_%03d", 1:100), version = "SF", append = FALSE) # Brief form (5 domains + the total) with standard errors. `calc_se` is # deprecated, so this call warns; the PID-5 has no interval function to # replace it with. score_pid5(sim_pid5bf, items = 1:25, version = "BF", calc_se = TRUE, append = FALSE) # PID5BF+M (18 facets + 6 domains). No BF+M dataset ships, but every BF+M # item is a PID-5 item, so take its 36 items from the full-form data in # BF+M order. bfpm_rows <- pid_items[!is.na(pid_items$BFPM), ] bfpm_rows <- bfpm_rows[order(bfpm_rows$BFPM), ] sim_bfpm <- sim_pid5[sprintf("pid5_%03d", bfpm_rows$FULL)] score_pid5(sim_bfpm, items = 1:36, version = "BFPM", append = FALSE) # PID-5 Informant Form (25 facets + 5 domains). No informant dataset ships; # for illustration, take the 218 full-form items the informant form maps to. irf_rows <- pid_items[!is.na(pid_items$IRF), ] sim_irf <- sim_pid5[sprintf("pid5_%03d", irf_rows$FULL)] score_pid5(sim_irf, items = 1:218, version = "IRF", append = FALSE) # PID-5-FFBF (25 facets + 7 domains). No FFBF dataset ships; for # illustration, simulate answers to its 100 items. set.seed(1) sim_ffbf <- as.data.frame(matrix(sample(0:3, 500, replace = TRUE), 5, 100)) score_pid5(sim_ffbf, items = 1:100, version = "FFBF", append = FALSE)# Score the full PID-5 (25 facets + 5 domains) from the simulated data score_pid5(sim_pid5, items = 1:220, version = "FULL", append = FALSE) # Short form, using the item column names instead of positions score_pid5(sim_pid5sf, items = sprintf("pid5sf_%03d", 1:100), version = "SF", append = FALSE) # Brief form (5 domains + the total) with standard errors. `calc_se` is # deprecated, so this call warns; the PID-5 has no interval function to # replace it with. score_pid5(sim_pid5bf, items = 1:25, version = "BF", calc_se = TRUE, append = FALSE) # PID5BF+M (18 facets + 6 domains). No BF+M dataset ships, but every BF+M # item is a PID-5 item, so take its 36 items from the full-form data in # BF+M order. bfpm_rows <- pid_items[!is.na(pid_items$BFPM), ] bfpm_rows <- bfpm_rows[order(bfpm_rows$BFPM), ] sim_bfpm <- sim_pid5[sprintf("pid5_%03d", bfpm_rows$FULL)] score_pid5(sim_bfpm, items = 1:36, version = "BFPM", append = FALSE) # PID-5 Informant Form (25 facets + 5 domains). No informant dataset ships; # for illustration, take the 218 full-form items the informant form maps to. irf_rows <- pid_items[!is.na(pid_items$IRF), ] sim_irf <- sim_pid5[sprintf("pid5_%03d", irf_rows$FULL)] score_pid5(sim_irf, items = 1:218, version = "IRF", append = FALSE) # PID-5-FFBF (25 facets + 7 domains). No FFBF dataset ships; for # illustration, simulate answers to its 100 items. set.seed(1) sim_ffbf <- as.data.frame(matrix(sample(0:3, 500, replace = TRUE), 5, 100)) score_pid5(sim_ffbf, items = 1:100, version = "FFBF", append = FALSE)
Simulated responses to items on the HiTOP-BR (with 45 items). Note that this is a naive simulation where response options 1 to 4 are all equally likely and generated independently per item. Thus, responses are not clustered within scales, and these data can be used (eventually) to test validity tools intended to detect inconsistent/random responding.
sim_hitopbrsim_hitopbr
A tibble with 100 rows and 45 columns.
Responses on each item
sim_hitopbrsim_hitopbr
Simulated responses to items on the full HiTOP-SR (with 405 items). Note that this is a naive simulation where response options 1 to 4 are all equally likely and generated independently per item. Thus, responses are not clustered within scales, and these data can be used (eventually) to test validity tools intended to detect inconsistent/random responding.
sim_hitopsrsim_hitopsr
A tibble with 100 rows and 405 columns.
Responses on each item
sim_hitopsrsim_hitopsr
Simulated responses to items on the full PID-5 (with 220 items).
sim_pid5sim_pid5
A tibble with 100 rows and 220 columns.
Responses on each item
sim_pid5sim_pid5
Simulated responses to items on the PID-5-BF (with 25 items).
sim_pid5bfsim_pid5bf
A tibble with 100 rows and 25 columns.
Responses on each item
sim_pid5bfsim_pid5bf
Simulated responses to items on the PID-5-SF (with 100 items).
sim_pid5sfsim_pid5sf
A tibble with 100 rows and 100 columns.
Responses on each item
sim_pid5sfsim_pid5sf
Calculate validity scale scores on the Personality Inventory for DSM-5: full version (PID-5, 220 items), short form version (PID-5-SF, 100 items), or brief form version (PID-5-BF, 25 items) from item-level data and return alerts when when observations meet criteria for invalidity.
validity_pid5( data, items, version = c("FULL", "SF", "BF"), srange = c(0, 3), prefix = "pid_", append = TRUE )validity_pid5( data, items, version = c("FULL", "SF", "BF"), srange = c(0, 3), prefix = "pid_", append = TRUE )
data |
A data frame containing (at least) all the PID items (numerically scored and in order). |
items |
A vector of column names (as strings) or numbers (as integers)
corresponding to the PID 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 |
version |
A string indicating the version of the PID to score: "FULL",
"SF", or "BF". Only a full name is accepted, in any letter case. Any
other value, a start of a name such as |
srange |
An optional numeric vector specifying the minimum and maximum
values of the items, used for reverse-coding. (default = |
prefix |
An optional string to add before each scale column name. If no
prefix is desired, set to an empty string |
append |
An optional logical indicating whether the new columns should
be added to the end of the |
For the full PID-5, a score of 17 or higher on the INC is indicative of inconsistent responding. A score of 3 or higher on the ORS is indicative of overreporting. A score of 10 or lower on the PRD is indicative of positive impression management (underreporting rather than genuine responding) whereas a score of 21 or higher on the PRD is indicative of genuine responding (rather than positive impression management). A score of 11 or lower on the SD-TD is indicative of social desirability (rather than defensiveness), whereas a score of 19 or higher on the SD-TD is indicative of defensiveness (rather than social desirability). For the PID-5-SF, scores of 8 or more on the INC-S are indicative of inconsistent responding. Cut-scores for the ORS-S, PRD-S, and SD-TD-S have not yet been validated.
The PRD and SD-TD cut scores are raw sums compared to fixed thresholds that
assume items are coded 0-3. Unlike the INC and ORS scales, they do not adapt
to srange, so scoring items on another scale (e.g. 1-4) mis-flags
respondents; a warning is issued when srange is not c(0, 3). The BF
version computes only the percent-missing (PNA) index and no cut-score
scales.
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 and
the srange warning.
A tibble containing all validity scores and all
original data columns (if requested)
Keeley, J. W., Webb, C., Peterson, D., Roussin, L., & Flanagan, E. H. (2016). Development of a Response Inconsistency Scale for the Personality Inventory for DSM-5. Journal of Personality Assessment, 98(4), 351-359. doi:10.1080/00223891.2016.1158719
Sellbom, M., Dhillon, S., & Bagby, R. M. (2018). Development and validation of an overreporting scale for the Personality Inventory for DSM-5 (PID-5). Psychological Assessment, 30(5), 582-593. doi:10.1037/pas0000507
Bagby, R. M., & Sellbom, M. (2018). The Validity and Clinical Utility of the Personality Inventory for DSM–5 Response Inconsistency Scale. Journal of Personality Assessment, 100(4), 398–405. doi:10.1080/00223891.2017.1420659
Williams, M. M., Rogers, R., Sharf, A. J., & Ross, C. A. (2019). Faking Good: An Investigation of Social Desirability and Defensiveness in an Inpatient Sample With Personality Disorder Traits. Journal of Personality Assessment, 101(3), 253–263. doi:10.1080/00223891.2018.1455691
Lowmaster, S. E., Hartman, M. J., Zimmermann, J., Baldock, Z. C., & Kurtz, J. E. (2020). Further Validation of the Response Inconsistency Scale for the Personality Inventory for DSM-5. Journal of Personality Assessment, 102(6), 743–750. doi:10.1080/00223891.2019.1674320
# Compute the PID-5 validity scales and flag likely-invalid responders. # (The simulated data are random, so most rows are flagged.) validity_pid5(sim_pid5, items = 1:220, version = "FULL", append = FALSE)# Compute the PID-5 validity scales and flag likely-invalid responders. # (The simulated data are random, so most rows are flagged.) validity_pid5(sim_pid5, items = 1:220, version = "FULL", append = FALSE)
Writes a hitop_module() descriptor to a JSON file, so that a
researcher can keep it beside the form they field and read it back at
scoring time with read_module() instead of retyping every scale name.
The file records the scale names, not the keying: read_module() rebuilds
the items and their reverse-keying flags from this package's own tables.
The recorded items are there for a human reader and as a cross-check,
and a file that disagrees with what the package derives is an error rather
than a silent preference for either side.
Before it writes, write_module() rebuilds the module with
hitop_module() from its instrument and scales. A module whose
items, nItems, camelCase or instrument differ from that rebuild, or
that cannot be rebuilt from its instrument and scales, is refused with
an error of class
hitop_module_mismatch, and nothing is written. The file holds the rebuild's fields. read_module() rebuilds
the module from the file's scales, so it returns a hitop_module with
integer items. This is also true for a file written
from the deprecated hitop_subset class, or from a module whose items
are doubles.
write_module(module, file)write_module(module, file)
module |
A |
file |
A string giving the path to write to. |
The file path, invisibly.
The file is JSON, with these fields:
formatThe format version, a "major.minor" string. This
release writes "1.0".
package, packageVersion, buildDate
The package that wrote
the file, its version, and the date it was written. Recorded for the
reader; read_module() ignores all three.
instrumentThe instrument the module belongs to.
scalesThe module's scales, as they are printed on the instrument. Required: these are what the module is rebuilt from.
items, nItems
The original instrument item numbers the module
covers, and how many there are. write_module() writes them in
ascending order, and the hitop-form web page requires that order,
refusing a descriptor whose items are not ascending. Cross-checked
on read: read_module() compares them as a set, so their order
carries no meaning to it, but a repeated number is an error, and the
printed order of a shuffled form belongs in itemOrder instead.
itemOrderThe printed order of a shuffled form: a permutation
of items. Optional — a form printed in instrument order carries
none. read_module() returns it on the module's item_order
attribute, the same attribute generate_docx_hitopsr() returns, and
write_module() writes it back from that attribute, so a descriptor
read and written again keeps the order it recorded. The generators'
descriptor argument sets the attribute for you, and
score_hitopsr() and reliability_hitopsr() read it under
layout = "printed" to score columns entered in the form's printed
order.
columnsThe names that an online export gives the module's
items: one string per item, in ascending item-number order.
Optional. generate_redcap_hitopsr()'s descriptor writes the
dictionary's item field names here, and
generate_qualtrics_hitopsr()'s writes the questions' [[ID:]]
values. A Word form has no columns, so
its descriptor has no field. read_module() returns the field on the
module's columns attribute, and write_module() writes it back
from that attribute as a JSON array. score_hitopsr() and
reliability_hitopsr() use the attribute as items when items is
omitted.
format, instrument, and scales are required. A reader of format
"1.0" ignores a field it does not know, so release 0.2.0, the first
with read_module(), and later releases read a file with columns and
ignore the field. The fields and the
version string are a public contract and change only deliberately.
read_module() to read the file back; hitop_module() to build a
module in the first place; the descriptor argument of
generate_docx_hitopsr(), generate_qualtrics_hitopsr(), and
generate_redcap_hitopsr(), which writes one of these files beside the
instrument it builds.
m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss")) f <- tempfile(fileext = ".json") write_module(m, f) cat(readLines(f), sep = "\n") identical(read_module(f), m) file.remove(f)m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss")) f <- tempfile(fileext = ".json") write_module(m, f) cat(readLines(f), sep = "\n") identical(read_module(f), m) file.remove(f)