verify_roles: Verify a declared analysis plan against the data signature

In rolescry: Name-Blind Variable-Role Detection by Data Signature

Verify a declared analysis plan against the data signature

Description

Checks a user-declared assignment of variable roles against what the data themselves can support. The claim is mapped to column positions once and the data are then examined name-blind (the same information-theoretic signature used by detect_roles()). Each claimed role gets one verdict: contradicted (a falsification backed by a value statistic), consistent (the data support it) or unverifiable (sub_reason identifiability or coverage). Structure the blind detector finds that the claim does not mention is listed separately.

Usage

verify_roles(data, claim)

## S3 method for class 'role_verification'
print(x, ...)

## S3 method for class 'role_verification'
summary(object, ...)

Arguments

data	A data.frame with unique, non-empty column names.
claim	A named list. Names are role keys: scalar roles (subject_id, group_var, outcome_continuous, outcome_binary, time_variable, event_variable, time_index) take one column name; set roles (repeated_measures, scale_items, covariate) take one or more; pair roles (coupled_pair, paired_pairs, agreement_pairs) take a length-2 character vector or a list of them.
x, object	A role_verification object.
...	Ignored.

Details

contradicted is issued only for these falsifications, each backed by a value statistic: subject_id whose values repeat while a detected long panel has a different entity cluster; a paired_pairs/agreement_pairs pair that shares no information beyond the independence noise floor, whose members differ more than they agree, or with a constant member; a coupled_pair whose members are independent; an event column that is not a two-level or 0/1/2 coding, or negative follow-up times; repeated_measures that are not the measures of a detected long panel, or a wide set with no common factor; ordinal scale_items with no common factor, or binary items forming a one-hot partition; a time_index that is not a calendar column; a group_var that is all-distinct or calendar; a non-numeric outcome_continuous; an outcome_binary without exactly two observed values. Absence of a time-event association is not a falsification (constant-hazard censoring makes the event independent of the observed time) and is reported as unverifiable(coverage). A consistent pair means the two columns share information and their difference is smaller than their mean. Each claimed pair is judged on its own. A survival claim (time_variable plus event_variable) is one claim shown as two rows and is counted once in counts.

Value

An object of class "role_verification": a list with table (role, columns, verdict, sub_reason, statistic, reason, blind), unclaimed (role, columns, statistic), counts (claims, testable, contradicted, consistent, unverifiable), n_obs and n_var.

Examples

set.seed(1)
rct <- data.frame(id = 1:60, arm = rep(c("a", "b"), 30),
                  pre = rnorm(60), post = rnorm(60))
verify_roles(rct, list(subject_id = "id", group_var = "arm",
                       paired_pairs = c("pre", "post")))

rolescry documentation built on Oct. 21, 2026, 5:14 p.m.