Skip to contents

Converts an IRW-compliant dataset from long format to wide format while handling optional metadata elements and filtering by wave.

Usage

irw_long2resp(
  df,
  wave = NULL,
  occasion = NULL,
  id_density_threshold = 0.1,
  agg_method = NULL,
  check_resp = FALSE,
  resp_col = "resp"
)

Arguments

df

A data frame containing IRW-compliant item response data in long format.

wave

(Optional) The occasion to keep, matched against df$wave as a string so that labelled waves ("pre"/"post") work as well as numbered ones. If the dataset does not have a wave column, this input is ignored. Defaults to the most frequent wave if NULL. A wave that is not present in the table is an error: reshaping without filtering would aggregate every occasion together.

occasion

(Optional) Named vector or list giving the occasion to keep for any other occasion column the standard defines – rater, session, trial_number, order, period, block, subtest, timepoint, occasion – e.g. occasion = c(rater = "2"). Matched as a string, exactly as wave is. An occasion column present in the table, not named here, and keying a repeated id-item pair is never chosen for you: either pass agg_method, which says aggregating across it is what you want, or this errors and names the column. Both halves matter – the aggregation step below would otherwise average occasions into a value that exists in no respondent's data, and picking one occasion unasked is the same defect wearing different clothes (on a 651-rater panel it returns one rater). The occasions kept are recorded on the result as the "occasion" attribute, and any aggregated across as "occasion_pooled".

id_density_threshold

A numeric value between 0.0 and 1.0 specifying the minimum response density required for an id to be included. Default is 0.1. Set to NULL to disable filtering. Density is the proportion of items with a non-missing value in the column given by resp_col.

agg_method

A string specifying how to handle multiple id-item pairs. Options: "mean", "mode", "median", "first". Default is "mean" for numeric response columns and "first" for non-numeric (e.g. text).

check_resp

Logical; if TRUE, perform basic response diagnostics on items using default thresholds and attach results as an attribute. Default is FALSE.

resp_col

Character string giving the column in df to use as the response value when building the wide matrix. Defaults to "resp". For nominal data stored in a text column, use e.g. resp_col = "text".

Value

A data frame in wide format where rows represent id values and each item column is named by the item id itself, as the long table spells it – so the matrix joins back to the item text (irw_itemtext()) and anything else keyed by item without renaming anything. (Before #3221 these names carried an item_ prefix.) A numeric item id becomes a column named by that number, which needs backticks in a formula and a rename for lavaan, whose model syntax rejects a name beginning with a digit even in backticks. The column used for response values is recorded in the "resp_col" attribute. If check_resp = TRUE, an attribute "resp_checks" is attached:

  • single_category_items: character vector of item IDs with only one observed category.

  • sparse_category_items: named list; each element is a data.frame with sparse categories for that item (columns: resp, count, prop).

Details

This function applies a default sparsity filter with a threshold of 0.1 for id density to avoid excessive sparsity. Users can disable filtering by setting id_density_threshold = NULL.

If check_resp = TRUE, the function will run a basic diagnostic using default thresholds (min_count = 5, min_prop = 0.01), attach the results as an attribute "resp_checks" on returned object, and add a short NOTE with counts of flagged items. A response category is considered sparse if it has fewer than min_count responses OR a within-item proportion smaller than min_prop. For more control, use irw_check_resp() directly.