Initialise a review

Creates a new review state for a reviewable variable or an existing review state in a claims_df. The current values are copied into a new review column placed immediately after its predecessor.

Usage

review(.data, review_var, review_id = NULL, obs_status = NULL, label = NULL)

Arguments

.data

A claims_df.

review_var

Character scalar identifying the current review state. A reviewable variable name is treated as shorthand for its corresponding _candidate column. Alternatively, an existing review column may be supplied to continue a multi-stage review workflow.

review_id

Optional identifier for the new review state. It becomes the suffix of the new review column. If omitted, the review sequence number is used.

obs_status

Optional observation status assigned to new review values.

label

Optional human-readable label describing the review task. Before review, the label provides instructions to the reviewer. After review, it identifies the completed review activity.

Value

A claims_df with one additional review round.

Details

review() creates a new review state by allocating a new review column. If review_id is supplied, it is used as the suffix of the new review column. Otherwise, the review sequence number is used. It is also possible to assign a human-readable label describing the intended review task. The label serves both as an instruction for reviewers during interactive review workflows and as a description of the review activity once the review has been completed.

In contrast, document() records provenance describing how a revision was produced. It records information such as the review activity, the responsible reviewer or software agent, supporting resources, and optional reviewer comments explaining how the task was interpreted or why particular review decisions were made.

Together, review() and document() separate the definition of a review task from the documentation of its execution, supporting reproducible, explainable, and auditable review workflows.

Examples

claims <- claims_df(
  Orange,
  scope_var = "age",
  subject_var = "Tree"
)

# Create an initial review.
reviewed <- claims |>
  review(
    "circumference", # equal to: circumference_candidate
    review_id = "remeasured",
    label = "Remeasure the circumference of each tree at the recorded age."
  )

# Continue the review.
reviewed <- reviewed |>
  review(
    "circumference_remeasured",
    review_id = "reviewed",
    label = "Verify the remeasurement independently."
  )

names(reviewed)
#> [1] "claim_id"                 "age"                     
#> [3] "Tree"                     "circumference_candidate" 
#> [5] "circumference_remeasured" "circumference_reviewed"  

attr(reviewed, "review_label")
#>                                                      remeasured 
#> "Remeasure the circumference of each tree at the recorded age." 
#>                                                        reviewed 
#>                       "Verify the remeasurement independently."