Rename Columns to Standard PID-5 Item Names

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.

Usage

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
)

Arguments

data

A data frame containing the PID-5 items.

version

A string specifying the PID-5 form the items belong to: "FULL" (220 items), "SF" (100 items), "BF" (25 items), "BFPM" (the 36-item PID5BF+M), "IRF" (the 218-item Informant Form, whose text matches pid_items$TextIRF), or "FFBF" (the 100-item Forensic Faceted Brief Form, whose text matches any of the four texts in pid_ffbf_items: self or informant report, English or German). Only a full name is accepted, in any letter case. Any other value, a start of a name such as "F" included, is an error of class hitop_unknown_version. (default = "FULL")

method

A string specifying the matching method: "number" to rename columns spelled from_prefix followed by an item number, or "text" to match against the literal item prompt text in pid_items$Text (pid_items$TextIRF for version = "IRF"; for version = "FFBF", any of the four texts in pid_ffbf_items). Typographic quotes (‘ ’ “ ”) count as straight ones, and any periods, ellipses (... or …), spaces (the no-break space too), tabs or line breaks at the start or the end of the text are ignored. So a leading ellipsis and a final period do not count. The informant text has no "He or she..." stem, so remove that stem from text copied from the printed informant form first. (default = "number")

The forms number their items independently, so "number" reads the digits as an item number of the form named by version: under version = "SF", pid_7 is short-form item 7, not the full-form item the short form numbers 7. Data labelled by full-form item numbers must be renamed with version = "FULL" first, or matched with method = "text".

item_cols

An optional character vector of current column names to be renamed. Required if method = "text".

item_text

An optional character vector of item texts corresponding exactly to the columns specified in item_cols. Required if method = "text".

from_prefix

A string matched literally at the start of a column name under method = "number", before the item number. The default is the spelling this package's own PID-5 datasets used before they were renamed to match the exports. (default = "pid_")

prefix

A string pasted literally before each standardized item number, which is zero-padded to the width of the form's largest item number. NULL resolves to the form's own stem: "pid5_", "pid5sf_", "pid5bf_", "pid5bfpm_", "pid5irf_" or "pid5ffbf_". (default = NULL)

Value

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.

References

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

Examples

# 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")))
#> [1] "pid5_001" "pid5_002" "age"