Skip to contents

Write a Define-XML 2.1 file from a herald specification

Source: R/define-write.R
write_define_xml.Rd

Generates a valid Define-XML 2.1 document from a herald_spec object and writes it to disk. The output includes full namespace declarations for ODM 1.3, Define-XML 2.1 extensions, and Analysis Results Metadata (ARM) 1.0.

This is the inverse of read_spec: a spec created from any source (P21 Excel, programmatic, or parsed Define-XML) can be written out as Define-XML 2.1.

Usage

write_define_xml(spec, path, stylesheet = TRUE, validate = TRUE)

Arguments

spec

A herald_spec object. At minimum, ds_spec and var_spec must be populated.

path

File path for the output XML. Should end in .xml.

stylesheet

Logical. Include an XSL stylesheet processing instruction in the output XML and copy define2-1.xsl alongside the output file? Default TRUE. Browsers apply the stylesheet when both files are in the same directory (serve over HTTP — file:// URLs are blocked by most browsers). If define2-1.xsl already exists at the destination, it is not overwritten.

validate

Logical. Run DD0001–DD0085 Define-XML rules against the spec before writing? Default TRUE. Findings are reported as warnings; generation is never blocked.

Value

The output path, invisibly. The validation result (if run) is attached as the "validation" attribute.

SAS equivalence

Replaces the Pinnacle 21 Community / Enterprise "Generate Define-XML" workflow. In SAS, this is typically done via Pinnacle 21 macros or manual XML construction.

Round-trip

A spec round-trips through write/read for fields that the parser extracts:


write_define_xml(spec, "define.xml")
spec2 <- read_spec("define.xml")

The study, ds_spec, var_spec, codelist, methods, comments, arm_displays, and arm_results slots are preserved. Slots not yet parsed by read_spec (value_spec, dictionaries, documents) are written but will not round-trip.

See also

read_spec() for the inverse operation, herald_spec() for building specs.

Other specification: apply_spec(), coerce_types(), decode_var(), detect_adam_class(), detect_adam_classes(), drop_unspec_vars(), herald_spec(), order_cols(), read_spec(), read_spec_define(), scaffold_vars(), sort_keys(), spec_codelist(), spec_datasets(), spec_study(), spec_vars(), write_define_html(), write_spec()

Examples

spec <- herald_spec(
  ds_spec = data.frame(dataset = "DM", label = "Demographics",
                       stringsAsFactors = FALSE),
  var_spec = data.frame(dataset = "DM", variable = "STUDYID",
                        label = "Study Identifier", data_type = "text",
                        length = "12", stringsAsFactors = FALSE)
)

## -- Write to temporary file ----------------------------------------------
tmp <- tempfile(fileext = ".xml")
write_define_xml(spec, tmp, validate = FALSE)

## -- Round-trip -----------------------------------------------------------
if (requireNamespace("xml2", quietly = TRUE)) {
  spec2 <- read_spec(tmp)
  spec2$ds_spec$dataset # "DM"
}
#> [1] "DM"
unlink(tmp)