metadataSweepCapture: Reusable metadata sweep sessions

In DDIwR: DDI with R

Reusable metadata sweep sessions

Description

Capture metadata once and request ordered subsets for progressive displays, DialogR variable selectors, or DDI Codebook generation.

Usage

metadataSweepCapture(from, revision)

metadataSweepRead(
  session,
  revision,
  columns = NULL,
  fields = NULL,
  xml_options = list(),
  profile = "progressive"
)

metadataSweepInvalidate(session, revision)

metadataSweepClose(session)

Arguments

from	A data frame. The host must invalidate the session after edits, including edits made by reference.
revision	One non-missing atomic revision token, supplied by the host. Every read must supply the current token; a mismatch makes the session stale.
session	An object returned by metadataSweepCapture().
columns	Integer positions, allowing reordering and repetition, or unambiguous variable names. NULL selects all columns; integer() selects none.
fields	Requested field groups. NULL uses the selected profile.
xml_options	Named arguments passed to the variable XML generator.
profile	One of progressive, dialogr, or codebook.

Details

Capture copies stored metadata for all columns without cleaning labels or scanning observations. Normalization is cached only for requested columns. The progressive profile returns identity, annotations and category definitions without scanning values. Request classification, weight_signal, summaries or categories to analyse only the selected columns and cache their results. Category definitions (category_metadata) and frequencies (categories) are separate requests. The latter retain DDI's labelled-category semantics. Category definitions include UI rows plus the original typed labels, levels, na_values and na_range, without cleaning or inference.

The dialogr profile returns row records in projection$dialogr, following DialogR's type, measurement, category, display and selector-flag rules. Its value-dependent interpretation is cached per column, separately from DDI statistical analysis. Bare observation copies are shared by both consumers. The codebook profile returns variable XML and export metadata, reusing cached unweighted analysis. Weighted XML retains the existing weighted export path.

Generated IDs remain stable for the life of the session. Numeric positions are required to distinguish duplicate names. Hosts schedule batches and yield to their UI between calls; this API does not start background browser workers. Sessions are process-local and must be recaptured after serialization or edits. Value-dependent requests support logical, integer, double and character columns; unsupported storage (such as list columns) can be read as metadata but raises an error when values are requested. metadataSweepClose() releases caches and is idempotent; a finalizer also releases them. Closing or invalidating a session never changes the input data.

Value

Capture returns a session. Read returns an ABI-versioned columnar envelope with revision, columns, completed_fields, projection and cache counters. Invalidate and close return invisible NULL.

See Also

exportCodebook(), collectMetadata()

Examples

session <- metadataSweepCapture(iris, revision = 1L)
metadataSweepRead(session, 1L, columns = 1:2)
metadataSweepRead(session, 1L, columns = "Species", profile = "dialogr")
metadataSweepRead(session, 1L, profile = "codebook")
book <- makeElement("codeBook", children = list(makeElement("stdyDscr", fill = TRUE)))
path <- tempfile(fileext = ".xml")
exportCodebook(book, path, session = session, revision = 1L)
unlink(path)
metadataSweepClose(session)

DDIwR documentation built on Oct. 8, 2026, 9:06 a.m.