Construct a Betwixt candidate dataset — create_candidate

Constructs the initial wide-form candidate dataset used for a Betwixt review. Each row associates a piece of evidence with a subject and the descriptive information required to present that subject for review.

The subject forms the first reviewable candidate column. Additional reviewable columns can subsequently be appended with add_candidate_column().

An optional evidence relation can describe a reviewable semantic relation between the evidence and the subject, for example "depicts" or "documents".

Usage

create_candidate_dataset(
  subject,
  evidence_url = NA_character_,
  evidence_media_url = NA_character_,
  evidence_text = NA_character_,
  label = NA_character_,
  description = NA_character_,
  alternative_label = NA_character_,
  alternative_description = NA_character_,
  evidence_relation = NULL,
  evidence_relation_range = NA_character_,
  subject_range = NA_character_,
  subject_definition = NA_character_,
  data_manager_name = "",
  data_manager_iri = "",
  data_manager_email = "",
  project_id = ""
)

Arguments

subject: A vector containing the subject identifiers or values to be reviewed. The subject is stored as the subject column named subject.
evidence_url: An optional character vector containing URLs or other resolvable locations of evidence resources that can be opened by the reviewer.
evidence_media_url: An optional character vector containing URLs or other resolvable locations of media presented directly to the reviewer.
evidence_text: An optional character vector containing short identifiers or labels for the evidence.
label: An optional character vector containing human-readable labels for the subjects presented for review.
description: An optional character vector containing human-readable descriptions of the subjects presented for review.
alternative_label: An optional character vector containing alternative human-readable labels for the subjects presented for review, for example a translation or a label intended for a different user group.
alternative_description: An optional character vector containing alternative human-readable descriptions of the subjects presented for review, for example a translation, a more detailed description, or a description intended for a different user group.
evidence_relation: An optional character vector describing a candidate semantic relation between the evidence and the subject, for example "depicts". If NULL, no evidence relation columns are added. Defaults to NULL.
evidence_relation_range: An optional character vector containing the admissible or suggested evidence relations. Use add_candidate_range() to construct controlled ranges. This argument can only be used when evidence_relation is supplied. Defaults to NA_character_.
subject_range: A character vector containing the admissible or suggested subject values. Use add_candidate_range() to construct controlled ranges, or NA_character_ when no controlled range is supplied. Defaults to NA_character_.
subject_definition: A character vector containing resolvable identifiers or URLs defining the proposed subject. A supplied definition indicates that the subject already exists as an identified entity; NA_character_ indicates an unresolved candidate subject. Defaults to NA_character_.
data_manager_name: Character string containing the name of the person responsible for preparing the candidate dataset.
data_manager_iri: Character string containing an IRI identifying the data manager, such as an ORCID, ISNI, or Wikidata URI.
data_manager_email: Character string containing the data manager's email address.
project_id: Character string identifying the project within which the candidate dataset was generated.

Value

A tibble with one row per evidence-subject observation and the columns row_number, evidence_url, evidence_media_url, evidence_text, label, description, alternative_label, alternative_description, subject, subject_range, and subject_definition.

If evidence_relation is supplied, the tibble additionally contains evidence_relation and evidence_relation_range.

Details

create_candidate_dataset() establishes the initial structure of a Betwixt candidate dataset. row_number is generated automatically as an integer sequence in input order.

Dataset-level provenance is stored in the provenance attribute rather than repeated across observation rows. The generation timestamp is recorded as an ISO 8601 UTC value at one-second precision. The software agent and installed Betwixt package version are recorded automatically.

The subject, its candidate range, and its definition are passed internally to add_candidate_column(), thereby establishing the same column contract used for subsequent reviewable assertions.

Additional reviewable assertions can be appended with add_candidate_column(). Display-only contextual columns can be added with ordinary data manipulation functions such as dplyr::mutate().

At least one of evidence_media_url or evidence_url must be supplied for each row.

The evidence relation is distinct from review provenance. When present, it represents a candidate semantic relation between the evidence and the subject and is itself available for review.

Examples

# Candidate dataset without a reviewable evidence relation
delini_candidates <- create_candidate_dataset(
  evidence_media_url = delini$evidence_media_url,
  evidence_text = delini$evidence_text,
  label = delini$label,
  description = delini$description,
  subject = delini$subject,
  subject_range = delini$subject_range,
  subject_definition = delini$subject_definition
)

delini_candidates
#> # A tibble: 5 × 11
#>   row_number evidence_url evidence_media_url     evidence_text label description
#>        <int> <chr>        <chr>                  <chr>         <chr> <chr>      
#> 1          1 NA           https://betwixt.datao… P7101565      Deli… the farmho…
#> 2          2 NA           https://betwixt.datao… P7101561      tabl… a tablet-w…
#> 3          3 NA           https://betwixt.datao… P7101556      bed … a bed in t…
#> 4          4 NA           https://betwixt.datao… P7101590      reco… a record c…
#> 5          5 NA           https://betwixt.datao… P7101623      reco… a floor pl…
#> # ℹ 5 more variables: alternative_label <chr>, alternative_description <chr>,
#> #   subject <chr>, subject_range <chr>, subject_definition <chr>

# Candidate dataset with a reviewable evidence relation
delini_dual_candidates <- create_candidate_dataset(
  evidence_media_url = delini$evidence_media_url,
  evidence_text = delini$evidence_text,
  label = delini$label,
  description = delini$description,
  subject = delini$subject,
  subject_definition = delini$subject_definition,
  evidence_relation = rep("depicts", nrow(delini)),
  evidence_relation_range = rep(
    add_candidate_range("depicts", "documents", "Other…"),
    nrow(delini)
  )
)

delini_dual_candidates
#> # A tibble: 5 × 13
#>   row_number evidence_url evidence_media_url     evidence_text evidence_relation
#>        <int> <chr>        <chr>                  <chr>         <chr>            
#> 1          1 NA           https://betwixt.datao… P7101565      depicts          
#> 2          2 NA           https://betwixt.datao… P7101561      depicts          
#> 3          3 NA           https://betwixt.datao… P7101556      depicts          
#> 4          4 NA           https://betwixt.datao… P7101590      depicts          
#> 5          5 NA           https://betwixt.datao… P7101623      depicts          
#> # ℹ 8 more variables: evidence_relation_range <chr>, label <chr>,
#> #   description <chr>, alternative_label <chr>, alternative_description <chr>,
#> #   subject <chr>, subject_range <chr>, subject_definition <chr>

# Statistical example based on the W3C RDF Data Cube Vocabulary
w3c_candidates <- create_candidate_dataset(
  evidence_media_url = rep(
    "https://www.w3.org/TR/vocab-data-cube/",
    nrow(w3c_life_expectancy)
  ),
  evidence_text = rep(
    "W3C RDF Data Cube Vocabulary",
    nrow(w3c_life_expectancy)
  ),
  label = w3c_life_expectancy$observation,
  description = paste(
    "Life expectancy observation for",
    w3c_life_expectancy$area
  ),
  subject = w3c_life_expectancy$observation
)

w3c_candidates <- w3c_candidates |>
  add_candidate_column(
    name = "area",
    value = w3c_life_expectancy$area
  ) |>
  add_candidate_column(
    name = "period",
    value = w3c_life_expectancy$period
  ) |>
  add_candidate_column(
    name = "sex",
    value = w3c_life_expectancy$sex
  ) |>
  add_candidate_column(
    name = "life_expectancy",
    value = w3c_life_expectancy$life_expectancy
  )

w3c_candidates
#> # A tibble: 4 × 23
#>   row_number evidence_url evidence_media_url     evidence_text label description
#>        <int> <chr>        <chr>                  <chr>         <chr> <chr>      
#> 1          1 NA           https://www.w3.org/TR… W3C RDF Data… eg:o… Life expec…
#> 2          2 NA           https://www.w3.org/TR… W3C RDF Data… eg:o… Life expec…
#> 3          3 NA           https://www.w3.org/TR… W3C RDF Data… eg:o… Life expec…
#> 4          4 NA           https://www.w3.org/TR… W3C RDF Data… eg:o… Life expec…
#> # ℹ 17 more variables: alternative_label <chr>, alternative_description <chr>,
#> #   subject <chr>, subject_range <chr>, subject_definition <chr>, area <chr>,
#> #   area_range <chr>, area_definition <chr>, period <chr>, period_range <chr>,
#> #   period_definition <chr>, sex <chr>, sex_range <chr>, sex_definition <chr>,
#> #   life_expectancy <dbl>, life_expectancy_range <chr>,
#> #   life_expectancy_definition <chr>