spec_codelists: Codelist terms

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

Codelist terms

Description

Return the controlled-terminology terms and decodes a spec carries: one codelist's terms when codelist_id names it, or the full codelists slot when codelist_id is NULL. Use it to inspect the values a coded variable is allowed to take before applying the spec. Mirrors the spec_variables() filter pattern.

Usage

spec_codelists(spec, codelist_id = NULL)

Arguments

spec	The specification to read. ⁠<artoo_spec>: required⁠.
codelist_id	The codelist to return. ⁠<character(1)> | NULL⁠. When NULL (default) the whole codelists table is returned. Restriction: a non-NULL id must name a codelist present in the spec's codelists slot; an unknown id aborts with artoo_error_input.

Value

A data frame of codelist terms, one row per term: every term when codelist_id is NULL, else the named codelist's terms. Columns:

• codelist_id — the codelist identifier variables reference.

• term — the submission value (what conformed data carries).

• decode — the human-readable decoded value.

• order — display order within the codelist.

• extended — TRUE marks an extensible codelist (sponsor terms allowed; non-members downgrade to notes in check_spec()).

• comment_id — reference into the comments slot.

See Also

spec_variables() for which variables reference a codelist.

Examples

# ---- Example 1: the terms behind a coded variable ----
#
# SEX is coded against C66731; spec_codelists() returns the terms and their
# decodes that apply_spec() will enforce or decode.
spec <- artoo_spec(
  cdisc_adam_datasets, cdisc_adam_variables,
  codelists = cdisc_codelists
)
spec_codelists(spec, "C66731")

# ---- Example 2: the whole codelists table ----
#
# Called with no id, it returns every term across every codelist.
head(spec_codelists(spec))

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