Save a Module to a File

Writes a hitop_module() descriptor to a JSON file, so that a researcher can keep it beside the form they field and read it back at scoring time with read_module() instead of retyping every scale name.

The file records the scale names, not the keying: read_module() rebuilds the items and their reverse-keying flags from this package's own tables. The recorded items are there for a human reader and as a cross-check, and a file that disagrees with what the package derives is an error rather than a silent preference for either side.

Usage

write_module(module, file)

Arguments

module

A hitop_module object, as returned by hitop_module(). An item_order attribute, where present, is written as the file's itemOrder and must be a permutation of the module's items.

file

A string giving the path to write to.

Value

The file path, invisibly.

The descriptor format

The file is JSON, with these fields:

format

The format version, a "major.minor" string. This release writes "1.0".

package, packageVersion, buildDate

The package that wrote the file, its version, and the date it was written. Recorded for the reader; read_module() ignores all three.

instrument

The instrument the module belongs to.

scales

The module's scales, as they are printed on the instrument. Required: these are what the module is rebuilt from.

items, nItems

The 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 in itemOrder instead.

itemOrder

The 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's item_order attribute, the same attribute generate_docx_hitopsr() returns, and write_module() writes it back from that attribute, so a descriptor read and written again keeps the order it recorded. The generators' descriptor argument sets the attribute for you, and score_hitopsr() and reliability_hitopsr() read it under layout = "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

read_module() to read the file back; hitop_module() to build a module in the first place; the descriptor argument of generate_docx_hitopsr(), generate_qualtrics_hitopsr(), and generate_redcap_hitopsr(), which writes one of these files beside the instrument it builds.

Examples

m <- hitop_module("hitopsr", scales = c("Agoraphobia", "Appetite Loss"))

f <- tempfile(fileext = ".json")
write_module(m, f)
cat(readLines(f), sep = "\n")
#> {
#>   "format": "1.0",
#>   "package": "hitop",
#>   "packageVersion": "0.2.0",
#>   "buildDate": "2026-09-11",
#>   "instrument": "hitopsr",
#>   "scales": ["Agoraphobia", "Appetite Loss"],
#>   "items": [66, 109, 118, 144, 202, 260, 291, 389],
#>   "nItems": 8
#> }

identical(read_module(f), m)
#> [1] TRUE

file.remove(f)
#> [1] TRUE