Checks the internal consistency of an sframe instrument object and
returns a diagnostic result. Validation is performed automatically by
write_sframe() and optionally by read_sframe(). It can also be run
independently at any point during instrument construction.
Arguments
- instrument
An
sframeobject created bysframe_instrument().- strict
Logical. When
TRUE(default), any detected problem raises an error of classsframe_validation_error. WhenFALSE, problems are reported in the returned diagnostic without stopping.
Value
An sframe_validation object. When the instrument is valid, the
instrument carried inside it has meta$validated set to TRUE and can
be recovered with as_sframe().
Details
The following checks are performed:
Duplicate item IDs
Invalid item IDs
Duplicate choice-set IDs
Duplicate scale IDs
Item IDs, scale IDs and response columns that share a name, or take a reserved metadata name such as
submitted_at. A scale's score is stored in a column named by its ID, so a shared name would overwrite dataItems with missing labels
Items referencing a missing
choice_setin the instrumentItems referencing a missing
scale_idin the instrumentItems marked
reverse = TRUEwithout ascale_idChoice sets referenced by items but not present in the instrument
Scale
itemsvectors containing IDs not present in the instrumentScale scoring parameters: repeated items, a
min_validoutside 1 to the number of items, and weights that are not positive finite numbersReverse coding declared for an item outside the scale that declares it
Branching rules referencing item IDs not present in the instrument
%in%branching rules whosevalueno evaluator can consumeAttention checks referencing item IDs not present in the instrument
A choice code with white space at the start or end, such as
" 1"A scale
methodother than"mean"or"sum", a choice set whosevaluesandlabelsdiffer in length, a branching rule whose operator is unknown or missing or that depends on its own item, and a plan block whosealphaoroptions$alphais not a number between 0 and 1
These are reported as notes, which sframe_notes() returns and which leave
the instrument valid, since SurveyBuilder saved them before 0.4.3: branching
rules that depend on each other in a cycle, a check whose pass values are
not codes of its item's choice set, an item whose scale_id names a
scale that does not list it, and a scale item's choice set with numeric
codes outside 1 evenly spaced run (1 to 5 and 99 for "do not know"), which
score_scales() reads as missing.
Analysis plan roles referencing missing variables or models
Model specifications referencing missing indicators or constructs
Changed in 0.4.0
Earlier versions returned 2 different things depending on strict: the
instrument itself, invisibly, when strict = TRUE, and a bare unclassed
list when strict = FALSE. A validator should report a diagnostic, so
both paths now return an sframe_validation object, and they return it
visibly, so validate_sframe(instrument) typed at the console shows the
result. Code that read $valid and $problems keeps working. Code that
used the strict = TRUE return as an instrument should now wrap the call
in as_sframe().
See also
sframe_validation, as_sframe(), sframe_problems(),
sframe_is_valid(), sframe_instrument(), write_sframe()
Other Design functions:
as_sframe(),
launch_builder(),
read_sframe(),
sframe_attention_check(),
sframe_branch(),
sframe_choice_set(),
sframe_conjoint_design(),
sframe_get_study(),
sframe_instrument(),
sframe_item(),
sframe_sampling_methods(),
sframe_scale(),
sframe_validation,
write_sframe()
Examples
# Build a minimal valid instrument and validate it
cs <- sframe_choice_set("ag5", 1:5,
c("Strongly disagree", "Disagree", "Neutral",
"Agree", "Strongly agree"))
item <- sframe_item("sat_1", "The service met my expectations.",
type = "likert", choice_set = "ag5", scale_id = "sat")
scale <- sframe_scale("sat", "Satisfaction", items = "sat_1")
instr <- sframe_instrument("Demo Survey", components = list(cs, item, scale))
# The result prints its own diagnostic
validate_sframe(instr, strict = FALSE)
# Explore it with dedicated methods rather than reaching in with `$`
v <- validate_sframe(instr, strict = FALSE)
sframe_is_valid(v)
sframe_problems(v)
summary(v)
# Recover the validated instrument
validated <- as_sframe(validate_sframe(instr, strict = TRUE))
isTRUE(sframe_meta(validated)$validated)