Reads a module descriptor written by write_module() (or
written by hand to the same format) and returns the hitop_module()
object it describes, ready to pass to score_hitopsr(),
reliability_hitopsr(), or any of the generators.
The file never supplies keying. The module is rebuilt by passing the
file's scales through hitop_module(), so this package's own tables
remain the only source of which items belong to a scale. The file's
recorded items and nItems, where present, are checked against that
rebuild, and a disagreement is an error: a descriptor written against
scale tables that have since moved fails loudly rather than scoring
quietly.
Value
A hitop_module object. If the file carries an itemOrder, it is
returned on the object's item_order attribute — the same attribute
generate_docx_hitopsr() returns for a shuffled form. Pass the module to
score_hitopsr() or reliability_hitopsr() with layout = "printed" to
score columns entered in that printed order.
Errors
Every failure below aborts with a condition naming the file, so a caller
may catch a particular one by class: hitop_module_file_missing,
hitop_module_file_invalid_json, hitop_module_file_missing_field,
hitop_module_file_unsupported_format, hitop_module_file_unknown_scales
(which carries hitop_module()'s own refusal as its parent),
hitop_module_file_items_mismatch, and hitop_module_file_bad_item_order.
The list is exhaustive by design: a descriptor that is malformed rather
than merely wrong — a top level that is a JSON array instead of an
object, or a number field that is not a flat array of numbers — is
refused as hitop_module_file_invalid_json or as the mismatch condition
for the field it spoils, never as a bare R coercion error.
The descriptor format
The file is JSON, with these fields:
formatThe format version, a
"major.minor"string. This release writes"1.0".package,packageVersion,buildDateThe package that wrote the file, its version, and the date it was written. Recorded for the reader;
read_module()ignores all three.instrumentThe instrument the module belongs to.
scalesThe module's scales, as they are printed on the instrument. Required: these are what the module is rebuilt from.
items,nItemsThe original instrument item numbers the module covers, and how many there are. Cross-checked on read: the order they are written in carries no meaning —
read_module()compares them as a set — but a repeated number is an error, and the printed order of a shuffled form belongs initemOrderinstead.itemOrderThe printed order of a shuffled form: a permutation of
items. Optional — a form printed in instrument order carries none.read_module()returns it on the module'sitem_orderattribute, the same attributegenerate_docx_hitopsr()returns, andwrite_module()writes it back from that attribute, so a descriptor read and written again keeps the order it recorded. The generators'descriptorargument sets the attribute for you, andscore_hitopsr()andreliability_hitopsr()read it underlayout = "printed"to score columns entered in the form's printed order.
format, instrument, and scales are required. The fields and the
version string are a public contract and change only deliberately.
See also
write_module() to write the file; hitop_module() to build a
module without one.
Examples
m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss"))
f <- tempfile(fileext = ".json")
write_module(m, f)
m2 <- read_module(f)
m2
#> <hitop_module> hitopsr: 8 items from 2 scales
#> * Agoraphobia
#> * Appetite Loss
identical(m2, m)
#> [1] TRUE
file.remove(f)
#> [1] TRUE