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.

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-08-25",
#>   "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