Document a revision — document • review

Records provenance information describing how a revision was produced.

Usage

document(
  .data,
  revision,
  activity = NULL,
  agent = NULL,
  used = NULL,
  comment = NULL
)

Arguments

.data: A claims_df.
revision: Character scalar identifying the revision to document, for example "height_remeasured" or "circumference_reviewed".
activity: Optional type of review activity.
agent: Optional person or software agent carrying out the review.
used: Optional evidence, source or other provenance entity used during the review.
comment: Optional reviewer comment.

Value

A claims_df with updated provenance metadata for the specified revision.

Details

document() records provenance describing how a revision was created after the review has been carried out. It complements review(), which allocates a new revision and optionally assigns a human-readable label describing the intended review task.

The recorded provenance may describe the review activity, the person or software agent performing the review, evidence or other resources consulted during the review, and optional reviewer comments explaining how the review was carried out or why particular review decisions were made.

By making review activities explicit, document() improves the explainability, reproducibility, and auditability of review workflows. The recorded provenance also provides a foundation for future implementations of the dplyr::explain() generic for review objects.

Examples

reviewed <- claims_df(
  Orange,
  scope_var = "age",
  subject_var = "Tree"
) |>
  review(
    "circumference",
    review_id = "remeasured",
    label = "Remeasure the circumference of each tree."
  ) |>
  document(
    revision = "circumference_remeasured",
    activity = "manual_review",
    agent = person("Jane", "Doe", role = "rev"),
    used = "doi:10.5281/zenodo.1234567",
    comment = "Measurements verified against the laboratory notebook."
  )

attr(reviewed, "prov_activity")
#>                candidate circumference_remeasured 
#>                 "create"          "manual_review" 
attr(reviewed, "prov_agent")
#>                candidate circumference_remeasured 
#>                       NA         "Jane Doe [rev]" 
attr(reviewed, "prov_used")
#>                    candidate     circumference_remeasured 
#>                           NA "doi:10.5281/zenodo.1234567" 
attr(reviewed, "prov_comment")
#>                                 circumference_remeasured 
#> "Measurements verified against the laboratory notebook."