write_dataset: Write a dataset to any supported format

In artoo: Lossless CDISC-Native Input and Output for Clinical Datasets

Write a dataset to any supported format

Description

Serialize a data frame to a clinical file format, preserving its artoo_meta losslessly. The codec is chosen from the file extension (or an explicit format), so one call covers xpt, Dataset-JSON, Parquet, and rds. This is the emit end of the artoo workflow; the per-format wrappers like write_rds() are thin sugar over it.

Usage

write_dataset(x, path, format = NULL, ...)

Arguments

x	The dataset to write. ⁠<data.frame>: required⁠. Typically the output of apply_spec(), carrying artoo_meta.
path	Destination file path. ⁠<character(1)>: required⁠. Its extension selects the codec unless format is given.
format	Force a codec instead of inferring from the extension. ⁠<character(1)> | NULL⁠. One of the registered formats (see artoo_formats()).
...	Codec-specific arguments passed through to the encoder (see the per-format wrappers, e.g. write_xpt(), for what each codec accepts). An argument the codec does not know is an error, never silently ignored.

Value

The input x, invisibly, so a write can sit mid-pipeline. Called for the side effect of writing path.

See Also

read_dataset() for the inverse; write_rds() for the per-format wrapper; artoo_formats() for what is available.

Examples

spec <- artoo_spec(cdisc_adam_datasets, cdisc_adam_variables, codelists = cdisc_codelists)

# ---- Example 1: write a conformed dataset, inferring rds from the path ----
#
# apply_spec() attaches the metadata; write_dataset() carries it into the
# file so a later read is lossless.
adsl <- apply_spec(cdisc_adsl, spec, "ADSL", conformance = "off")
path <- tempfile(fileext = ".rds")
write_dataset(adsl, path)

# ---- Example 2: force the format for an unconventional extension ----
#
# When the extension does not name the format, pass it explicitly.
alt <- tempfile(fileext = ".data")
write_dataset(adsl, alt, format = "rds")

artoo documentation built on July 23, 2026, 1:08 a.m.