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$waveas a string so that labelled waves ("pre"/"post") work as well as numbered ones. If the dataset does not have awavecolumn, this input is ignored. Defaults to the most frequent wave ifNULL. 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 aswaveis. An occasion column present in the table, not named here, and keying a repeatedid-itempair is never chosen for you: either passagg_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.0and1.0specifying the minimum response density required for anidto be included. Default is0.1. Set toNULLto disable filtering. Density is the proportion of items with a non-missing value in the column given byresp_col.- agg_method
A string specifying how to handle multiple
id-itempairs. 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 isFALSE.- resp_col
Character string giving the column in
dfto 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.