Appends a structured, disclosed-revision entry to an instrument's
amendment log, comparing previous against instrument to record what
changed and why: a data-entry correction, bot-response removal, or a
documented model respecification. The record is kept inside the file,
beside the content it explains.
Usage
amend_sframe(
previous,
instrument,
reason_code,
reason_text,
tier = NULL,
author = NULL,
deviation_report = NULL,
second_signoff = NULL,
version = NULL
)Arguments
- previous
An
sframeobject: the instrument's state before this amendment. Read from a file, it must still match that file, or its last recorded amendment, so the log starts from a state a file held. An edit made to it after reading is refused, and so is one read withverify = FALSEthat failed its integrity check.- instrument
An
sframeobject: the instrument's state after the change this call discloses.- reason_code
One of
"data_correction","bot_removal","model_respecification","instrument_revision","other".- reason_text
Character. A free-text explanation. Required and must be non-empty regardless of
reason_code.- tier
"pipeline"or"design". WhenNULL(the default), inferred fromreason_code:data_correctionandbot_removaldefault to"pipeline", and everything else to"design". A change to the analysis plan, a model, a conjoint design or a scale's scoring is always"design", and asking for"pipeline"on one is an error.Character or
NULL. Who made the change.- deviation_report
Character or
NULL. Required whentieris"design": what changed in the research question, method, or model, and why. Ignored (may beNULL) for"pipeline"amendments.- second_signoff
Character or
NULL. A second reviewer's name or identifier (an ethics board reference, a co-author). When omitted, the entry recordssignoff = "none".- version
Character or
NULL. The instrument's version after the amendment, written tometa$versionand covered by the recorded content.NULLkeeps the versioninstrumenthas. When that is still the version ofprevious, a message of classsframe_version_suggestionsuggests the next one: the minor number for a design amendment (1.0.0 to 1.1.0), the patch number for a pipeline amendment (1.0.0 to 1.0.1).
Value
The amended sframe object, with the new entry appended to its
amendment log. Call write_sframe() to persist it.
Details
write_sframe() refuses to write an instrument read from a file whose
content has changed with no amendment recorded, one that changed after its
last amendment, and one whose amendment log was shortened or reordered.
read_sframe() refuses a file edited on disk without its hash being
recomputed. These checks are local and the hashes are unsigned: someone
who rewrites both a file and its log, and recomputes the hashes, is not
detected, and nothing here establishes who made a change or when.
Amendments come in 2 tiers. A "pipeline" amendment (data corrections,
bot removal) needs only a reason. A "design" amendment also requires a
deviation_report describing what changed in the research question,
method or model, and why. The tier follows the change itself: an amendment
that changes the analysis plan, a model, a conjoint design or how a scale
is scored (its items, reverse keys, weights, method or minimum answered)
is always design tier, whatever reason_code or tier says. So is a
change to an item's own reverse or scale_id, to the choice codes of an
item a scale scores, or to what an attention check tests and its pass
values, since each moves scale scores or who is flagged. second_signoff is
optional. When omitted, the entry records signoff = "none", so the
absence of a named reviewer is visible. The tier, report and signoff are
what the author records. None of them is independent approval.
previous_hash and new_hash on each entry are a content fingerprint: a
SHA-256 over a canonical serialisation of the instrument, with the hash,
amendments and references fields excluded, taken after validation, so new_hash is
the content that is written. It is distinct from the file's own integrity
hash from write_sframe(), which also covers the amendment log. Both
identify content. Neither is byte identity.
The amendment is sealed when the file is written: write_sframe() hashes
the object as it stands then, so a change made to the returned object
before it is written is part of the author's new version, covered by the
file's hash but not by this entry's new_hash.
The check that a change read from a file was recorded here rests on an
attribute, sframe_origin, which read_sframe() sets and the package's
own functions keep. Base R that builds a new list from the parts, such as
x[names(x)], c(x) or lapply() over the fields, drops it, and the
result is written as an instrument read from no file, with no amendment
asked for. See the Revisions section of write_sframe().
Wording on the participant's screens
The welcome, consent and thank-you wording lives in render, and both
hashes cover render, so editing that wording changes the instrument as
much as editing an item does. On a published instrument, record it as a
pipeline-tier amendment with reason_code = "other" and a reason_text
saying what was reworded, then write the file with write_sframe(). This
is the intended path for a host that lets researchers edit these screens.
A file whose JSON is edited directly fails read_sframe()'s hash check.
See also
sframe_get_amendments(), write_sframe(), read_sframe()
Other Amendments functions:
sframe_drop_items(),
sframe_get_amendments(),
sframe_item_flags(),
sframe_link_git_commit()
Examples
item <- sframe_item("q1", "How satisfied are you?", type = "text")
instr <- sframe_instrument("Demo", components = list(item))
item2 <- sframe_item("q1", "How satisfied are you overall?", type = "text")
revised <- sframe_instrument("Demo", components = list(item2))
amended <- amend_sframe(
instr, revised,
reason_code = "instrument_revision",
reason_text = "Clarified item wording after a pilot round.",
deviation_report = "Wording only; no change to the construct measured."
)
nrow(sframe_get_amendments(amended))