R/recordset_df.R

Defines functions recordset_provenance new_recordset_df recordset_df

Documented in new_recordset_df recordset_df

#' @title Create a semantically annotated Record Set
#'
#' @description
#' Create a `recordset_df`, a lightweight extension of
#' `dataset::dataset_df` for representing archival Record Sets.
#'
#' A `recordset_df` stores dataset-level metadata together with
#' optional Record and Record Part identifiers using lightweight
#' conventions inspired by the Records in Contexts (RiC) model.
#' It supports provenance-aware archival, curatorial and semantic
#' enrichment workflows while remaining compatible with ordinary
#' data frames.
#'
#' See the **"Working with Record Sets"** vignette for a complete
#' workflow starting from filesystem observations.
#'
#' @param x A `data.frame` or `dataset_df`.
#'
#' @param title Character scalar giving the title of the Record Set.
#'
#' @param creator A `utils::person()` object describing the creator of
#'   the Record Set metadata.
#'
#' @param description Optional description of the Record Set.
#'
#' @param record_set_identifier Optional identifier of the Record Set.
#'
#' @param record_identifier Name of the column containing Record
#'   identifiers. The selected column is annotated as
#'   `rico:Identifier` and labelled "Record Identifier".
#'
#' @param record_part_identifier Name of the column containing Record
#'   Part identifiers. The selected column is annotated as
#'   `rico:Identifier` and labelled "Record Part Identifier".
#'
#' @param record_subject Subject term describing the Record Set.
#'   Defaults to `"Record Set"`.
#'
#' @param ... Reserved for future extensions.
#'
#' @return
#' A `recordset_df`, which inherits from `dataset_df`, `tbl_df`,
#' `tbl` and `data.frame`.
#'
#' @examples
#' x <- data.frame(
#'   resource_locator = c(
#'     "https://example.org/1", "https://example.org/2"
#'   ),
#'   filename = c("a.html", "b.html"),
#'   stringsAsFactors = FALSE
#' )
#'
#' rs <- recordset_df(
#'   x,
#'   title = "Demo Record Set",
#'   creator = utils::person("Joe", "Doe", role = "aut"),
#'   record_identifier = "resource_locator",
#'   record_part_identifier = "filename"
#' )
#'
#' rs
#'
#' @references
#' International Council on Archives Expert Group on Archival
#' Description (2023). Records in Contexts (RiC).
#' https://www.ica.org/ica-network/expert-groups/egad/records-in-contexts-ric/
#'
#' @seealso
#' [dataset::dataset_df()], [observe_wacz()],
#' [wacz_to_recordset_df()]
#'
#' @importFrom dataset as_dataset_df defined dublincore subject identifier
#' @importFrom utils person
#' @export
recordset_df <- function(
  x,
  title = NULL,
  creator = utils::person("Jane", "Doe"),
  description = NULL,
  record_set_identifier = NULL,
  record_identifier = NULL,
  record_part_identifier = NULL,
  record_subject = "Record Set",
  ...
) {
  if (is.null(creator)) {
    rs_creator <- "Untitled Record Set"
  } else if (!inherits(creator, "person")) {
    rs_creator <- person(creator)
  } else {
    rs_creator <- creator
  }

  if (is.null(description) || is.na(description)) {
    rs_description <- NULL
  } else {
    rs_description <- description
  }

  ds_bibentry <- dataset::dublincore(
    title = if (is.null(title)) "Untitled Record Set" else title,
    identifier = record_set_identifier,
    creator = creator,
    description = description
  )

  ds_bibentry

  y <- dataset::as_dataset_df(x)

  attr(y, "dataset_bibentry") <- ds_bibentry

  dataset::subject(y) <-
    dataset::subject_create(term = record_subject)


  new_recordset_df(
    y,
    record_identifier = record_identifier,
    record_part_identifier = record_part_identifier
  )
}

#' Internal constructor for recordset_df
#'
#' @description
#' Low-level constructor for recordset_df objects.
#'
#' This function extends an existing dataset_df with lightweight
#' Record Set semantics by:
#'
#' * assigning the recordset_df class;
#' * optionally assigning a Record Set identifier and provenance;
#' * optionally declaring Record and Record Part identifier columns as
#' rico:Identifier using [dataset::defined()].
#'
#' Unlike [recordset_df()], this constructor assumes that dataset-level
#' metadata have already been created and performs no coercion from
#' ordinary data.frame objects.
#'
#' @param x A dataset_df object.
#'
#' @param record_identifier Optional name of the column containing
#' Record identifiers.
#'
#' @param record_part_identifier Optional name of the column containing
#' Record Part identifiers.
#'
#' @return
#' A recordset_df object inheriting from dataset_df.
#'
#' @importFrom dataset identifier
#' @keywords internal
new_recordset_df <- function(
  x,
  record_identifier = NULL,
  record_part_identifier = NULL
) {
  if (!inherits(x, "dataset_df")) {
    stop("`x` must inherit from dataset_df.", call. = FALSE)
  }

  record_set_identifier <- dataset::identifier(x)

  dataset::provenance(x) <- recordset_provenance(record_set_identifier)

  if (!is.null(record_identifier)) {
    if (!record_identifier %in% names(x)) {
      stop("Column not found: ", record_identifier, call. = FALSE)
    }

    if (anyDuplicated(x[[record_identifier]])) {
      warning("Record identifiers are not unique.", call. = FALSE)
    }

    x[[record_identifier]] <- dataset::defined(
      x[[record_identifier]],
      label = "Record Identifier",
      concept = "rico:Identifier"
    )
  }

  if (!is.null(record_part_identifier)) {
    if (!record_part_identifier %in% names(x)) {
      stop("Column not found: ", record_part_identifier, call. = FALSE)
    }

    if (anyDuplicated(x[[record_part_identifier]])) {
      warning("Record part identifiers are not unique.", call. = FALSE)
    }

    x[[record_part_identifier]] <- dataset::defined(
      x[[record_part_identifier]],
      label = "Record Part Identifier",
      concept = "rico:Identifier"
    )
  }

  class(x) <- unique(c("recordset_df", class(x)))


  attr(x, "prov") <-
    recordset_provenance(record_set_identifier = record_set_identifier)

  x
}

#' Default internal provenance constructor
#' A wrapper around [dataset::n_triples()] and [dataset::n_triple()].
#' @keywords internal
#' @importFrom dataset n_triples n_triple
#' @noRd
recordset_provenance <- function(
  record_set_identifier = NULL
) {
  if (is.null(record_set_identifier)) {
    record_set_identifier <- "http://example.com/recordset"
  }


  activity <- paste0(record_set_identifier, "/activity")

  dataset::n_triples(c(
    dataset::n_triple(
      record_set_identifier,
      "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
      "http://www.w3.org/ns/prov#Entity"
    ),
    dataset::n_triple(
      activity,
      "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
      "http://www.w3.org/ns/prov#Activity"
    ),
    dataset::n_triple(
      "https://fscontext.dataobservatory.eu/software/fscontext",
      "http://www.w3.org/1999/02/22-rdf-syntax-ns#type",
      "http://www.w3.org/ns/prov#SoftwareAgent"
    ),
    dataset::n_triple(
      activity,
      "http://www.w3.org/ns/prov#wasAssociatedWith",
      "https://fscontext.dataobservatory.eu/software/fscontext"
    ),
    dataset::n_triple(
      record_set_identifier,
      "http://www.w3.org/ns/prov#wasGeneratedBy",
      activity
    )
  ))
}

Try the fscontext package in your browser

Any scripts or data that you put into this service are public.

fscontext documentation built on Nov. 19, 2026, 5:11 p.m.