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
candidate_dataset(
evidence_url = NA_character_,
evidence_media_url = NA_character_,
evidence_text,
label,
description,
alternative_label = NA_character_,
alternative_description = NA_character_,
subject,
evidence_relation = NULL,
evidence_relation_range = NA_character_,
subject_range = NA_character_,
subject_definition = NA_character_
)Arguments
- 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
A character vector containing short identifiers or labels for the evidence.
- label
A character vector containing human-readable labels for the subjects presented for review.
- description
A 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.
- subject
A vector containing the subject identifiers or values to be reviewed. The subject is stored as the first candidate column,
col_1.- evidence_relation
An optional character vector describing a candidate semantic relation between the evidence and the subject, for example
"depicts". IfNULL, no evidence relation columns are added. Defaults toNULL.- evidence_relation_range
An optional character vector containing the admissible or suggested evidence relations. Use
candidate_range()to construct controlled ranges. This argument can only be used whenevidence_relationis supplied. Defaults toNA_character_.- subject_range
A character vector containing the admissible or suggested subject values. Use
candidate_range()to construct controlled ranges, orNA_character_when no controlled range is supplied. Defaults toNA_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 toNA_character_.
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, col_1,
col_1_range, and col_1_definition.
If evidence_relation is supplied, the tibble additionally contains
evidence_relation and evidence_relation_range.
Details
candidate_dataset() establishes the initial structure of a Betwixt
candidate dataset. row_number is generated automatically as an integer
sequence in input order.
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 <- candidate_dataset(
evidence_media_url = delini$evidence_media_url,
evidence_text = delini$evidence_text,
label = delini$label,
description = delini$description,
subject = delini$col_1,
subject_range = delini$col_1_range,
subject_definition = delini$col_1_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>,
#> # col_1 <chr>, col_1_range <chr>, col_1_definition <chr>
# Candidate dataset with a reviewable evidence relation
delini_dual_candidates <- candidate_dataset(
evidence_media_url = delini$evidence_media_url,
evidence_text = delini$evidence_text,
label = delini$label,
description = delini$description,
subject = delini$col_1,
subject_definition = delini$col_1_definition,
evidence_relation = rep("depicts", nrow(delini)),
evidence_relation_range = rep(
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>,
#> # col_1 <chr>, col_1_range <chr>, col_1_definition <chr>
# Statistical example based on the W3C RDF Data Cube Vocabulary
w3c_candidates <- 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(
value = w3c_life_expectancy$area
) |>
add_candidate_column(
value = w3c_life_expectancy$period
) |>
add_candidate_column(
value = w3c_life_expectancy$sex
) |>
add_candidate_column(
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>,
#> # col_1 <chr>, col_1_range <chr>, col_1_definition <chr>, col_2 <chr>,
#> # col_2_range <chr>, col_2_definition <chr>, col_3 <chr>, col_3_range <chr>,
#> # col_3_definition <chr>, col_4 <chr>, col_4_range <chr>,
#> # col_4_definition <chr>, col_5 <dbl>, col_5_range <chr>,
#> # col_5_definition <chr>