columns: View a dataset's variable attributes, SAS-style

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

View a dataset's variable attributes, SAS-style

Description

Return a one-row-per-variable attribute table — the pane a SAS programmer reads in ⁠PROC CONTENTS⁠ or the Universal Viewer: position, name, Char/Num type, length, format, informat, label, and the CDISC key sequence. This is the quick look after apply_spec() stamps a frame, or on any dataset file artoo can read.

Usage

columns(x, member = NULL)

Arguments

x	What to describe. ⁠<data.frame> | <character(1)>: required⁠. A stamped frame (carries artoo_meta), any plain data frame, or a path to a dataset file (.xpt, .json, .ndjson, .parquet, .rds).
member	XPORT member to describe. ⁠<character(1)> | NULL⁠. Only meaningful when x is a path to a multi-member .xpt file.

Details

Every real column shows. The table covers the frame's columns: a column the spec never declared (which apply_spec() keeps, never drops) still appears, its attributes inferred from the R class. A plain, never-stamped data frame works the same way — every attribute is inferred.

Len is physical storage. The pane mirrors what ⁠PROC CONTENTS⁠ shows and what the writers store, not a spec digit-width. A Char column always carries a byte Len (the declared length, else inferred from the data); a numeric Len is blank, because a numeric stores as an 8-byte IEEE double with no character width (a Define-XML numeric Length is a digit-width, kept in the metadata for the Define / P21 surface). Format and informat names render uppercase; the metadata keeps the source spelling.

A path reads through the codec. A file path is dispatched by extension through the same registry as read_dataset(), so the attributes come from the one lossless reader (an unknown extension aborts with the registry's known-extensions message).

Tip: a multi-member XPORT file needs ⁠member =⁠; without one the xpt reader aborts and points at xpt_members() for the listing.

Note: an .xpt path shows a blank Key: the XPORT byte layout stores only name, label, length, and formats, so keySequence (like codelist and origin) cannot ride in the file. The metadata-carrying formats (.json, .ndjson, .parquet, .rds) and the in-session conformed frame show it; re-apply the spec after an xpt read to restore it.

Value

A ⁠<artoo_columns>⁠ data frame with columns ⁠#⁠, Variable, Type, Len, Format, Label, Key, printed left-aligned. The Informat column appears only when at least one variable carries an informat (most clinical panes have none). It is an ordinary data frame underneath — filter or inspect it like one.

See Also

Members: xpt_members() lists a multi-member XPORT file.

Metadata: get_meta() for the full artoo_meta; apply_spec() which stamps it.

Examples

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

# ---- Example 1: the column pane of a conformed frame ----
#
# apply_spec() stamps ADSL with its metadata; columns() reads it back as
# the SAS-style attribute table.
adsl <- apply_spec(cdisc_adsl, spec, "ADSL", conformance = "off")
columns(adsl)

# ---- Example 2: straight off a file ----
#
# Write the conformed frame to any format and point columns() at the
# path; the codec reads it back and the attributes are identical.
p <- tempfile(fileext = ".json")
write_json(adsl, p)
columns(p)

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