Review Layouts • betwixt

library(betwixt)

Review layouts and semantic projections

Betwixt supports the review of candidate semantic assertions before they are accepted into a stabilised semantic state. The same candidate knowledge can be presented in different tabular projections depending on what the reviewer needs to inspect.

This vignette introduces these projections through the delini example dataset. It distinguishes four related forms:

wide;
dual-wide;
long; and
dual-long.

These are not four different semantic models. They are different projections of the same underlying candidate assertions and their supporting information.

The wide projection is currently the primary browser-based review interface in Betwixt. The long projections are introduced here because they make the atomic claim structure explicit and clarify how the review representation relates to semantic graph statements.

The Delini example

The delini dataset provides a small heterogeneous cultural heritage example associated with the Delini farmstead at the Ethnographic Open-Air Museum of Latvia. It contains three artefacts and two archival records: the farmhouse, a tablet-woven sash, a bed, a record containing photographs of the farmhouse, and a floor plan prepared for its reconstruction.

The example combines four kinds of information required for semantic review: evidence, human-readable description, candidate semantic assertions, and display-only context.

data("delini")

delini
#> # A tibble: 5 × 16
#>   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…
#> # ℹ 10 more variables: 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>, context_1 <chr>

The columns belong to four functional groups:

Role	Columns	Purpose
Evidence	`evidence_url`, `evidence_media_url`, `evidence_text`	Identifies the evidence resource, media presented to the reviewer, and its human-readable description
Description	`label`, `description`	Identifies and describes the resource in human-readable form
Candidate assertions	`col_1`, `col_2`, `col_3` and their range and definition columns	Contains the semantic assertions proposed for review
Context	`context_1`	Provides information outside the current review boundary

In this review task, evidence_url identifies an evidence resource that the reviewer can open, while evidence_media_url identifies media that can be presented directly in the review interface. At least one of these must be present for each observation, and either may contain multiple pipe-separated URLs. evidence_text provides a short human-readable identification or description of the evidence. The semantic assertions begin with col_1, which identifies the subject; col_2 proposes its type through instance of; and col_3 proposes its heritage of association. These generic column names keep the candidate data structure independent of a particular ontology or presentation vocabulary.

Candidate columns may be accompanied by a _range and a _definition. Ranges provide controlled or suggested values, while definitions provide resolvable semantic references where available.

The delini dataset is already in the wide projection: each row brings together evidence, description, a subject, several candidate assertions, and context. The other projections rearrange or extend this same candidate semantic material while preserving these distinctions.

Projections are views of candidate knowledge

A semantic review task rarely needs to expose every aspect of a graph in its native graph representation. Betwixt therefore uses tabular projections to present a bounded part of candidate knowledge for a particular review task.

A projection changes how candidate knowledge is arranged for inspection. It does not, by itself, change what the assertions mean.

The Delini example can be represented in four closely related forms.

Wide projection

The wide projection places a subject and several candidate assertions about it on the same row:

Evidence | Subject | instance of | heritage of | Context

Predicates are represented by columns and their candidate values by cells. This keeps related assertions visible together and is particularly suitable for curators and domain experts who review a described resource rather than a sequence of atomic graph statements.

The wide projection therefore hides some graph mechanics without discarding semantic structure. It presents a bounded part of that structure in a task-oriented form. The delini dataset is represented in this wide form.

Dual-wide projection

The dual-wide projection adds a reviewable relation between the evidence and the subject:

Evidence | Evidence relation | Subject | instance of | heritage of | Context

This is useful when the presence of evidence alone does not establish how that evidence relates to the subject. An image may, for example, depict an artefact, while an archival resource may document it.

The evidence relation is a candidate assertion, not review provenance. Provenance instead records the review activity itself, including the reviewer, decisions, sequence, and timestamps.

The evidence relation is optional: ordinary wide review can present supporting evidence without making its relation to the subject part of the review task.

The dual-wide projection can therefore be derived directly from delini by adding the evidence relation and its controlled range:

delini_dual_wide <- delini |>
  dplyr::mutate(
    evidence_relation = c(
      "depicts", "depicts", "depicts", "documents", "documents"
    ),
    evidence_relation_range = candidate_range(
      "depicts", "documents", "Other…"
    ),
    .after = evidence_text
  )

delini_dual_wide
#> # A tibble: 5 × 18
#>   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      documents        
#> 5          5 NA           https://betwixt.datao… P7101623      documents        
#> # ℹ 13 more variables: evidence_relation_range <chr>, label <chr>,
#> #   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>, context_1 <chr>

The first three evidential resources depict the three artefacts, while the last two document the two archival records. All other candidate assertions remain unchanged.

Long projection

The long projection makes the atomic semantic claim structure explicit. Instead of representing predicates as columns, each row contains one subject–predicate–value assertion:

Evidence | Subject | Predicate | Value

The wide assertions concerning one subject therefore become multiple rows. In the Delini example, each resource has candidate instance of and heritage of assertions, so the five wide rows become ten atomic candidate claims.

The long projection can be derived directly from delini:

delini_long <- delini |>
  tidyr::pivot_longer(
    cols = c(col_2, col_3),
    names_to = "candidate_column",
    values_to = "value"
  ) |>
  dplyr::mutate(
    predicate = dplyr::recode(
      candidate_column,
      col_2 = "instance of",
      col_3 = "heritage of"
    ),
    subject = col_1
  ) |>
  dplyr::select(
    row_number,
    evidence_url, evidence_media_url, evidence_text,
    label, description,
    subject, predicate, value,
    context_1
  )

delini_long
#> # A tibble: 10 × 10
#>    row_number evidence_url evidence_media_url    evidence_text label description
#>         <int> <chr>        <chr>                 <chr>         <chr> <chr>      
#>  1          1 NA           https://betwixt.data… P7101565      Deli… the farmho…
#>  2          1 NA           https://betwixt.data… P7101565      Deli… the farmho…
#>  3          2 NA           https://betwixt.data… P7101561      tabl… a tablet-w…
#>  4          2 NA           https://betwixt.data… P7101561      tabl… a tablet-w…
#>  5          3 NA           https://betwixt.data… P7101556      bed … a bed in t…
#>  6          3 NA           https://betwixt.data… P7101556      bed … a bed in t…
#>  7          4 NA           https://betwixt.data… P7101590      reco… a record c…
#>  8          4 NA           https://betwixt.data… P7101590      reco… a record c…
#>  9          5 NA           https://betwixt.data… P7101623      reco… a floor pl…
#> 10          5 NA           https://betwixt.data… P7101623      reco… a floor pl…
#> # ℹ 4 more variables: subject <chr>, predicate <chr>, value <chr>,
#> #   context_1 <chr>

Each original row now produces two rows with the same subject: one for instance of and one for heritage of. The semantic content is unchanged; only its tabular projection has changed.

This representation makes the boundary of an individual assertion explicit and is closer to the subject–predicate–value structure used in graph serialization. It is therefore useful for semantic modelling, review-task design, data stewardship, and inspection of atomic candidate claims.

For domain-expert review, however, repeatedly presenting the same resource across several atomic rows may be less natural than seeing its related properties together. Wide and long are therefore not merely cosmetic table layouts: they provide different views of the same candidate semantic material for different review tasks.

Dual-long projection

The dual-long projection combines atomic semantic claims with an explicit, reviewable relation between the evidence and the subject:

Evidence | Evidence relation | Subject | Predicate | Value

It can be derived by pivoting the dual-wide projection in the same way as the ordinary wide projection:

delini_dual_long <- delini_dual_wide |>
  tidyr::pivot_longer(
    cols = c(col_2, col_3),
    names_to = "candidate_column",
    values_to = "value"
  ) |>
  dplyr::mutate(
    predicate = dplyr::recode(
      candidate_column,
      col_2 = "instance of",
      col_3 = "heritage of"
    ),
    subject = col_1
  ) |>
  dplyr::select(
    row_number,
    evidence_url, evidence_media_url, evidence_text,
    evidence_relation, evidence_relation_range,
    label, description,
    subject, predicate, value,
    context_1
  )

delini_dual_long
#> # A tibble: 10 × 12
#>    row_number evidence_url evidence_media_url    evidence_text evidence_relation
#>         <int> <chr>        <chr>                 <chr>         <chr>            
#>  1          1 NA           https://betwixt.data… P7101565      depicts          
#>  2          1 NA           https://betwixt.data… P7101565      depicts          
#>  3          2 NA           https://betwixt.data… P7101561      depicts          
#>  4          2 NA           https://betwixt.data… P7101561      depicts          
#>  5          3 NA           https://betwixt.data… P7101556      depicts          
#>  6          3 NA           https://betwixt.data… P7101556      depicts          
#>  7          4 NA           https://betwixt.data… P7101590      documents        
#>  8          4 NA           https://betwixt.data… P7101590      documents        
#>  9          5 NA           https://betwixt.data… P7101623      documents        
#> 10          5 NA           https://betwixt.data… P7101623      documents        
#> # ℹ 7 more variables: evidence_relation_range <chr>, label <chr>,
#> #   description <chr>, subject <chr>, predicate <chr>, value <chr>,
#> #   context_1 <chr>

Each row now exposes two distinct semantic relationships: the relation between the evidence and the subject, and one atomic assertion about that subject. As in the dual-wide projection, the evidence relation is a candidate assertion and remains distinct from review provenance.

The four projections therefore preserve the same basic semantic material while varying two dimensions: whether assertions are arranged in wide or atomic-long form, and whether the evidence relation is implicit or explicitly reviewable.

Relationship between the four projections

The four projections vary along two independent dimensions: wide versus long determines how semantic assertions are arranged, while ordinary versus dual determines whether the relation between evidence and subject is itself reviewable.

Projection	Assertion structure	Evidence relation
Wide	Multiple candidate predicates per row	Not reviewable
Dual-wide	Multiple candidate predicates per row	Reviewable
Long	One atomic candidate claim per row	Not reviewable
Dual-long	One atomic candidate claim per row	Reviewable

Moving from wide to long rearranges the same candidate assertions into atomic subject–predicate–value rows. Moving from ordinary to dual adds an explicit candidate assertion relating the evidence to the subject.

These projections therefore separate the semantic content of the candidate knowledge from its representation for a particular review task. The same candidate material can be projected differently without making one tabular representation canonical.

From review design to review execution

Long and wide projections support different stages of semantic review. The long form exposes atomic subjects, predicates, values, ranges, and definitions, making it useful for semantic modelling and review-task design. Once the relevant claims and permitted choices have been bounded, they can be presented in wide form for domain-expert review.

semantic and review design
          ↓
     atomic claims
          ↓
   bounded review task
          ↓
    wide projection
          ↓
  domain-expert review

This is a division of cognitive work rather than a hierarchy of semantic validity. The wide projection preserves the candidate semantic structure while presenting related assertions in a form suited to the review task.

Rendering the wide projection

Betwixt currently provides browser-based rendering for the wide projection. The renderer adapts the candidate dataset to the review interface without changing its semantic contract.

Evidence and descriptive information remain visible alongside the candidate assertions. Evidence media supplied through evidence_media_url can be presented directly in the interface, while evidence resources supplied through evidence_url are provided as links that the reviewer can open. An observation may contain either or both. Depending on the candidate data, reviewable values can be presented as resolved entities, editable unresolved entities, or controlled choices. Definitions can link to semantic resources, while controlled ranges constrain or guide the available values. Context remains visible but outside the review boundary.

A URL appearing as evidence is not thereby part of the candidate assertion. The same URL may independently occur as a reviewable candidate value, for example as an access point, without conflating these two semantic roles.

Reviewers can accept or modify candidate values, defer or reject assertions, and finalise reviewed rows. The interface also records review metadata, including the reviewer, project, review sequence, timestamps, and review status.

A review can be saved as a draft and subsequently finalised. Draft and finalised files from the same review cycle retain the same sequence number, so the standalone HTML preserves both the review interface and its current review state.

betwixt_render(
  delini,
  cols = c(
    col_1 = "Subject",
    col_2 = "instance of",
    col_3 = "heritage of",
    context_1 = "held by"
  ),
  subheadings = c(
    col_2 = "wdt:P31",
    col_3 = "controlled range"
  ),
  title = "Delini semantic review",
  description = "Review the proposed semantic assertions.",
  project_id = "delini",
  filename_stem = "delini-wide",
  sequence = 0L,
  path = tempdir()
)

The wide projection is the browser-rendered review interface in the current Betwixt implementation. The other Delini projections demonstrate how the same candidate knowledge can be rearranged or extended without making any one tabular representation canonical.