Function reference¶
One section per function: what it does, every parameter with its type, and a worked example. The summary tables are in Expression syntax.
How to read this page¶
Two rules hold everywhere, so only departures from them are noted per function.
1. "" is a present value and is read literally. len("") is 0, upper("") is "". There
is no "empty means missing" behaviour — with one deliberate family of exceptions, the emptiness
predicates (empty / is_missing), whose whole purpose is to report "" and a genuine missing
alike. A section headed Missing and empty appears wherever a function departs from this.
2. A missing input propagates. A genuine missing value
passed to a function yields a missing result rather than a default, an error or a sentinel — so a
check built from ordinary functions ignores rows with missing data by construction. Where that is
not what you want, test for it with empty(x) explicitly.
Functions that reach outside the row have one more failure mode, and it is not an error.
record_count(domain="DS"), distinct(X, domain="TA"), read_value(…, domain=TS), the library and Define-XML lookups — each names something that
may not be there: an absent dataset, a filter no row satisfies, a group no row falls in, a name
the library holds nothing under.
Every such function is total over that. It answers with its own declared empty result —
a count answers 0, a set answers the empty set, a predicate answers false, a text lookup
answers "", a calculation answers missing — and the check then computes honestly over that
value. A section headed When there is nothing to answer states which, per function. ⚠ A few
library lookups are exceptions and SKIP the rule instead; their section says so.
⛔ An empty answer is a value, never a "do not fire".
record_count(domain="DS")on a study with noDSdataset is0, so$n == 0fires — the rule reports, it does not stand down. If the rule should not run at all when a dataset is missing, that isRequirements.Datasets, not something the function decides.
The target of distinct: one column, or a list of columns¶
distinct is the one function whose single positional argument decides the shape of its
answer (runbook W7, PLAN-distinct-function; like every function that reads another dataset it
takes that target as its only positional argument — see below). What that argument is decides what the function collects:
| you write | collects | meaning |
|---|---|---|
distinct(ARMCD, …) |
the column's distinct values | one column, or a value expression over the target dataset (distinct(upper(ARM), …)) |
distinct([ARMCD, ARM], …) |
the distinct row tuples | a list of columns |
There is no name= / names= keyword spelling: the positional argument is the target, and a
quoted name is a string literal that fails to load.
A list target yields row tuples¶
The two forms answer different questions. A single column yields the set of that column's values; a list yields the set of its row tuples, one per row of the source, in the order the list gives.
A tuple set is tested with tuple(…), which builds the same shape from the row in hand:
Bindings:
- name: "$ta_arm_pairs"
expression: 'distinct([ARMCD, ARM], domain="TA")'
Check:
expression: 'not empty(ARM) and not empty(ARMCD) and tuple(ARMCD, ARM) not in $ta_arm_pairs'
That is a real rule — "a populated ARM / ARMCD pair must coincide with a planned pair in TA". Comparing the two columns separately would accept a row that mixes one arm's code with another's description; comparing the pair does not.
⚠ The list is positional, so the order is part of the value.
tuple(ARMCD, ARM)matches a set built asdistinct([ARMCD, ARM], …); againstdistinct([ARM, ARMCD], …)it matches nothing. Which way that would show depends on the operator: underinthe rule silently never fires, undernot init fires on every row. Write the two in the same order and read them together.⭐ The loader now refuses both undecidable-by-hand cases (2026-09-21): a permutation of the same column names, and a length mismatch, are LOAD ERRORS naming the rule — so a reversed pair fails to load instead of quietly answering false forever. It cannot catch more than that, because the third case is legitimate:
⚠ Comparing differently named columns is legitimate and common —
tuple(PPNOMDY, PPTPTREF) not in distinct([PCNOMDY, PCTPTREF])pairs one dataset's columns against another's. It is only a permutation of the same names, or a length mismatch, that can never match.
Other parameters take a list in the same literal form: is_unique_set([USUBJID, --SEQ]),
contains_all(source, keys=[ARMCD]),
is_sorted_by(target, by=[asc(VISITNUM)]).
⚠ The one-positional rule holds for the functions that read another dataset —
distinct,max,max_date,min_dateandread_valuetake their target as the only positional argument, andrecord_counttakes none; a further positional (max_date(DSSTDTC, DS, group=[USUBJID])) is a load error naming the keyword spelling. An ordinary function takes as many positional arguments as it declares parameters —substring(AETERM, 1, 3)— as described under Arguments.
⛔ A type mismatch is a rule ERROR, not a coercion. Where a function requires a numeric
operand, a character column raises rather than being parsed; convert it with num(x) when the
text really is meant as a number. Sections that gate a type say so under Type error. The
general rules — including which operators gate — are in
Comparison.
Qualified group= members¶
The grouped functions that read another dataset — read_value, max,
max_date, min_date, record_count and
distinct — accept a qualified group= member. It keys the record's side of the
group through a join the rule declares:
Match_Datasets:
- Name: "DM"
Keys: ["USUBJID"]
Bindings:
- name: "$rprfdy"
expression: 'read_value(RPRFDY, domain="TP", group=[DM.RPATHCD, RPHASE], mode="MAX")'
TP is grouped by its own RPATHCD and RPHASE. A record of the evaluated dataset (say BW,
which has no RPATHCD) reads the group of the RPATHCD of its bound DM record and its own
RPHASE. The qualified name says where the record's value comes from; the unqualified name is
the same variable on the grouped side. There is no sided spelling: DM.RPATHCD groups on
RPATHCD.
domain=is required. Without it there is no other side — the evaluated dataset would be grouped by a value it does not carry — and the call is a load error. To group the evaluated rows by a joined value, use the rule-levelGrouping.- The qualifier names a
Match_Datasetsentry of the rule that is an ordinary keyed join (notChild: true, notRELREC, notSUPP--/SQ, no--template name, withKeys) andinner—Join_Type: "inner"or none. Anything else, and a qualifier naming no entry, is a load error — in everyChecklevel and every binding. - Load errors besides: a
--wildcard inside a qualified member (DM.--SEQ), and a qualified member together withrecord_count'sregex=(the regex normalises the grouped dataset's key values; the record's value comes from another dataset). A qualified name spliced intogroup=from a$list is not judged at load, so it errors the rule when it runs — write it in thegroup=list itself. So does a$member whose binding holds neither a list of names nor a single name — and when the binding's type already shows it at load (a number, or a per-row binding such asupper(AETERM)), the rule fails to load instead. A compiler-dispatched group operator such ashas_multiple_values_forhas no other side at all: a dotted member of itswithin=is refused. - The answer contract is the function's own. Only the key is read differently. A record whose
key has no group reads the function's no-group answer — the type default for
read_value, missing formax/max_date/min_date,0forrecord_count, the empty list fordistinct. A blankDM.RPATHCDis a key like any other (keep_missingsdefaults totrue): it reads the grouped dataset's blank-RPATHCDgroup if there is one, else the no-group answer. - Types are checked against the source. The grouped column's type is compared with the
source column's (
DM.RPATHCD), not with the evaluated dataset's; a character key on one side and a numeric one on the other makes the rule ERROR. - It is never dropped. A plain group column absent from a dataset partitions nothing; a
qualified member the rule cannot read makes it ERROR — no
DMdataset in the study,DMwithoutRPATHCD, or a grouped dataset that lacksRPATHCD(it needs the same variable, unqualified). That holds even when the grouped dataset has no rows. DeclareDM.RPATHCDandTP.RPATHCDinRequirements.Variables.Alland such a study skips the rule instead. - Copies are judged separately. The
DMjoin runs before any binding. If it is not one-to-one per record —DMcarrying a subject twice, on two paths — each copy of the record reads the group of its ownDMrecord, and the two copies may read two different values. Join on a key that makes the source one-to-one if the record should be judged once.
The same convention keys a Match_Datasets join through an earlier entry.
Presence and emptiness¶
available¶
available(op) → boolean
True when the named binding produced a result at all
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
Bindings:
- name: "$ds_count"
expression: 'record_count(domain="DS")'
Check:
expression: 'available($ds_count) and $ds_count == 0'
coalesce¶
coalesce(a, b[, c]) → value
The first operand that is neither missing nor ""
| parameter | type | required | description |
|---|---|---|---|
a |
any | yes | The first value |
b |
any | yes | The second value |
c |
any | no | An optional third value |
Example
Check:
expression: 'empty(coalesce(AEDECOD, AETERM, AELLT))'
Minimal — required parameters only
Check:
expression: 'empty(coalesce(AEDECOD, AETERM))'
Missing and empty — "" counts as not present and is skipped, exactly like a genuine missing: coalesce("", "a") returns "a", and an absent column is skipped as well. For numbers only a missing value is skipped — 0 and 0.0 are real values and are returned. When every operand is missing or "", the result is missing — and it is the missing the operands carry (rulings register D85c / D86a): one distinct identity among the genuinely missing operands gives that missing (coalesce(.A, "") is .A), two or more give the plain MIS (coalesce(.A, .B)), and none — every operand "" — gives the plain MIS. A plain missing, and an absent numeric column, count as the identity .: coalesce(.A, «missing» .) is MIS; an absent character column reads "" and contributes no identity.
ds_exists¶
ds_exists(x) → boolean
True when the named dataset is present in the run. A negated spelling ds_not_exists(x) exists; prefer not ds_exists(x).
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
Example
expression: 'ds_exists("SJ")'
empty¶
empty(x) → boolean
True when the value is missing or "". Also spelled is_missing. The positive spellings non_empty / present / is_present exist; prefer not empty(x).
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'empty(AGE)'
Missing and empty — This is one of the few places "" is not read literally: it reports both a genuine missing value and "" as empty. That is the function's purpose.
var_exists¶
var_exists(x) → boolean
True when the named column exists; accepts a -- wildcard, a dotted cross-dataset name, a SUPP QNAM pivot, a ${…} substitution and a computed name (var_exists(concat("ADSL.TRT", printf("%02d", APERIOD), "P"))). The column part of a dotted string matches in any letter case (var_exists("ADSL.trt01p") finds TRT01P); the dataset qualifier is matched as written. A negated spelling var_not_exists(x) exists; prefer not var_exists(x).
A written name (a literal or a column reference) is one fact for the whole dataset. A computed
name is tested per row — the rule runs at record level — and resolves exactly as the written
name would (the dataset through the run's resolver, the SUPP QNAM pivot included). A computed name
that starts with -- is not specialised to the domain: it answers as any absent name.
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
Example
expression: 'var_exists("AWU")'
Missing and empty — A computed name that is missing (or a value that is not text) fires for
neither polarity: var_exists(…) and not var_exists(…) are both false on that row.
var_is_null¶
var_is_null(x) → boolean
True when the column exists but no row in the dataset populates it
A qualified name (var_is_null(DM.DTHDTC), or the string "DM.DTHDTC") reads the joined column through its Match_Datasets entry over every row of the evaluated dataset, exactly as the operand DM.DTHDTC reads it — an unmatched row reads the column's type default, and an absent column or an undeclared join the absent default. (Until 2026-10-01 the dotted text was looked up on the primary and the call answered true, silently.)
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
Example
expression: 'varname() in $expected_variables and var_is_null(varname())'
Text¶
concat¶
concat(a, b[, c]) → value
Joins two or three values into one string; a missing operand makes the result missing
| parameter | type | required | description |
|---|---|---|---|
a |
any | yes | The first value |
b |
any | yes | The second value |
c |
any | no | An optional third value |
Example
Check:
expression: 'concat(STUDYID, "-", USUBJID) != SUBJID'
Missing and empty — A missing operand makes the result that missing value (rulings register D36: one missing part poisons the result). The identity is kept — .A in gives .A out — and when the operands carry two or more distinct missing identities the result is the plain MIS (D86a). A present "" contributes nothing, and so does an absent character column (it reads as "").
Minimal — required parameters only
Check:
expression: 'concat(DOMAIN, "SEQ") == varname()'
contains¶
contains(x, needle) → boolean
True when needle occurs anywhere in x; needle may vary per row. A negated spelling does_not_contain(x, needle) exists; prefer not contains(x, needle).
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
value |
any | yes | The value to compare against |
Example
expression: 'contains(--LAT, ";")'
count¶
count(x) → value
Number of elements in a list-valued operand — 1 for a present scalar, 0 for missing or "". Also spelled size.
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'count(library_variable_label_values) > 1'
Missing and empty — Counts elements, not characters: 1 for a present scalar, 0 for a missing one or "".
does_not_equal_string_part¶
does_not_equal_string_part(name, value, regex=) → boolean
True when value differs from capture-group 1 of regex= applied to name
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
value |
any | yes | The value to compare against |
regex |
string | yes | A regular expression, written as a string literal |
Example
expression: 'does_not_equal_string_part(SUFFIX, USUBJID, regex="-([0-9]+)$")'
ends_with¶
ends_with(x, needle) → boolean
True when x ends with needle; needle may vary per row
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
value |
any | yes | The value to compare against |
Example
expression: 'ends_with(varname(), "DT")'
equalsIgnoreCase¶
equalsIgnoreCase(x, y) → boolean
Case-insensitive string equality; two empties match
| parameter | type | required | description |
|---|---|---|---|
a |
any | yes | The first value |
b |
any | yes | The second value |
Example
expression: 'equalsIgnoreCase(RDOMAIN, "DM")'
has_alpha¶
has_alpha(x) → boolean
True when x contains any ASCII letter
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'has_alpha(LBTOXGR) and has_digit(LBTOXGR)'
has_digit¶
has_digit(x) → boolean
True when x contains any ASCII digit
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'has_alpha(LBTOXGR) and has_digit(LBTOXGR)'
has_equal_length¶
has_equal_length(name, n) → boolean
True when the value's length equals n. A negated spelling has_not_equal_length(name, n) exists; prefer not has_equal_length(name, n). n may be a number, numeric text or a per-row column.
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
length |
any | yes | How many characters to take |
Example
expression: 'has_equal_length(RDOMAIN, 8)'
⛔ Type error on a character n. The length operand must be numeric; a character column there raises a rule ERROR. Convert with num(n).
imatches¶
imatches(x, /re/) → boolean
Case-insensitive unanchored regex search
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
pattern |
regex | yes | The regular expression to match |
Example
expression: 'imatches(ARM, /placebo/)'
Missing and empty — A missing value matches no pattern, including one that would match an empty string.
is_valid_name¶
is_valid_name(x) → boolean
True when x is a valid uppercase SAS name of 1–8 characters
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'not is_valid_name(varname())'
is_valid_testcd¶
is_valid_testcd(x) → boolean
True when x is 1–8 characters starting with a letter or underscore
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'not empty(--TESTCD) and not is_valid_testcd(--TESTCD)'
len¶
len(x) → value
Length of the value in characters; len("") = 0. Also spelled length.
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'len(ETCD) > 8'
Missing and empty — len("") is 0 — an empty string is a present value of length zero. A genuine missing value yields that missing value, not 0 — identity kept (len(.A) is .A, rulings register D85c). An absent character column reads as all-"", so len(x) == 0 is true for it.
lower¶
lower(x) → value
The value lower-cased. Also spelled lowcase.
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'lower(SEX) == "m"'
Missing and empty — A missing input yields that missing value, identity kept (.A in, .A out — rulings register D36, owner 2026-09-28 "D36 stands"). "" is a present value and yields "".
List form — given a list (a $-binding such as get_column_order_from_dataset() or a
distinct(…) result), returns a new list with every element lower-cased, in order; a missing
element stays missing — it is carried through unchanged, in its position (missing propagates
through the string functions, register D36), never folded to "". Confirmed by the owner 2026-09-28 together
with upper's list form (rulings register CIT §3).
max_value_length¶
max_value_length([name]) → value
The longest value stored in the column, across all rows
A qualified name (max_value_length(DM.ARM), or the string form) reads the joined column through its Match_Datasets entry over every row of the evaluated dataset, exactly as the operand DM.ARM reads it. (Until 2026-10-01 the dotted text was looked up on the primary and the call answered 0, silently.)
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
Check:
expression: 'max_value_length(AETERM) > var_length("DEFINE")'
Minimal — required parameters only
Check:
expression: 'max_value_length() > 200'
normalize_space¶
normalize_space(x) → value
Trims the value and collapses each run of internal whitespace to a single space
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'upper(normalize_space(var_label("DATA"))) not in library_variable_label_values'
Missing and empty — A missing input yields that missing value, identity kept (rulings register D36). "" is a present value and yields "" (it used to yield missing).
prefix¶
prefix(x, n) → value
The first n characters; a shorter value is returned whole
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
n |
number | yes | A number of characters |
Example
expression: 'prefix(TSVCDREF, 5) == "CDISC"'
Missing and empty — A missing x yields that missing value, identity kept (rulings register D36); a missing n makes the result missing too (the identities of x and n combine per D86a: one distinct identity ⇒ that identity, two ⇒ MIS). "" yields "". A value shorter than n — or a non-positive or non-integral n — returns the value whole.
⛔ Type error on a character n. The length operand must be numeric; a character column there raises a rule ERROR. Convert with num(n).
prefix_matches¶
prefix_matches(x, /re/[, n]) → boolean
True when the first n characters match the regex, anchored; without n, the whole value
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
pattern |
regex | yes | The regular expression to match |
n |
number | no | A number of characters |
Example
Check:
expression: 'not prefix_matches(--TESTCD, /^[A-Z]+$/, 4)'
Minimal — required parameters only
Check:
expression: 'not prefix_matches(USUBJID, /^[0-9]+$/)'
Missing and empty — A missing value matches no pattern, including one that would match an empty string.
⛔ Type error on a character n. The length operand must be numeric; a character column there raises a rule ERROR. Convert with num(n).
split_by¶
split_by(x, "delimiter") → value
Splits the value on a literal delimiter into a list of tokens
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
delimiter |
string | yes | The literal string to split on |
Example
expression: 'not contains_all(var_codelist_coded_values("LIBRARY"), split_by(value(), ";"))` (`CDISC-SEND-0049`)'
Missing and empty — A missing x yields that missing value — a single value, not a list (rulings register D85c); "" yields the plain missing (MIS). Either way there are no tokens, so a membership test over it does not fire.
starts_with¶
starts_with(x, needle) → boolean
True when x begins with needle
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
value |
any | yes | The value to compare against |
Example
expression: 'starts_with(QNAM, "RACE")'
substring¶
substring(x, start[, length]) → value
The substring starting at start for length characters; 1-based, as in SAS
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
start |
number | yes | 1-based position of the first character |
length |
number | no | How many characters to take |
Example
Check:
expression: 'substring(USUBJID, 1, 4) != STUDYID'
Minimal — required parameters only
Check:
expression: 'empty(substring(AETERM, 2))'
Missing and empty — A missing x, start or length yields that operand's missing value, identity kept (rulings register D36; two or more distinct identities collapse to MIS, D86a). "" is evaluated literally against the bounds rather than being suppressed beforehand — substring("", 1) is a start past the end of a length-0 string, so it is the computed missing MIS.
⛔ Type error on character bounds. start and length must be numeric; a character column raises a rule ERROR. Convert with num(...).
suffix¶
suffix(x, n) → value
The last n characters; a shorter value is returned whole
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
n |
number | yes | A number of characters |
Example
expression: 'suffix(QNAM, 1) =~ /^[A-Z0-9]$/'
Missing and empty — As prefix: a missing x or n yields that missing value, identity kept (rulings register D36 / D86a); "" yields ""; a value shorter than n — or a non-positive or non-integral n — returns the value whole.
⛔ Type error on a character n. The length operand must be numeric; a character column there raises a rule ERROR. Convert with num(n).
suffix_matches¶
suffix_matches(x, /re/[, n]) → boolean
True when the last n characters match the regex, anchored; without n, the whole value
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
pattern |
regex | yes | The regular expression to match |
n |
number | no | A number of characters |
Example
Check:
expression: 'not suffix_matches(--DTC, /^[0-9]{2}$/, 2)'
Minimal — required parameters only
Check:
expression: 'not suffix_matches(VISIT, /^WEEK.*$/)'
Missing and empty — A missing value matches no pattern, including one that would match an empty string.
⛔ Type error on a character n. The length operand must be numeric; a character column there raises a rule ERROR. Convert with num(n).
trim¶
trim(x) → value
The value with leading and trailing whitespace removed
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'trim(QVAL) != QVAL'
Missing and empty — A missing input yields that missing value, identity kept (rulings register D36). "" yields "".
upper¶
upper(x) → value
The value upper-cased. Also spelled upcase.
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'not contains(upper(VISIT), upper("UNSCHEDUL"))'
Missing and empty — A missing input yields that missing value, identity kept (.A in, .A out — rulings register D36, owner 2026-09-28 "D36 stands"). "" is a present value and yields "".
List form — given a list (a $-binding such as get_column_order_from_dataset() or a
distinct(…) result), returns a new list with every element upper-cased, in order; a missing
element stays missing — it is carried through unchanged, in its position (missing propagates
through the string functions, rulings register D36), never folded to "". This is how a rule compares the dataset's
column names against the library's names (owner, 2026-09-28: "upper allows a list of strings as
parameter and returns a list of these strings converted to upper case"; rulings register
CIT §3): a column name a rule handles as a value is a string and compares exactly like one, so
the rule folds both sides — the owner's "compare the upper case version of a name against the
upper case version of a list of strings"; folding a library list is a no-op under the owner's
assumption that library names are upper case, and it spares the rule from deciding which side is
the library —
Bindings:
- name: "$required_variables"
expression: "required_variables()"
- name: "$dataset_variables"
expression: "get_column_order_from_dataset()"
- name: "$dataset_variables_upper"
expression: "upper($dataset_variables)"
- name: "$required_variables_upper"
expression: "upper($required_variables)"
- name: "$required_variables_absent_upper"
expression: "minus($required_variables, subtract=$dataset_variables_upper)"
- name: "$missing_required_variables"
expression: "minus($required_variables_absent_upper, subtract=$dataset_variables)"
Check:
expression: "not contains_all($dataset_variables_upper, $required_variables_upper)"
Outcome:
Output_Variables:
- "$missing_required_variables"
- "!$dataset_variables_upper"
- "!$required_variables_upper"
- "!$required_variables_absent_upper"
The un-folded bindings stay available for Output_Variables (each sibling is excluded with
!$x_upper), so a reported name keeps its own spelling; the two-step minus subtracts both
spellings of the dataset's names, so the missing list keeps a library name — or an unmatched template
such as TRTxxP — verbatim and drops a template instance the dataset carries in its own spelling. The
scalar spellings are upper(varname()) in $required_variables (the membership surface folds the
list too) and equalsIgnoreCase(varname(), var_name("LIBRARY")); a name test is
ends_with(upper(varname()), "DTC") / upper(varname()) =~ /^ANL\d\dFL$/. A QNAM / IDVAR
cell is a value and is not folded — it compares exactly, as every string does. The naming rules
(varname() =~ /.*[a-z]/, varname() !~ /^[A-Z0-9_]+$/ and kin) test the letter case of the name itself and are
never folded; a template carve-out tests the library name instead, var_name("LIBRARY") !~ /[a-z]/, which
needs no fold.
Numbers and arithmetic¶
abs¶
abs(x) → value
The absolute value of a number
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'abs(num(BASE) - num(AVAL)) > 0.001'
Missing and empty — A missing input yields that missing value, identity kept (abs(.A) is .A, rulings register D85c) — also through num: abs(num(X)) keeps X's .A. A non-numeric or empty input yields the plain missing (MIS).
⛔ Type error on a character column. The operand must be numeric; a character column raises a rule ERROR rather than being parsed. Convert it explicitly with num(x) if the text is meant as a number.
between¶
between(x, lo, hi) → boolean
True when lo <= x <= hi, inclusive
| parameter | type | required | description |
|---|---|---|---|
x |
number | yes | The value to read |
lo |
number | yes | The lower bound |
hi |
number | yes | The upper bound |
Example
expression: 'not empty(PARAMCD) and not between(char(PARAMCD), char("A"), char("Z"))'
⛔ Type error on a character column. All three operands must be numeric; a character column raises a rule ERROR. Convert with num(x).
ceil¶
ceil(x) → value
The smallest integer not less than x
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'ceil(ADY)'
Missing and empty — As abs: a missing input yields that missing value, identity kept (rulings register D85c); a non-numeric or empty input yields the plain missing (MIS).
⛔ Type error on a character column. The operand must be numeric; a character column raises a rule ERROR rather than being parsed. Convert it explicitly with num(x) if the text is meant as a number.
floor¶
floor(x) → value
The largest integer not greater than x
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'floor(ADY)'
Missing and empty — As abs: a missing input yields that missing value, identity kept (rulings register D85c); a non-numeric or empty input yields the plain missing (MIS).
⛔ Type error on a character column. The operand must be numeric; a character column raises a rule ERROR rather than being parsed. Convert it explicitly with num(x) if the text is meant as a number.
is_integer¶
is_integer(x) → boolean
True when the value is a finite whole number. A negated spelling is_not_integer(x) exists; prefer not is_integer(x).
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'not empty(PARAMN) and not is_integer(PARAMN)'
Missing and empty — "" is not a whole number, so this is false for it — and the negated spelling therefore fires on a blank.
is_numeric¶
is_numeric(x) → boolean
True when the value is a decimal number; there is no is_not_numeric — write not is_numeric(x)
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'is_numeric(--DOSTXT)'
Missing and empty — "" is not a number, so this is false for it.
minus¶
minus(value, subtract=) → value (a list)
The set difference of two lists — the members of value that are not in subtract, in value's order.
| parameter | type | required | description |
|---|---|---|---|
value |
list | yes | The minuend — a $-binding holding a dataset-level list, or a list literal of string literals (["AGEU", "SDESIGN"]) |
subtract |
list | yes | The subtrahend — a $-binding holding a dataset-level list, or a list literal of string literals |
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). Both operands are dataset-level lists, and only two spellings are accepted: a $-binding holding one (typically the answer of another list function), or a list literal. Anything else written inline — a column, a call (even a list function), any other expression — is a load error ("takes a dataset-level list — a $-binding of one or a list literal"): an inline operand would be read once, at row 0, and stand for every row, so bind it and read the binding. A $-binding that is computed per row (distinct(…, group=[…]), a per-variable value) is refused at load too ("the list function minus(…) … cannot read the per-row or per-variable binding"). A list literal must hold string literals — a bare [AGEU] names a column and fails to load. It is an aggregate: one list for the dataset. Members compare as set elements: a text against a text, a missing value by its identity, and a row tuple (from distinct([A, B], …)) structurally, component by component — never by its printed form.
Example
Bindings:
- name: "$untraceable"
expression: 'minus($ae_keys, subtract=$adae_keys)'
Check:
expression: 'not empty($untraceable)'
Minimal — required parameters only
Bindings:
- name: "$missing"
expression: 'minus(value=["AGEU", "SDESIGN"], subtract=$present)'
Check:
expression: 'not empty($missing)'
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. An empty minuend answers the empty set without reading subtract.
round¶
round(x) → value
The value rounded to the nearest integer, a half rounded up toward +∞ (round(-2.5) is -2)
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'round(AGE) == AGE'
Missing and empty — As abs: a missing input yields that missing value, identity kept (rulings register D85c); a non-numeric or empty input yields the plain missing (MIS).
⛔ Type error on a character column. The operand must be numeric; a character column raises a rule ERROR rather than being parsed. Convert it explicitly with num(x) if the text is meant as a number.
Dates and times¶
date_contains¶
date_contains(outer, inner) → boolean
True when every instant inner could denote lies inside outer's range
| parameter | type | required | description |
|---|---|---|---|
outer |
date | yes | The containing value |
inner |
date | yes | The value that must lie inside |
Example
expression: 'date_contains(date(RFSTDTC), date(AESTDTC))'
date_diff_days¶
date_diff_days(name, reference) → value
The calendar days from a reference date to a record's date — date − reference, with no +1 (unlike dy)
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The record's date column (--DTC, --STDTC, --ENDTC), or a column read through a declared join (PM.PMDTC) |
reference |
value | yes | The date to measure from: a column of the record, a column read through the rule's declared join, or a named aggregation — min_date(…) / max_date(…) over another dataset |
Both arguments are read per record. A reference that is the earliest (or latest) date of a group in another dataset is written as that aggregation, min_date(SJSTDTC, domain="SJ", group=[USUBJID, RPHASE]) — its domain=, group=, filter=, keep_missings= and missing_values= belong to min_date / max_date, never to date_diff_days. An offset is plain arithmetic — a constant (date_diff_days(…) + 1) or a value read from another dataset (+ $rprfdy). A date read from a matched record of another dataset is a declared join and a dotted name (Match_Datasets on the matching keys, then PM.PMDTC). A quoted name ("--DTC") is a string literal, never a column, and fails to load. (Until runbook W2b this was an operation with domain=, group=, reference="…", offset=, reference_extreme=, missing_values=, minuend_domain= and minuend_match= keywords; each is now spelled as above, and each is a load error on date_diff_days.)
Example
Match_Datasets:
- Name: "DM"
Keys: ["USUBJID"]
Bindings:
- name: "$sj_stages"
expression: 'record_count(domain="SJ", group=[USUBJID, RPHASE])'
- name: "$rprfdy"
expression: 'read_value(RPRFDY, domain="TP", group=[DM.RPATHCD, RPHASE], mode="MAX")'
- name: "$rpref_day"
expression: 'date_diff_days(--ENDTC, min_date(SJSTDTC, domain="SJ", group=[USUBJID, RPHASE])) + $rprfdy'
Check:
expression: 'is_complete_date(--ENDTC) and not empty(--RPENDY) and $sj_stages > 0 and not empty($rprfdy) and --RPENDY != $rpref_day'
The repro-phase day of CDISC-SEND-0403: the reference is the earliest SJSTDTC of the record's RPHASE, and the offset is the phase's first day reference RPRFDY (0 or 1) of the subject's own path, read from TP through the qualified read_value group= member DM.RPATHCD — the RPATHCD of the record's bound DM record. $sj_stages > 0 and not empty($rprfdy) leave a record whose phase has no SJ stage or no TP offset unjudged.
With an offset
Bindings:
- name: "$days_from_first_dose"
expression: 'date_diff_days(--DTC, min_date(EXSTDTC, domain="EX", group=[USUBJID])) + 1'
Check:
expression: 'is_complete_date(--DTC) and not empty(TFDETECT) and TFDETECT != $days_from_first_dose'
When there is nothing to answer — missing — the date or the reference lacks a complete yyyy-MM-dd part, a column is absent, or the aggregation has no answer for the record's group (no group, an absent dataset, an indeterminate extreme). A missing input's own missing is handed through. empty() on it is true, and a populated column compared with != against it fires: a derived day whose inputs cannot support it is reported, not skipped (EC-45) — declare the reference dataset's columns in Requirements if the rule should not run without them.
date_overlaps¶
date_overlaps(a, b) → boolean
True when the two date ranges share at least one possible instant
| parameter | type | required | description |
|---|---|---|---|
a |
date | yes | The first value |
b |
date | yes | The second value |
Example
expression: 'not date_overlaps(date(DSSTDTC), date(DM.DTHDTC))'
day¶
day(x) → value
The day component of an ISO value, or missing
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'is_complete_date(AESTDTC) and day(AESTDTC) > 28'
Missing and empty — A missing input yields that missing value, identity kept (day(.A) is .A, rulings register D85c). "" carries no date component and yields the plain missing (MIS).
dy¶
dy(name, reference) → value
The SDTM study day of a record's date relative to a reference date; there is no day 0
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The record's date column (--DTC, --STDTC, --ENDTC) |
reference |
column | yes | The reference date, read through the rule's declared join: DM.RFSTDTC, DM.RFXSTDTC or DM.RFCSTDTC |
Both arguments are column references. The reference is read per row through the Match_Datasets join the rule declares (DM on USUBJID), so on a subject that DM carries twice every row copy the join makes reads its own DM record — the same one the Check reads through DM.RFSTDTC. A quoted name (reference="RFXSTDTC") is a string literal, never a column, and fails to load; so does a call with one argument. (Until wave 1 of the operation→function programme dy(--DTC) was an operation that read DM itself and defaulted its reference to RFSTDTC.)
Example
Match_Datasets:
- Name: "DM"
Keys: ["USUBJID"]
Bindings:
- name: "$value_xstdy_algorithm"
expression: 'dy(--STDTC, DM.RFXSTDTC)'
Check:
expression: 'not empty(--XSTDY) and is_complete_date(--STDTC) and is_complete_date(DM.RFXSTDTC) and --XSTDY != $value_xstdy_algorithm'
Minimal — required parameters only
Match_Datasets:
- Name: "DM"
Keys: ["USUBJID"]
Bindings:
- name: "$value_dy_algorithm"
expression: 'dy(--DTC, DM.RFSTDTC)'
Check:
expression: 'not empty(--DY) and is_complete_date_part(--DTC) and is_complete_date_part(DM.RFSTDTC) and --DY != $value_dy_algorithm'
When there is nothing to answer — missing — the date or the reference lacks a complete yyyy-MM-dd part, or a column is absent. != against it fires (a missing is not equal to any value — rulings register D34a); == is true only against the same missing; an order comparison treats it as the lowest value (D34 #5): X > it and it < X fire, X < it does not; empty() is true.
Missing and empty — A missing date or reference yields that missing value, decided before the dates are parsed: with X = .A, dy(X, R) is .A whatever present value R holds (even an incomplete date), and with X = .A, R = .B it is the plain missing (rulings register D85c / D86a). Only present but incomplete or unparsable dates give the plain missing (MIS).
earliest_date¶
earliest_date(a, b) → value
The earlier of two dates — exactly what min_date answers over a group holding the two cells a and b: the same candidate rule and the same determinability rule, in the same accumulator, so the two can never drift. Written for a SEND subject's first dose, which is the earlier of the subject's own first dose and its pools' (recipe 9).
| parameter | type | required | description |
|---|---|---|---|
a |
date | yes | The first date — a column, a date(…) conversion, or a date-valued binding such as a min_date(…) result. Positional, or by name (a=) |
b |
date | yes | The second date, likewise. Positional, or by name (b=) |
Exactly two arguments; more than two nest (earliest_date(a, earliest_date(b, c))), which is exact for determinate operands but not the three-way extreme once an inner pair is undeterminable. A string literal argument fails the rule's load (a type error, stage A: PARAMETER_TYPE), as does a number literal — write earliest_date(date("2012-06"), date("2012-06-01")). The result is a date, so it meets date(X) != … and date(X) == … as a date. A numeric column is not refused: a number is never a complete calendar date, so it never wins — beside a date it makes the answer undeterminable (no answer) unless its text reads as a year (2020), which it then is — a partial date the other date can still beat — exactly as inside min_date. When the two arguments differ in column type (a numeric EXSTDTC read from an Excel serial beside a character one), the answer is typed as text, which only a character date or a missing can be. A numeric column passed directly as an argument is observed as a numeric date read, not an error — the same observe-only treatment date() over a numeric column has (D55). There is no missing_values= parameter: a per-part indeterminate belongs on the grouped call that feeds it.
Determinability (EC-46) — as min_date: the determined candidate that reaches every possible completion of the other wins, and its own cell is the answer. earliest_date(date("2012-06"), date("2012-06-01")) is 2012-06-01; earliest_date(date("2012-06"), date("2012-06-02")) has no answer (the partial could be the 1st); two partials have no answer; a present value that cannot be positioned (UNK, 2020-02-30) makes the answer undeterminable. On equal text a wins.
Example
# CDISC-SEND-0305
Bindings:
- name: "$min_ex_exstdtc"
expression: 'min_date(EXSTDTC, domain="EX", group=[USUBJID])'
- name: "$pool_min_exstdtc"
expression: 'min_date(min_date(EXSTDTC, domain="EX", group=[POOLID], filter=(not empty(POOLID))), domain="POOLDEF", group=[USUBJID])'
- name: "$first_exstdtc"
expression: 'earliest_date($min_ex_exstdtc, $pool_min_exstdtc)'
Check:
expression: 'not empty(RFXSTDTC) and (USUBJID in $ex_usubjid or $pool_ex_rows > 0) and date(RFXSTDTC) != $first_exstdtc'
Missing and empty — The extremes' candidate rule, not propagation: a missing argument (any identity) and a blank or whitespace-only argument are not candidates, and the other argument decides alone — earliest_date(.A, date("2020-01-01")) is 2020-01-01. So a grouped extreme that has no answer (a subject in no pool, an undeterminable pool) is skipped and the other part is taken. Only when both arguments are missing is their identity carried: .A and .A give .A, two distinct identities give the plain missing (rulings register D85c / D86a). Any other case with no answer — two blanks, a missing beside a blank, an undeterminable pair — is the plain missing (MIS). != against a missing answer fires (D34a); empty() on it is true.
earliest_possible¶
earliest_possible(x) → value
The earliest instant an incomplete value could denote
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'not empty(MHENDTC) and date(latest_possible(MHENDTC)) >= date(earliest_possible(DM.RFSTDTC))'
Missing and empty — A missing input yields that missing value, identity kept (rulings register D85c). "", and a value that cannot be placed on the calendar, yield the plain missing (MIS) — never a sentinel date.
interval_uncertainty_precision_mismatch¶
interval_uncertainty_precision_mismatch(name, delimiter=) → boolean
True on a row whose ISO 8601 interval of uncertainty (a/b) states its two halves at different precisions. Each half is measured after its timezone offset and fractional seconds are stripped, so an offset on one side only is not a precision difference. A value without the delimiter, a blank half, and a blank or missing value are false.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The interval column (--DTC, --STDTC, --ENDTC) |
delimiter |
string | no | The separator between the halves; default "/". Read per row, so any expression of string type may supply it; a missing or empty one is "/" |
name is a column reference; a quoted name ("LBDTC") is a string literal and fails to load. An absent column is a column of blanks, so the rule runs and fires on no row. (Until wave 3 of the operation→function programme this was an operation.)
Example
Bindings:
- name: "$interval_mismatch_stdtc"
expression: 'interval_uncertainty_precision_mismatch(--STDTC, delimiter="/")'
Check:
expression: '$interval_mismatch_stdtc == true'
Minimal — required parameters only
Bindings:
- name: "$interval_mismatch_dtc"
expression: 'interval_uncertainty_precision_mismatch(--DTC)'
Check:
expression: '$interval_mismatch_dtc == true'
is_complete_date¶
is_complete_date(x) → boolean
True when every date component is present
| parameter | type | required | description |
|---|---|---|---|
x |
string | yes | The value to read |
Example
expression: 'is_complete_date(--DTC)'
is_complete_date_part¶
is_complete_date_part(x) → boolean
True when the leading YYYY-MM-DD portion is complete, ignoring any time. A negated spelling is_not_complete_date_part(x) exists; prefer not is_complete_date_part(x).
| parameter | type | required | description |
|---|---|---|---|
x |
string | yes | The value to read |
Example
expression: 'not is_complete_date_part(--ENDTC)'
is_partial_date¶
is_partial_date(x) → boolean
True when the value is calendar-valid but has missing components. Also spelled is_incomplete_date.
| parameter | type | required | description |
|---|---|---|---|
x |
string | yes | The value to read |
Example
expression: 'is_partial_date(AESTDTC)'
is_valid_date¶
is_valid_date(x) → boolean
True when the value is a calendar-valid ISO date at any precision. A negated spelling invalid_date(x) exists; prefer not is_valid_date(x).
| parameter | type | required | description |
|---|---|---|---|
x |
string | yes | The value to read |
Example
expression: 'not is_valid_date(--DTC)'
Missing and empty — "" is not a calendar-valid date, so this is false for it — and invalid_date("") fires.
is_valid_duration¶
is_valid_duration(x) → boolean
True when the value is a valid ISO-8601 duration. A negated spelling invalid_duration(x[, negative=]) exists; prefer not is_valid_duration(x). negative= decides whether a negative duration counts.
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'is_valid_duration(--ELTM)'
Missing and empty — "" is not a valid duration, so this is false for it.
latest_date¶
latest_date(a, b) → value
The later of two dates — exactly what max_date answers over a group holding the two cells a and b, in the other direction from earliest_date, whose parameters, nesting, typing and missing rules it shares. Written for a SEND subject's last dose (CDISC-SEND-0306: the later of the subject's own latest EXENDTC and its pools').
| parameter | type | required | description |
|---|---|---|---|
a |
date | yes | The first date — a column, a date(…) conversion, or a date-valued binding. Positional, or by name (a=) |
b |
date | yes | The second date, likewise. Positional, or by name (b=) |
Determinability (EC-46) — as max_date: latest_date(date("2012-06"), date("2012-06-30")) is 2012-06-30; latest_date(date("2012-06"), date("2012-06-15")) has no answer (the partial could be the 30th). A date beside a datetime of the same day answers the date, whose hull ends at the end of the day.
Example
# CDISC-SEND-0306
Bindings:
- name: "$latest_exendtc"
expression: 'max_date(EXENDTC, domain="EX", missing_values="indeterminate", group=[USUBJID])'
- name: "$pool_latest_exendtc"
expression: 'max_date(max_date(EXENDTC, domain="EX", missing_values="indeterminate", group=[POOLID], filter=(not empty(POOLID))), domain="POOLDEF", group=[USUBJID])'
- name: "$last_exendtc"
expression: 'latest_date($latest_exendtc, $pool_latest_exendtc)'
Check:
expression: 'not empty(RFXENDTC) and (USUBJID in $ex_subjects or $pool_ex_rows > 0) and date(RFXENDTC) != $last_exendtc and date(RFXENDTC) != $last_exstdtc'
Missing and empty — As earliest_date: a missing or blank argument is skipped and the other decides; both missing carry their identity (.A + .A is .A, .A + .B is MIS); any other no-answer is the plain missing, and != against it fires.
latest_possible¶
latest_possible(x) → value
The latest instant an incomplete value could denote
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
Check:
expression: 'date(earliest_possible(--STDTC)) > latest_possible(--ENDTC)'
Missing and empty — As earliest_possible: a missing input yields that missing value, identity kept (rulings register D85c); "" and an unplaceable value yield the plain missing (MIS).
month¶
month(x) → value
The month component of an ISO value, or missing
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'is_complete_date(AESTDTC) and month(AESTDTC) > 12'
Missing and empty — A missing input yields that missing value, identity kept (month(.A) is .A, rulings register D85c). "" carries no date component and yields the plain missing (MIS).
time_contains¶
time_contains(outer, inner) → boolean
True when every time-of-day inner could denote lies inside outer's range
| parameter | type | required | description |
|---|---|---|---|
outer |
time | yes | The containing value |
inner |
time | yes | The value that must lie inside |
Example
expression: 'time_contains(time(VSTIM), time(EXTIM))'
time_overlaps¶
time_overlaps(a, b) → boolean
True when the two time-of-day ranges share at least one possible instant
| parameter | type | required | description |
|---|---|---|---|
a |
time | yes | The first value |
b |
time | yes | The second value |
Example
expression: 'not time_overlaps(time(ATM), time_part(ADTM))'
year¶
year(x) → value
The year component of an ISO value, or missing
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'year(BRTHDTC) < 1900'
Missing and empty — A missing input yields that missing value, identity kept (year(.A) is .A, rulings register D85c). "" carries no date component and yields the plain missing (MIS).
Aggregates over rows and groups¶
distinct¶
distinct(name, domain=, filter=, group=, keep_missings=) → value (a list)
The distinct values of a column, or the distinct row tuples over a list of columns — a registry
function since runbook W7 (PLAN-distinct-function), on the grouped cross-dataset plan max /
max_date / min_date (W5) and record_count (W6) established. Without group= it is one list
for the dataset; with group= (a column target only) it is each row's group's list, read per row
of the evaluated dataset. The answer is a set by content and a list by carrier: membership is
what it is for — X not in $set, X in $set, tuple(A, B) not in $pairs, contains($per_row,
"Y"), contains_all($a, $b), minus($a, subtract=$b).
| parameter | type | required | description |
|---|---|---|---|
name |
column, a value expression, or a list of columns | yes | The positional target. A column (USUBJID, --BLFL, upper(ARM)) collects its distinct values; a list ([VISIT, VISITNUM]) collects the distinct row tuples in that order — see The target of distinct. A quoted name is a string literal and fails to load |
domain |
dataset reference | no | The dataset to read: TA or "TA". Absent ⇒ the dataset under evaluation. With domain, every column argument names a column of that dataset. A -- in the dataset name resolves against the dataset under evaluation: domain="SUPP--" on AE reads SUPPAE (and on SUPPAE too), as Match_Datasets names do |
filter |
boolean over the target dataset's columns | no | Which rows are read, in parentheses: filter=(DSDECOD == "DEATH"), filter=(DSDECOD in ["TERMINAL SACRIFICE", "INTERIM SACRIFICE"]), filter=(RDOMAIN == "AE" and IDVAR == "AESEQ" and QNAM == "AESOSP"). Only bare columns of the target dataset — a dotted, $ or -- reference (under domain) is a load error. The retired map spelling filter=filter(K="v") fails to load, naming this one |
group |
list of columns | no | Columns whose combined value defines a group — on the target dataset; the list is read per row of the evaluated dataset by the same columns (an absent group column partitions nothing, on both sides). A column target only: group= beside a list target is a load error (the retired operation ignored it silently). A member may be qualified (DM.RPATHCD) with domain |
keep_missings |
boolean | no | Whether a row with a missing group key stays in its group (default true: the blank key forms its own group). Requires group= |
What is a value. A present, non-blank cell contributes its text — a numeric cell renders
as it does in a report (2, never 2.0) and the probe side compares as == does, so a numeric
VISITNUM meets the text member 2. A missing cell and a blank "" are not members: the set
of [S1, "", missing] is [S1], and a missing probe is a member of nothing. A tuple keeps
more: a present component as its text, a missing component as that missing (it is not "",
not ".", not 0 — (missing, "Day 0") is not (0, "Day 0")), an absent column as its type's
default (""; the missing for a column the rule expects numeric), and an IDVARVAL component as
its SUPP-- / RELREC join token (" 1", "01", "1.0" and "+1" are the token 1), so a
tuple(USUBJID, AESEQ) probe meets it. Two tuples are equal component by component, never by
their printed form.
Example — a value set across datasets
Bindings:
- name: "$scheduled_subjects"
expression: 'distinct(USUBJID, domain="DS", filter=(DSDECOD in ["TERMINAL SACRIFICE", "INTERIM SACRIFICE", "RECOVERY SACRIFICE", "NON-MORIBUND SACRIFICE"]))'
Check:
expression: 'USUBJID in $scheduled_subjects'
A tuple set
Bindings:
- name: "$ta_arm_pairs"
expression: 'distinct([ARMCD, ARM], domain="TA")'
Check:
expression: 'not empty(ARM) and not empty(ARMCD) and tuple(ARMCD, ARM) not in $ta_arm_pairs'
Grouped, read per row
Bindings:
- name: "$sv_visitnum"
expression: 'distinct(VISITNUM, domain="SV", group=[USUBJID])'
Check:
expression: 'not empty(VISITNUM) and VISITNUM not in $sv_visitnum'
Minimal — the dataset's own column
Bindings:
- name: "$domain_list"
expression: 'distinct(DOMAIN)'
Check:
expression: '$domain_is_custom == true and prefix(varname(), 2) not in $domain_list'
When there is nothing to answer — the empty list: an absent domain dataset, an absent
target column, a group no kept row reaches, a row of the evaluated dataset whose group the target
dataset does not have. X in $s is then vacuously false; X not in $s is vacuously true and
fires — the closed-world reading the operation always had.
⛔ The group keys are type-checked even when there is nothing to collect. A grouped call on
another dataset compares its group columns' types with the evaluated dataset's; a character key on
one side and a numeric key of the same name on the other makes the rule ERROR rather than
silently match no row — also when the target column is absent from domain and every group's
list would be empty.
Missing and empty — Always present — a list, never missing. (The former
distinct(IDVAR, value_is_reference=true), which never read IDVAR, is
referenced_dataset_variables(RDOMAIN).)
empty_within_except_last_row¶
empty_within_except_last_row(name, group, ordering=, keep_missings=) → boolean
True when a row other than the ordered-last one is unpopulated
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
group |
any | yes | Columns whose combined value defines a group |
ordering |
any | yes | Sort keys deciding row order inside the group |
keep_missings |
boolean | no | Whether a row with a missing key stays in its group |
Example
Check:
expression: 'empty_within_except_last_row(AEENDTC, group=[USUBJID], ordering=AESEQ, keep_missings=false)'
Minimal — required parameters only
Check:
expression: 'empty_within_except_last_row(AEENDTC, group=[USUBJID], ordering=AESEQ)'
has_mixed_emptiness_within_group¶
has_mixed_emptiness_within_group(name, group=, qualifying_any_populated=, keep_missings=) → boolean
true on every row of a group in which the subject column is populated on some rows and unpopulated on others
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The column whose emptiness is tallied (BASETYPE) |
group |
list of columns | no | Columns whose combined value defines a group; none, or none present, is one whole-table group |
qualifying_any_populated |
list of columns | no | Rows on which none of these columns is populated are out of scope (EC-23); an all-absent list qualifies no row |
keep_missings |
boolean | no | Whether a group whose key is missing is kept as its own group (default true, the fold) or dropped; requires a non-empty group |
Column parameters are column references — a quoted name is a string literal and fails to load — and an absent group column is dropped from the key (EC-44). An absent subject column is all-unpopulated, so no group is mixed (EC-45). The group key is compared by identity (4.9999999999994 and 5.0 are two groups, -0.0 and 0.0 one). (Until wave 1 of the operation→function programme this was an operation; the spelling is unchanged.)
Example
Bindings:
- name: "$basetype_mixed"
expression: 'has_mixed_emptiness_within_group(BASETYPE, group=[PARAMCD], qualifying_any_populated=[BASE, BASEC])'
Check:
expression: '$basetype_mixed == true'
Minimal — required parameters only
Bindings:
- name: "$basetype_mixed"
expression: 'has_mixed_emptiness_within_group(BASETYPE, group=[PARAMCD])'
Check:
expression: '$basetype_mixed == true'
When there is nothing to answer — false — a row in no group, or in a group that is not mixed, is false. It is not unknown.
is_last_in_group¶
is_last_in_group(ordering=, group=, keep_missings=) → boolean
true on every row whose ordering value is identical to its group's maximum — the last record of the group
| parameter | type | required | description |
|---|---|---|---|
ordering |
column | yes | The column that orders the group (SESEQ). It orders by its type: a numeric column numerically, a character column as text — "10" < "9", and "5" and "5.0" (or "-0.0" and "0.0") are two values — even when its values look like numbers. A missing value ranks lowest (two missing markers by their value byte), then a blank "". The order is total, so the answer never depends on row order. ⚠ ordering takes a plain column; a numeric order of a character column (num(X)) is not spellable here yet |
group |
list of columns | yes | Columns whose combined value defines a group (USUBJID); absent ones are dropped, all absent answers nothing |
keep_missings |
boolean | no | Whether a group whose key is missing is kept as its own group or dropped (default false, the drop); requires a non-empty group |
It takes no target: it reads only ordering and group. Both are column references — ordering="SESEQ" is a string literal and fails to load. "Identical" has one meaning, the key identity: a numeric -0.0 is 0.0, 4.9999999999994 is not 5.0, a character 5 is not 5.0 and a character -0.0 is not 0.0, and a missing is identical to the same missing. So every tied row is last: the copies a one-to-many Match_Datasets join makes of one record, a duplicated SESEQ in the source, and every row of a group whose ordering values are all missing. (Until wave 1 of the operation→function programme this was an operation whose tied rows all read false.)
Example
Bindings:
- name: "$is_last_se"
expression: 'is_last_in_group(ordering=SESEQ, group=[USUBJID], keep_missings=false)'
Check:
expression: '$is_last_se == true and date(SEENDTC) != date(DS.DSSTDTC)'
When there is nothing to answer — false — a row that is not the last of its group, a row dropped for a missing group key, or every row when the ordering column or every group column is absent. It is not unknown.
max¶
max(name, group=, domain=, filter=, keep_missings=) → value
The largest value of a column per group, broadcast to every row of the group — a registry
function since runbook W5 (PLAN-grouped-aggregate-functions), the pilot of the grouped
cross-dataset plan record_count and distinct follow.
| parameter | type | required | description |
|---|---|---|---|
name |
column of the target dataset, or any value expression over it | yes | The column to aggregate — bare, never quoted (max("AyIND", …) fails to load: a quoted name is a string). An expression is allowed: max(num(ATOXGR), …) ranks a character grade numerically |
group |
list of columns | yes | Columns whose combined value defines a group — on the target dataset; the value is read per row of the evaluated dataset by the same columns (an absent group column partitions nothing, on both sides). A member may be qualified (DM.RPATHCD) with domain |
domain |
dataset reference | no | The dataset to read from: DS or "DS". Absent ⇒ the dataset under evaluation. With domain, every column argument names a column of that dataset. A -- in the dataset name resolves against the dataset under evaluation: domain="SUPP--" on AE reads SUPPAE (and on SUPPAE too), as Match_Datasets names do |
filter |
boolean over the target dataset's columns | no | Which rows take part, in parentheses: filter=(ABLFL == "Y"). Only bare columns of the target dataset — a dotted, $ or -- reference (under domain) is a load error. The retired filter=filter(K="v") spelling fails to load, naming this one |
keep_missings |
boolean | no | Whether a row with a missing group key stays in its group (default true: the blank key forms its own group) |
One positional argument. The target is the only positional; every other argument is a keyword. A second
positional (max(DSSTDY, DS, group=[USUBJID])) is a load error naming the keyword spelling
("max takes one positional argument, its target; got 2 — write the others as keywords: …"),
never a silent binding to domain. The same holds for max_date and min_date.
Ranking by type. Candidates are the populated cells (a missing, empty or whitespace-only cell
is no candidate). A numeric column ranks numerically; a character column ranks as text —
"9" is above "10", and "3" and "3.0" are two different values (a string is a string,
D-W1-2a). The answer is the winning cell, with the column's own type, so a comparison against
it is numeric for a numeric column and textual for a character one. Numeric order of a character
grade is spelled max(num(ATOXGR), …). Text is text (owner K3, 2026-09-30: "no special
handling for special texts"): a character value that looks like a date ranks as text like any
other — max over 2024-01 and 2024-01-15 answers 2024-01-15 — and never takes the date rule;
max is not the function for dates — author max_date, which is.
Example
Bindings:
- name: "$baseline_ayind"
expression: 'max(AyIND, group=[USUBJID, PARAMCD, BASETYPE, SPDEVID], filter=(ABLFL=="Y"))'
Check:
expression: 'var_exists("BASETYPE") and not empty(ByIND) and ByIND != $baseline_ayind'
Another dataset
Bindings:
- name: "$max_ds_dsstdy"
expression: 'max(DSSTDY, domain="DS", group=[USUBJID])'
Check:
expression: 'USUBJID in $ds_usubjid and not empty(--DY) and not empty($max_ds_dsstdy) and --DY != $max_ds_dsstdy'
When there is nothing to answer — missing — for a group with no candidate (all cells
missing or blank, or a filter that keeps no row), and for a row of the evaluated dataset whose key
has no group (a subject with no DS row; an absent domain dataset). != against it fires (a missing is not equal to any value — rulings register D34a); == is true only against the same missing; an order comparison treats it as the lowest value (D34 #5): X > it and it < X fire, X < it does not; empty() is true. A group whose inputs are all missing carries their missing
identity.
max_date¶
max_date(name, group=, domain=, filter=, keep_missings=, missing_values=) → value
The latest date in a column per group, broadcast to every row of the group; a value that
cannot be positioned yields no value. A registry function since runbook W5; the parameters are
max's, plus:
| parameter | type | required | description |
|---|---|---|---|
missing_values |
"skip" · "indeterminate" |
no | How a missing input affects the result: skipped (the default), or making the group's extreme undeterminable (EC-51). "indeterminate" may only be consumed by a negative-polarity comparison (!=); a positive one (<, ==, …) is a load error, because it would read "no value" as "no violation" |
Determinability (EC-46). The extreme is answered only when a fully determined candidate wins
against every possible completion of every other candidate: max{2012-06, 2012-06-15} has no
answer (the partial could be the 30th), max{2012-06, 2012-06-30} is 2012-06-30. A present
value that cannot be positioned (UNK, a masked day) makes the group's extreme undeterminable.
The answer is the winning cell's own text.
One positional argument, as for max: max_date(DSSTDTC, DS, group=[USUBJID]) is a load
error naming the keyword spelling (domain="DS"), never a read of DS.
Example
Bindings:
- name: "$max_ex_exendtc"
expression: 'max_date(EXENDTC, domain="EX", missing_values="indeterminate", group=[USUBJID])'
Check:
expression: 'USUBJID in $ex_usubjid and date(RFXENDTC) != $max_ex_exstdtc and date(RFXENDTC) != $max_ex_exendtc'
Minimal — required parameters only
Bindings:
- name: "$max_ds_dsstdtc"
expression: 'max_date(DSSTDTC, domain="DS", group=[USUBJID])'
Check:
expression: 'SSSTRESC == "DEAD" and date(SSDTC) < $max_ds_dsstdtc'
When there is nothing to answer — missing — an undeterminable group, a group with no
candidate, and a row of the evaluated dataset whose key has no group. != against it fires (a missing is not equal to any value — rulings register D34a); == is true only against the same missing; an order comparison treats it as the lowest value (D34 #5): X > it and it < X fire, X < it does not; empty() is true.
min_date¶
min_date(name, group=, domain=, filter=, keep_missings=, missing_values=) → value
The earliest date in a column per group — the same contract as max_date, in the other direction
(min{2012-06, 2012-06-01} is 2012-06-01; min{2012-06, 2012-06-02} has no answer, the
partial could be the 1st). Its parameters, its -- resolution in domain= and its one positional
argument are max_date's: min_date(DSSTDTC, DS, group=[USUBJID]) is a load error naming the
keyword spelling.
Example
Bindings:
- name: "$min_ds_dsstdtc"
expression: 'min_date(DSSTDTC, domain="DS", group=[USUBJID], filter=(DSDECOD=="INFORMED CONSENT OBTAINED"))'
Check:
expression: 'not empty(DSSTDTC) and DSDECOD == "INFORMED CONSENT OBTAINED" and present_on_multiple_rows_within(DSDECOD, within=USUBJID) and $min_ds_dsstdtc == date(DSSTDTC) and $min_ds_dsstdtc != date(DM.RFICDTC)'
Minimal — required parameters only
Bindings:
- name: "$min_ds_dsstdtc"
expression: 'min_date(DSSTDTC, domain="DS", group=[USUBJID])'
Check:
expression: 'DSDECOD == "INFORMED CONSENT OBTAINED" and not empty(DSSTDTC) and date(DSSTDTC) == $min_ds_dsstdtc and not empty(DM.RFICDTC) and date(DM.RFICDTC) != $min_ds_dsstdtc'
When there is nothing to answer — missing, as for max_date.
An aggregate as another aggregate's target. The target of max_date / min_date (and of max) may itself be a grouped aggregate over a third dataset, evaluated on that dataset and broadcast to the target table's rows before the outer extreme is taken. The shipped use is a SEND subject's first dose per pool: EX records a pool's dose once, on a row whose POOLID is set and whose USUBJID is blank, and POOLDEF maps each pool to its subjects (SENDIG 3.1.1 §6.1.1, §8.5.1), so
- name: "$pool_first_dose"
expression: 'min_date(min_date(EXSTDTC, domain="EX", group=[POOLID], filter=(not empty(POOLID))), domain="POOLDEF", group=[USUBJID])'
reads, per POOLDEF row, the earliest EXSTDTC of that row's pool, and then per subject the earliest over the subject's pools. Three answers to know: a subject in two pools reads the earlier pool; a pool with no EX row (an FW or LB pool, which POOLDEF also defines) has no answer and is skipped by the outer extreme; a study without POOLDEF, or an EX without POOLID, answers missing for every subject — which is what makes earliest_date($own, $pool) fall back to the subject's own dose. ⚠ The inner call's filter=(not empty(POOLID)) is required: with POOLID absent from EX, group=[POOLID] partitions nothing and every EX row is one block keyed blank, which a POOLDEF row with a blank POOLID would take as its pool's first dose (a non-blank POOLID matches nothing); and an own EX row with a blank POOLID must never match a POOLDEF row with a blank POOLID. The inner call's target and filter columns (EXSTDTC, POOLID in the filter) are columns of its domain=, not of the outer target table; its group= columns (POOLID) are read on both its domain= and the outer target table — they are the key its answer is broadcast on, so POOLDEF must carry POOLID too. An inner call without domain= reads the outer target table itself.
present_on_multiple_rows_within¶
present_on_multiple_rows_within(name, within=) → boolean
True for every member of a group that has two or more rows
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
within |
any | yes | Columns that partition the rows |
keep_missings |
boolean | no | Whether a row with a missing key stays in its group |
Example
Check:
expression: 'present_on_multiple_rows_within(--TESTCD, within=[USUBJID, VISITNUM], keep_missings=false)'
Minimal — required parameters only
Check:
expression: 'present_on_multiple_rows_within(--TESTCD, within=[USUBJID])'
record_count¶
record_count(domain=, filter=, group=, keep_missings=, regex=) → value
The number of rows of a dataset — a registry function since runbook W6 (PLAN-record-count-function),
on the grouped cross-dataset plan max / max_date / min_date established (runbook W5). Without
group= it is one value for the dataset; with group= it is the count of each row's group,
read per row of the evaluated dataset. The bare record_count() is the dataset's row count.
| parameter | type | required | description |
|---|---|---|---|
domain |
dataset reference | no | The dataset to count: DS or "DS". Absent ⇒ the dataset under evaluation. With domain, every column argument names a column of that dataset. A -- in the dataset name resolves against the dataset under evaluation: domain="SUPP--" on AE reads SUPPAE (and on SUPPAE too), as Match_Datasets names do |
filter |
boolean over the target dataset's columns | no | Which rows are counted, in parentheses: filter=(TSPARMCD == "INDIC"), filter=(TSPARMCD == "INTTYPE" and TSVAL in ["DRUG", "BIOLOGIC"]), filter=(starts_with(QNAM, "RACE")), filter=(not empty(AEACN)). Only bare columns of the target dataset — a dotted, $ or -- reference (under domain) is a load error. The retired map spelling filter=filter(K="v") fails to load, naming this one |
group |
list of columns | no | Columns whose combined value defines a group — on the target dataset; the count is read per row of the evaluated dataset by the same columns (an absent group column partitions nothing, on both sides). A member may be a $-reference to a dataset-level list of column names (group=[USUBJID, --TESTCD, $TIMING_VARIABLES]), spliced in place; a per-row binding, or one typed as a number, is a load error. A quoted name ("USUBJID") is not a column and is a load error too. A member may be qualified (DM.RPATHCD) with domain — never spliced, and never beside regex= |
keep_missings |
boolean | no | Whether a row with a missing group key stays in its group (default true: the blank key forms its own group) |
regex |
regex | no | A regular expression, written as a string literal, applied to the group columns the way is_unique_set's regex= is: a group column whose first populated value matches is grouped by each value's first match ("^\\d{4}-\\d{2}-\\d{2}" collapses a date-time to its date); a column whose first value does not match is left as it is |
No target. record_count counts rows, never a column: the former positional target
(record_count(TSPARMCD, filter=…)) was never read and is a load error now — name the column in
filter=(…) or group=[…].
Example
Bindings:
- name: "$inttype_pharm_count"
expression: 'record_count(filter=(TSPARMCD == "INTTYPE" and TSVAL in ["DRUG", "BIOLOGIC", "VACCINE", "DIETARY SUPPLEMENT", "COMBINATION PRODUCT"]))'
Check:
expression: '$stype_interventional_count >= 1 and $inttype_pharm_count >= 1 and $pclas_count == 0'
Grouped, over another dataset
Bindings:
- name: "$dv_count"
expression: 'record_count(domain="DV", group=[USUBJID])'
Check:
expression: 'DSDECOD == "PROTOCOL DEVIATION" and $dv_count == 0'
Minimal — the row count
Bindings:
- name: "$bt_total"
expression: 'record_count()'
Check:
expression: '$bt_pop > 0 and $bt_pop < $bt_total'
When there is nothing to answer — 0 — a real count of nothing, not an absence of an answer: a
group no row of the filter reaches, a row of the evaluated dataset whose group the counted dataset
does not have, and a domain dataset the study lacks all read 0. So $n == 0 and $n <= 1 fire.
Missing and empty — Always present — a count, never missing.
row_max¶
row_max(name_pattern=) → value
The largest populated value, per row, among the columns whose names match a regular expression.
| parameter | type | required | description |
|---|---|---|---|
name_pattern |
string | yes | A regular expression over column names, matched in full and in any letter case. A static string literal — anything else, or a pattern that does not compile, fails to load |
row_max takes no column target: the pattern chooses the columns (row_max(TRTEDT, name_pattern=…) fails to load). Blank and missing cells are not candidates. The candidates rank by the matched columns' declared type, decided once for the dataset, never per row: a set of Num columns ranks numerically; a set of Char columns as text — text is text (owner K3, 2026-09-30): a date-looking value ranks as text like any other, so 2012-06 against 2012-06-15 answers 2012-06-15, never the date rule (max_date is the date function). A matched column with no candidate on any row takes no part in that decision — a CSV or Excel file delivers an all-blank TR02EDT as a Char column, and beside a numeric TR01EDT it is ignored rather than a mix. When Num and Char columns both carry values, the rule errors (a column-type mismatch): the two have no common order. A text value is never read as a number: CHAR "9" is larger than CHAR "12"; convert with num(…) for numeric order. On a tie the first candidate in column order wins. The winning cell is returned as it is, type and all.
Example
Bindings:
- name: "$trxx_max"
expression: 'row_max(name_pattern="^TR(0[1-9]|[1-9][0-9])EDT$")'
Check:
expression: 'not empty(TRTEDT) and not empty($trxx_max) and TRTEDT != $trxx_max'
The example above is the complete call.
When there is nothing to answer — missing: a row whose matched cells are all missing answers their missing value (identity kept when they agree); a row of blanks, an undeterminable date extreme, or a dataset with no matching column answers the plain missing. empty() on it is true, so guard with not empty($x) as the example does. (Until wave 3 of the operation→function programme this was an operation; it also accepted name / names, which it never read.)
tuple¶
tuple(c1, c2, …) → value
Builds a composite key from two to six columns, for whole-tuple membership
| parameter | type | required | description |
|---|---|---|---|
c1 |
column | yes | A column of the composite key |
c2 |
column | yes | A column of the composite key |
columns |
list of columns (absorbs the remaining arguments) | no | The columns forming the composite key |
Example
Check:
expression: 'not tuple(USUBJID, VISITNUM, --TESTCD) in distinct([USUBJID, VISITNUM, --TESTCD], domain="SV")'
Minimal — required parameters only
Check:
expression: 'not tuple(USUBJID, VISITNUM) in distinct([USUBJID, VISITNUM], domain="SV")'
variable_count¶
variable_count(name | name_pattern=) → value
A count of variables, in one of three forms — give the template or the pattern, never both (a load error: two counts under one name):
variable_count(name_pattern="^.+FL$")— the columns of the current dataset whose names match the regular expression (full match, letter case ignored);variable_count("--LNKGRP")— study-wide: the datasets of the study whose own--resolution of the template exists (AELNKGRP,CMLNKGRP, …), a split dataset family counted once;variable_count()— the number of columns of the current dataset.
| parameter | type | required | description |
|---|---|---|---|
name |
string | no | A -- variable-name template, resolved per dataset of the study |
name_pattern |
regex | no | A regular expression over the current dataset's column names |
A registry function since wave 4b of the operations→functions programme (PLAN-scalar-metadata-functions). It is an aggregate: one value for the dataset, computed once per rule and dataset and read by every row. Its arguments are read once per call, so each is a literal — a column or any other expression there fails to load. The template is a string ("--LNKGRP"): it names a column of every dataset, not of the current one, so a bare --LNKGRP fails to load. An invalid name_pattern fails to load (the retired operation counted 0, silently). The study-wide form reads the study inventory; a run whose dataset resolver cannot enumerate the study is a wiring defect and reports a rule ERROR (the retired operation counted the current dataset only).
Example
Bindings:
- name: "$treatment_variable_count"
expression: 'variable_count(name_pattern="^(ARM|ACTARM|TRTSEQ[PA]|TRT\\d\\d[PA]|TR\\d\\d[PA]G\\d+|TSEQ[PA]G\\d+|TRT[PA]|TRT[PA]G\\d+)$")'
Check:
expression: '$treatment_variable_count == 0'
Minimal — required parameters only
Bindings:
- name: "$variable_count"
expression: 'variable_count("--LNKID")'
Check:
expression: 'var_exists("--LNKID") and $variable_count < 2'
When there is nothing to answer — 0 — a real count of nothing, not an absence of an answer. So $n == 0 and $n <= 1 fire.
Uniqueness and consistency¶
has_multiple_values_for¶
has_multiple_values_for(name, key, within=, keep_missings=, include_empty=) → boolean
True when one key maps to more than one name — a functional-dependency violation; a blank key or value is excluded unless include_empty=true
| parameter | type | required | description |
|---|---|---|---|
name |
column reference (bare, or a --prefix reference) |
yes | The column to read — a quoted literal is a load error |
key |
column reference (bare, or a --prefix reference) |
yes | The column whose value acts as the key — a quoted literal is a load error |
within |
column reference or list of column references (bare, or --prefix) |
no | Columns that partition the rows, read by keyword only — a positional third argument (has_multiple_values_for(A, B, USUBJID)) is a load error since runbook W8 (it used to be bound and silently ignored), and so is a quoted literal |
keep_missings |
boolean | no | Whether a row with a missing key stays in its group |
include_empty |
boolean | no | Whether a blank key or value takes part |
Example
Check:
expression: 'has_multiple_values_for(ARMCD, ARM, within=[STUDYID], keep_missings=false, include_empty=false)'
Minimal — required parameters only
Check:
expression: 'has_multiple_values_for(ARMCD, ARM)'
Missing and empty — A blank key or dependent is excluded from the relationship unless include_empty=true.
has_same_values¶
has_same_values(name) → boolean
True on every row when the column has at most one distinct value
| parameter | type | required | description |
|---|---|---|---|
name |
column reference (bare, or a --prefix reference) |
yes | The column to read — a quoted literal is a load error |
Example
expression: 'not empty(MHCAT) and has_same_values(MHCAT)'
inconsistent_enumerated_columns¶
inconsistent_enumerated_columns(name) → boolean
True when the numbered series name, name1, name2 … has a gap
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
Example
expression: 'inconsistent_enumerated_columns(--VAL)'
is_inconsistent_across_dataset¶
is_inconsistent_across_dataset(name, keys=[…], include_empty=) → boolean
True on the minority rows of a group that disagrees; blank targets excluded unless include_empty=true
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
key |
any | no | The column whose value acts as the key |
keys |
list of columns | no | The values that must all be present |
include_empty |
boolean | no | Whether a blank key or value takes part |
keep_missings |
boolean | no | Whether a row with a missing key stays in its group |
Example
Check:
expression: 'is_inconsistent_across_dataset(--TEST, keys=[--TESTCD], include_empty=false, keep_missings=false)'
Minimal — required parameters only
Check:
expression: 'is_inconsistent_across_dataset(--TEST)'
Missing and empty — A blank target is excluded unless include_empty=true.
is_unique_relationship¶
is_unique_relationship(a, b) → boolean
True when a and b are in a strict one-to-one relationship. A negated spelling is_not_unique_relationship(a, b) exists; prefer not is_unique_relationship(a, b). A blank key or value is excluded.
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
value |
any | no | The value to compare against |
keys |
list of columns | no | The values that must all be present |
Example
Check:
expression: 'not is_unique_relationship(ARMCD, keys=[ARM])'
Minimal — required parameters only
Check:
expression: 'not is_unique_relationship(ARMCD, ARM)'
Missing and empty — A blank key or value is excluded from the relationship.
is_unique_set¶
is_unique_set([V1, V2, …]) → boolean
True when the tuple of the listed columns occurs exactly once. A negated spelling is_not_unique_set([…]) exists; prefer not is_unique_set([…]). An absent member is dropped, "" is a real component. A member is a column of the dataset under evaluation, written bare. A $ member splices a dataset-level binding exactly as record_count's group= does — a list of names element by element, a single name as one member; a per-row binding, or one typed as a number, fails the rule's load; a binding holding anything else, or a qualified name, makes the rule ERROR when it runs (until 2026-10-01 such a member was dropped silently as absent).
| parameter | type | required | description |
|---|---|---|---|
members |
list of columns | yes | The columns forming the tuple |
regex |
string | no | A regular expression, written as a string literal |
keep_missings |
boolean | no | Whether a row with a missing key stays in its group |
Example
Check:
expression: 'not is_unique_set([USUBJID, --TESTCD, VISITNUM], keep_missings=false)'
Minimal — required parameters only
Check:
expression: 'not is_unique_set([USUBJID, --SEQ])'
Missing and empty — "" is a real component of the tuple; an absent member is dropped wherever it sits.
is_unique_value¶
is_unique_value(name) → boolean
True when the value occurs exactly once in the column. A negated spelling is_not_unique_value(name) exists; prefer not is_unique_value(name).
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
Example
expression: 'not is_unique_value(USUBJID)'
Sets and ordering¶
contains_all¶
contains_all(source, keys=[…]) → boolean
True when the source's distinct values include every value in keys=. A negated spelling not_contains_all(source, keys=[…]) exists; prefer not contains_all(source, keys=[…]).
| parameter | type | required | description |
|---|---|---|---|
source |
any | yes | The column or list to look in |
required |
any | no | The values that must all be present |
keys |
list | no | The values that must all be present |
Example
Bindings:
- name: "$study_arms"
expression: 'distinct(ARMCD, domain="TA")'
Check:
expression: 'not contains_all($study_arms, keys=[ARMCD])'
Minimal — required parameters only
Bindings:
- name: "$study_arms"
expression: 'distinct(ARMCD, domain="TA")'
Check:
expression: 'not contains_all($study_arms)'
has_next_corresponding_record¶
has_next_corresponding_record(name, value, within=, ordering=, keep_missings=, relation=) → boolean
True when a following record in the group matches under relation=; authored under not
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
value |
any | yes | The value to compare against |
within |
any | yes | Columns that partition the rows |
ordering |
any | yes | Sort keys deciding row order inside the group |
relation |
string | no | How a record must relate to the next one |
keep_missings |
boolean | no | Whether a row with a missing key stays in its group |
Example
Check:
expression: 'not has_next_corresponding_record(--ENDTC, --STDTC, within=[USUBJID], ordering=--SEQ, relation="<=", keep_missings=false)'
Minimal — required parameters only
Check:
expression: 'not has_next_corresponding_record(--ENDTC, --STDTC, within=[USUBJID], ordering=--SEQ)'
Missing and empty — "" is compared literally, not treated as absent.
is_ordered_subset_of¶
is_ordered_subset_of(name, $b) → boolean
True when the column's values appear in $b in the same order. A negated spelling is_not_ordered_subset_of(name, $b) exists; prefer not is_ordered_subset_of(name, $b).
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
value |
any | yes | The value to compare against |
Example
expression: 'not is_ordered_subset_of($column_order_from_dataset, $model_column_order)'
is_sorted_by¶
is_sorted_by(target, by=[asc(col)[, nulls=]], within=) → boolean
True when the target is sorted by by=; authored under not, it fires the whole unsorted group
| parameter | type | required | description |
|---|---|---|---|
target |
column reference (bare, or a --prefix reference) |
yes | The column the function is about — a quoted literal is a load error |
by |
list of asc(COL) / desc(COL) descriptors |
yes | Sort keys — COL is bare (or --prefix); the quoted asc("COL") the engine used to require is a string literal since runbook W8 and fails to load. The asc/desc direction itself is declarative only — ExprCompiler.compileTargetIsNotSortedBy reads only the ordered column names and ignores it, matching the legacy operator |
within |
one column reference, or a one-element list (bare, or --prefix) |
no | The column that partitions the rows — a quoted literal is a load error, and so is a list of two or more columns (it used to run ungrouped) |
keep_missings |
boolean | no | Whether a row with a missing key stays in its group |
nulls |
"first" | "last" kwarg on a by=[…] descriptor |
no | asc(COL, nulls="first") — declarative only: the native evaluator (ExprCompiler.compileTargetIsNotSortedBy) reads the descriptor's column names and nothing else, so nulls= (default "last") has no runtime effect today; documented for the authoring surface, not as a behavioural guarantee |
Example
Check:
expression: 'not is_sorted_by(VISITNUM, by=[asc(VISITNUM)], within=[USUBJID], keep_missings=false)'
Minimal — required parameters only
Check:
expression: 'not is_sorted_by(VISITNUM, by=[asc(VISITNUM)])'
Missing and empty — keep_missings= decides whether a row with a missing sort key stays in its group.
shares_elements_with¶
shares_elements_with($a, $b) → boolean
True when the two lists have at least one member in common. A negated spelling shares_no_elements_with($a, $b) exists; prefer not shares_elements_with($a, $b).
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The column to read |
value |
any | no | The value to compare against |
keys |
list | no | The values that must all be present |
Example
Bindings:
- name: "$ae_subjects"
expression: 'distinct(USUBJID, domain="AE")'
Check:
expression: 'not shares_elements_with($ae_subjects, keys=[USUBJID])'
Minimal — required parameters only
Bindings:
- name: "$ae_subjects"
expression: 'distinct(USUBJID, domain="AE")'
Check:
expression: 'not shares_elements_with($ae_subjects)'
Dataset and domain metadata¶
dataset_class_from_library¶
dataset_class_from_library() → value
The CDISC Library's class name of the current dataset's domain (e.g. "BASIC DATA STRUCTURE"), looked up by the dataset's domain code.
A registry function since wave 4b of the operations→functions programme (PLAN-scalar-metadata-functions). It is an aggregate: one value for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one — or with one that could not be consulted — the rule is SKIPPED ("Rule skipped — no Library access"). Under the Define-XML fallback for an unreachable Library, a blank class means the define could not answer and the rule is SKIPPED too. (ds_class("LIBRARY") is not the same question: its tiered lookup answers where this one does not.)
Example
Bindings:
- name: "$dataset_class"
expression: 'dataset_class_from_library()'
Check:
expression: 'starts_with(ds_name("DATA"), "AD") and empty($dataset_class)'
The example above is the complete call.
When there is nothing to answer — missing — the calculation was not possible. != against it fires (a missing is not equal to any value — rulings register D34a); == is true only against the same missing; an order comparison treats it as the lowest value (D34 #5): X > it and it < X fire, X < it does not; empty() is true.
dataset_names¶
dataset_names() → value (a list)
The names of every dataset in the study, upper-cased, as a list — split members as themselves (LBCH, not LB; that is study_domains()'s question), SUPP-- and RELREC included.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and dataset_names(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It reads the study inventory; a run whose dataset resolver cannot enumerate the study is a wiring defect and reports a rule ERROR (the retired operation answered the empty set there, silently).
Example
Bindings:
- name: "$study_datasets"
expression: 'dataset_names()'
Check:
expression: 'not shares_elements_with($study_datasets, keys=[SUPPAE]) or $aetrtem_count < 1'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires.
domain_is_custom¶
domain_is_custom() → value (boolean)
Whether the CDISC Library declares the current dataset's domain a custom (sponsor) domain, looked up by the dataset's domain code: true or false.
A registry function since wave 4b of the operations→functions programme (PLAN-scalar-metadata-functions). It is an aggregate: one value for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one — or with one that could not be consulted — the rule is SKIPPED ("Rule skipped — no Library access"). ⚠ A Library that could not be consulted SKIPs the rule even under the Define-XML fallback: false ("not custom") is the answer that lets a rule fire, and a define cannot tell a custom domain — "custom" means "not in the standard", and the standard is what is missing.
Example
Bindings:
- name: "$domain_is_custom"
expression: 'domain_is_custom()'
Check:
expression: '$domain_is_custom == true and not var_exists("--TESTCD")'
The example above is the complete call.
When there is nothing to answer — it always answers, true or false; a Library that cannot answer SKIPs the rule instead.
ds_class¶
ds_class([x,] level) → value
The dataset's observation class; available at every level
At DATA it takes no argument: the DATA-level class is the evaluated dataset's, so ds_class("DM", "DATA") fails to load — write ds_class("DATA"), or read another dataset's class at DEFINE / LIBRARY.
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE/LIBRARY |
Example
expression: 'not empty(ds_class("DEFINE"))'
ds_domain¶
ds_domain("DATA") → value
The dataset's domain as Scope.Domains resolves it — SUPPLB, not the parent, on a SUPP dataset; DATA only
At DATA an argument names the dataset read (ds_domain("DM", "DATA")), resolved through the study's datasets like every dataset-naming read; a dataset the study lacks answers a missing. (Until 2026-10-01 the argument was ignored at DATA and the evaluated dataset answered.)
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA |
Example
expression: 'ds_domain("DATA") == "AE"'
ds_label¶
ds_label([x,] level) → value
The dataset's label; available at every level
At DATA an argument names the dataset read (ds_label("DM", "DATA")), resolved through the study's datasets like every dataset-naming read; a dataset the study lacks answers a missing. (Until 2026-10-01 the argument was ignored at DATA and the evaluated dataset answered.)
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE/LIBRARY |
Example
expression: 'ds_label("DATA") != "Device-level Analysis Dataset"'
ds_name¶
ds_name([x,] level) → value
The dataset's name; available at every level
At DATA an argument names the dataset read (ds_name("DM", "DATA")), resolved through the study's datasets like every dataset-naming read; a dataset the study lacks answers a missing. (Until 2026-10-01 the argument was ignored at DATA and the evaluated dataset answered.)
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE/LIBRARY |
Example
expression: 'ds_name("DATA") !~ /^[A-Z0-9_]{1,8}$/'
ds_structure¶
ds_structure([x,] level) → value
The dataset's ADaM data structure; DEFINE and LIBRARY only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE/LIBRARY |
Example
expression: 'ds_structure("DEFINE")'
extract_metadata¶
extract_metadata(name) → value
One dataset-metadata value of the current dataset, named by its key: "dataset_name", "dataset_label", "dataset_size" (bytes of the parsed file), "dataset_location" / "filename" (the source file's name), or any other key the dataset's reader publishes ("file_format", …).
| parameter | type | required | description |
|---|---|---|---|
name |
string | yes | The metadata key |
A registry function since wave 4b of the operations→functions programme (PLAN-scalar-metadata-functions). It is an aggregate: one value for the dataset, computed once per rule and dataset and read by every row. Its arguments are read once per call, so each is a literal — a column or any other expression there fails to load.
Example
Bindings:
- name: "$dataset_location"
expression: 'extract_metadata("dataset_location")'
Check:
expression: '$dataset_location =~ /[A-Z]/'
The example above is the complete call.
When there is nothing to answer — missing — the calculation was not possible. != against it fires (a missing is not equal to any value — rulings register D34a); == is true only against the same missing; an order comparison treats it as the lowest value (D34 #5): X > it and it < X fire, X < it does not; empty() is true.
referenced_dataset_variables¶
referenced_dataset_variables(name) → value (a list)
The variable names of the dataset named in a column value, per row — the list a SUPP-- / CO /
RELREC record's RDOMAIN refers to, so a Check tests the row's IDVAR against its referenced
dataset's columns, never a flat union over every referenced domain. A registry function since
runbook W7 (PLAN-distinct-function), replacing distinct(IDVAR, value_is_reference=true),
which never read its target.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The column naming a dataset (RDOMAIN) |
name is a column reference and is required — the former implicit RDOMAIN read is spelled
out. Per row the answer is the column-name list of every dataset member whose domain is the value
(a split family unions its members, in declaration order), in the datasets' own spelling —
upper($vars) folds the list element by element. A missing or blank value, or a value no dataset
carries, answers the empty list. The function reads the study's own datasets, never the CDISC
Library.
Example
Bindings:
- name: "$rdomain_variables"
expression: 'referenced_dataset_variables(RDOMAIN)'
- name: "$rdomain_variables_upper"
expression: 'upper($rdomain_variables)'
Check:
expression: 'var_exists("RDOMAIN") and not empty(IDVAR) and IDVAR not in $rdomain_variables and IDVAR not in $rdomain_variables_upper'
The example above is the complete call.
When there is nothing to answer — the empty list — no dataset of that name, a blank or
missing RDOMAIN: IDVAR not in $rdomain_variables fires, IDVAR in does not.
Missing and empty — Always present — a list, never missing.
referenced_domain_class¶
referenced_domain_class(name) → value
The CDISC Library observation class of the domain named in a column value, per row — upper-cased (EVENTS, FINDINGS ABOUT, …) whatever the Library's own spelling, or "" when the Library cannot classify the domain.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The column naming a domain (RDOMAIN) |
name is a column reference and is required — the former RDOMAIN default is gone. A missing cell answers that missing value. The function needs the CDISC Library: with none configured, or one that could not be consulted, the rule reports SKIPPED. (Until wave 3 of the operation→function programme this was an operation.)
Example
Bindings:
- name: "$rdomain_class"
expression: 'referenced_domain_class(RDOMAIN)'
Check:
expression: '$rdomain_class not in ["EVENTS", "INTERVENTIONS", "FINDINGS", "FINDINGS ABOUT"] and RDOMAIN != "DM" and RDOMAIN != "SV"'
The example above is the complete call.
When there is nothing to answer — "" — the closed-world reading: the Library holds no class for that domain. So a not in / != against a class literal fires.
split_sibling_length_mismatch¶
split_sibling_length_mismatch() → value (a list)
The variables whose declared column length differs across the current dataset's split-family members (every dataset whose data-driven unsplit name equals the current one's), as a list — library-independent.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and split_sibling_length_mismatch(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It reads the study inventory; a run whose dataset resolver cannot enumerate the study is a wiring defect and reports a rule ERROR (the retired operation answered the empty set there, silently).
Example
Bindings:
- name: "$len_mismatch"
expression: 'split_sibling_length_mismatch()'
Check:
expression: 'varname() in $len_mismatch'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. A dataset that is not split, and a family whose shared variables all agree, answer it.
standard_domains¶
standard_domains() → value (a list)
The domain codes the standard publishes, as a list.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and standard_domains(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access").
Example
Bindings:
- name: "$sdtm_domains"
expression: 'standard_domains()'
Check:
expression: 'not empty(SRCDOM) and SRCDOM not in $sdtm_domains'
The example above is the complete call.
When there is nothing to answer — ⚠ the rule is SKIPPED, an exception to the totality rule above: a Library that publishes no dataset names for the standard is library not available ("Rule skipped — library returned no data for standard_domains").
study_domains¶
study_domains() → value (a list)
The distinct data-driven SDTM domain codes across the study — the DOMAIN cell of each dataset, not its member name — as a list: a split LB (lbch / lbhe) contributes one LB, which is what an RDOMAIN of LB matches; the no-domain datasets (SUPP--, RELREC) contribute "".
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and study_domains(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It reads the study inventory; a run whose dataset resolver cannot enumerate the study is a wiring defect and reports a rule ERROR (the retired operation answered the empty set there, silently).
Example
Bindings:
- name: "$study_domains"
expression: 'study_domains()'
Check:
expression: 'not empty(RDOMAIN) and RDOMAIN not in $study_domains'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires.
Variable metadata¶
The var_* accessors read the metadata of a variable of the dataset under evaluation, so the
name they take is written bare: a qualified literal (var_label("DM.AGE", "DATA"),
var_core("DM.AGE", "LIBRARY")) fails to load at every level, naming the bare spelling. Another
dataset's DATA-level label, type, length or format is read with dataset=
(var_label("AGE", "DATA", dataset="DM")), whose variable name matches in any letter case.
(Until 2026-10-01 a qualified literal was looked up verbatim and answered a missing — at LIBRARY
a false finding on every row of var_core("DM.AGE", "LIBRARY") != "Req".)
column_series_metadata¶
column_series_metadata([name,] name_pattern=, min_length=) → value (boolean)
Whether a numbered column series (COVAL1..n) is incomplete: its members are the columns whose names match name_pattern (by their trailing number) plus the optional un-numbered base column name as member 0. true (the check fires) when the present numbers are not contiguous from the lowest to the highest, or when min_length is given and a member other than the last declares a length below it; false with fewer than two members.
| parameter | type | required | description |
|---|---|---|---|
name |
string | no | The un-numbered base column's name |
name_pattern |
regex | yes | A regular expression over column names |
min_length |
number | no | The length every non-terminal member must reach |
A registry function since wave 4b of the operations→functions programme (PLAN-scalar-metadata-functions). It is an aggregate: one value for the dataset, computed once per rule and dataset and read by every row. Its arguments are read once per call, so each is a literal — a column or any other expression there fails to load. The base column is named by a string ("COVAL") — its metadata is read, not its values — so a bare COVAL fails to load; an invalid name_pattern or a non-integer min_length fails to load too.
Example
Bindings:
- name: "$coval_series_incomplete"
expression: 'column_series_metadata("COVAL", name_pattern="^COVAL\\d+$", min_length=200)'
Check:
expression: '$coval_series_incomplete == true'
Minimal — required parameters only
Bindings:
- name: "$coval_series"
expression: 'column_series_metadata(name_pattern="^COVAL\\d+$")'
Check:
expression: '$coval_series == true'
When there is nothing to answer — false — the predicate was evaluated and did not hold. It is not unknown.
cross_dataset_variable_metadata¶
cross_dataset_variable_metadata(name, domain=) → value (per variable)
Per variable of the current dataset, one metadata attribute — "label", "data_type" (Char / Num), "length" or "format" — of the same-named variable in another dataset: the one domain= names, or with domain="*" the first dataset of the study that carries the variable (shortest name first, then alphabetical — so an SDTM domain wins over an ADaM dataset), the current dataset excluded by its name.
| parameter | type | required | description |
|---|---|---|---|
name |
string | yes | The attribute: label, data_type, length or format |
domain |
string | yes | The dataset to read from, or "*" for the whole study |
A registry function since wave 4b of the operations→functions programme (PLAN-scalar-metadata-functions). It is an aggregate: one value for the dataset, computed once per rule and dataset and read by every row. Its arguments are read once per call, so each is a literal — a column or any other expression there fails to load. Its one value is the whole per-variable answer, which the rule reads variable by variable: a Check comparing var_label("DATA") != $x runs once per variable and sees that variable's value (reported in the finding too). It is read only through a binding — written inline in a Check it fails to load. domain is a string, since "*" is a pattern, not a dataset; an attribute outside the four fails to load (the retired operation answered nothing, silently).
Example
Bindings:
- name: "$adsl_data_type"
expression: 'cross_dataset_variable_metadata("data_type", domain="ADSL")'
Check:
expression: 'not empty($adsl_data_type) and var_type("DATA") != $adsl_data_type'
Minimal — required parameters only
Bindings:
- name: "$sdtm_label"
expression: 'cross_dataset_variable_metadata("label", domain="*")'
Check:
expression: 'not empty($sdtm_label) and var_label("DATA") != $sdtm_label'
When there is nothing to answer — missing for a variable the other dataset does not carry, and for every variable when the named dataset is not in the study. != against it fires (a missing is not equal to any value — rulings register D34a); == is true only against the same missing; an order comparison treats it as the lowest value (D34 #5): X > it and it < X fire, X < it does not; empty() is true.
duplicate_label_variables¶
duplicate_label_variables() → value (a list)
The variables of the current dataset whose declared label is shared by another of its columns, as a list; a blank label is never a duplicate.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and duplicate_label_variables(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row.
Example
Bindings:
- name: "$dup_labels"
expression: 'duplicate_label_variables()'
Check:
expression: 'varname() in $dup_labels'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. Every label unique answers it.
expected_variables¶
expected_variables() → value (a list)
The variables the CDISC Library marks Expected for this dataset, as a list — for an ADaM dataset, the expected variables of its detected data structure(s), naming templates substituted against the dataset's own columns.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and expected_variables(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access").
Example
Bindings:
- name: "$expected_variables"
expression: 'expected_variables()'
Check:
expression: 'not contains_all($dataset_variables, $expected_variables)'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. ⚠ Two exceptions SKIP the rule instead: an ADaM dataset for which the declared product publishes no data structure ("Rule skipped — library returned no data for expected_variables"), and the Define-XML fallback for an unreachable Library answering nothing.
get_column_order_from_dataset¶
get_column_order_from_dataset() → value (a list)
The dataset's own column names in declaration order, in the dataset's own spelling, as a list — the "actual" side of a presence or ordering check.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and get_column_order_from_dataset(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row.
Example
Bindings:
- name: "$dataset_variables"
expression: 'get_column_order_from_dataset()'
Check:
expression: 'not shares_elements_with($dataset_variables, $timing_variables)'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. (A dataset with no columns is the only way to get it.)
get_column_order_from_library¶
get_column_order_from_library() → value (a list)
The column order the CDISC Library publishes for this dataset, as a list — the IG-defined variable order for the dataset's domain, the "expected" side of an ordering check.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and get_column_order_from_library(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access").
Example
Bindings:
- name: "$library_variables"
expression: 'get_column_order_from_library()'
Check:
expression: 'upper(varname()) not in $library_variables'
The example above is the complete call.
When there is nothing to answer — ⚠ the rule is SKIPPED for that dataset, an exception to the totality rule above: an absent or empty column order is library not available ("Rule skipped — library returned no data for get_column_order_from_library"). To keep a rule answering when the IG has no list for the dataset, bind get_dataset_filtered_variables() instead — the same IG-resolved list intersected with the dataset's columns, which answers the empty set.
get_dataset_filtered_variables¶
get_dataset_filtered_variables(key_name=, key_value=) → value (a list)
Library variables of the current dataset filtered by metadata, intersected with the columns present — the IG-resolved list for the dataset's domain, keeping the variables whose attribute key_name= has the value key_value=; without a filter, the whole intersected list.
| parameter | type | required | description |
|---|---|---|---|
key_name |
string | no | The metadata attribute to filter on — a static string literal naming an attribute the Library publishes for a variable (role, core, label, simpleDatatype, …); any other name fails to load, naming the attributes that exist |
key_value |
string | no | The value that attribute must have — a static string literal, compared exactly |
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and get_dataset_filtered_variables(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access"). Both parameters are read once per call, which is why they must be literals (a column bound there would be read at row 0 and silently stand for every row). A key_name the dataset's own Library rows do not carry (core on a model-only walk, role on an ADaM dataset) is legal and logs a WARNING, because servability is a per-dataset fact.
Example
Bindings:
- name: "$TIMING_VARIABLES"
expression: 'get_dataset_filtered_variables(key_name="role", key_value="Timing")'
Check:
expression: '$record_count_per_subject_test_timing > 1 and (empty(--REPNUM) or not is_unique_set([--REPNUM, USUBJID, --TESTCD, $TIMING_VARIABLES], regex="^\\d{4}-\\d{2}-\\d{2}"))'
Minimal — required parameters only
Bindings:
- name: "$expected_variables"
expression: 'get_dataset_filtered_variables(key_name="core", key_value="Exp")'
Check:
expression: 'varname() in $expected_variables and var_is_null(varname())'
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. Under the Define-XML fallback for an unreachable Library, an empty answer means the define could not answer and the rule is SKIPPED instead.
get_model_column_order¶
get_model_column_order() → value (a list)
The column order of the standard's model for the dataset's observation class, as a list.
It is the pure SDTM model walk for the dataset's observation class: the IG's own dataset variables are never merged in. Where an IG runs ahead of the model version it links to, a variable the IG defines for the dataset is therefore absent from this list (60 of them at SENDIG 3.0, 5 at SDTMIG 3.3, none at SDTMIG 3.4). FDA-SD0058 binds it next to the IG list from get_dataset_filtered_variables() and reports such a variable at WARNING, a variable in neither list at ERROR.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and get_model_column_order(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access").
Example
Bindings:
- name: "$model_order"
expression: 'get_model_column_order()'
Check:
expression: 'varname() not in $model_order and varname() not in $library_order and varname() not in $events_vars and varname() not in $interventions_vars and varname() not in $findings_vars and varname() not in $findings_about_vars'
The example above is the complete call.
When there is nothing to answer — ⚠ the rule is SKIPPED for that dataset, an exception to the totality rule above: an absent or empty model list is library not available ("Rule skipped — library returned no data for get_model_column_order"), so varname() not in $s never fans out over every column.
A domain the run's IG does not define — a sponsor-defined domain, or a standard one the IG leaves out (at SENDIG-AR 1.0 every SEND domain but DM/CM/FA/MH) — is walked under exactly the observation class the scope matcher gives the dataset (the study's declared class, the product, the curated domain map — these three keyed by the DOMAIN value, or by the dataset name when there is no DOMAIN column — then the topic-variable sniff of the dataset's own columns, which needs a DOMAIN column; and for an AP-- dataset, finally its parent domain's class), so the class a rule is scoped by and the class its model list comes from are one class. Only a dataset no class tier places — a code the curated map does not know whose columns show no topic variable the sniff recognises (e.g. SDTMIG-MD's DI and DR), or an AP-- dataset whose parent domain is not in the study, which the scope matcher places nowhere either — or one whose class the linked model has no variables for, resolves an empty list — and then the rule is skipped. get_model_filtered_variables() and get_parent_model_column_order() read this same walk. get_dataset_filtered_variables() and natural_key_variables() read the IG-merged walk, which for such a domain is this one when its class is a general-observation class (Events, Interventions, Findings, Findings About) — and the empty set when its class is special-purpose, trial-design or relationship (e.g. CO, TS or RELREC in a SENDIG-AR 1.0 run; an AP-- dataset keeps only its associated-persons identifiers): the IG-merged walk has no model dataset to fall back to. Where this lookup skips, the filtered lookups answer the empty set. get_column_order_from_library() stays keyed by the domain name: the IG has no column order for such a domain, so it skips.
get_model_filtered_variables¶
get_model_filtered_variables(key_name=, key_value=, model_class=) → value (a list)
Model variables filtered by metadata, not intersected with the dataset's columns — the model-level set itself. model_class= walks the named general-observation class's model table instead of the dataset's own class.
| parameter | type | required | description |
|---|---|---|---|
key_name |
string | no | The metadata attribute to filter on — a static string literal naming an attribute the Library publishes for a variable (role, core, label, simpleDatatype, …); any other name fails to load, naming the attributes that exist |
key_value |
string | no | The value that attribute must have — a static string literal, compared exactly |
model_class |
string | no | The general-observation class whose model table to walk — a static string literal; Events, Interventions, Findings, Findings About in any letter case and spacing ("EVENTS", " Findings About "), any other spelling fails to load |
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and get_model_filtered_variables(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access"). The three parameters are read once per call and must be literals. A key_name the walked rows do not carry (core on a model walk of a standard SDTM domain) is legal and logs a WARNING — SUPP--/SQ-- datasets and every ADaM dataset publish core on this walk.
Example
Bindings:
- name: "$timing_variables"
expression: 'get_model_filtered_variables(key_name="role", key_value="Timing")'
Check:
expression: 'not shares_elements_with($dataset_variables, $timing_variables)'
Minimal — required parameters only
Bindings:
- name: "$events_vars"
expression: 'get_model_filtered_variables(model_class="EVENTS")'
Check:
expression: 'varname() not in $model_order and varname() not in $library_order and (varname() in $events_vars or varname() in $interventions_vars or varname() in $findings_vars or varname() in $findings_about_vars)'
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. Under the Define-XML fallback for an unreachable Library, an empty answer means the define could not answer and the rule is SKIPPED instead. ⚠ With model_class=, a class the linked model has no variables for is library not available and the rule is SKIPPED ("Rule skipped — library returned no data for get_model_filtered_variables") — the dataset's own-class walk answers the empty set, the named-class walk does not.
get_parent_model_column_order¶
get_parent_model_column_order(name) → value (a list, per row)
The model column order of the parent domain named in a column value, per row — for a SUPP-- dataset, the SDTM model variables of the domain each row's RDOMAIN names, so QNAM in $model_variables asks whether the qualifier duplicates a parent variable.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The column holding the parent domain code (RDOMAIN) — a column reference; a quoted name fails to load |
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions); the retired operation took no argument and always read RDOMAIN, so get_parent_model_column_order() fails to load — name the column. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access"). Unlike the other list functions it answers per row: each row reads the list of the parent its own cell names (the lists are computed once per distinct parent). ⭐ A split parent resolves (fixed in wave 4, defect D2): when the parent domain is submitted as split members (LBCH + LBHE for RDOMAIN = LB), the list is the union of the members' model column orders, in member-name order (members sorted by dataset name, LBCH before LBHE), so the list is the same on every run; a dataset named exactly like the parent is used alone when it exists, and a study dataset that cannot be opened is never a member and does not stop the parent resolving — the retired operation looked for a dataset literally named LB, found none, and answered nothing for every such row.
Example
Bindings:
- name: "$model_variables"
expression: 'get_parent_model_column_order(RDOMAIN)'
Check:
expression: 'QNAM in $model_variables'
The example above is the complete call.
When there is nothing to answer — a row whose cell is blank, or names a parent no dataset of the study carries, reads the empty set (QNAM in $s is false; not in fires). ⚠ The rule is SKIPPED, an exception to the totality rule above, when no row's parent resolves a model list ("Rule skipped — library returned no data for get_parent_model_column_order"), and when a resolved parent's model list is library not available (no product declared, or the Library unreachable) — as get_model_column_order() skips for its own dataset.
natural_key_variables¶
natural_key_variables() → value (a list)
The natural-key-forming role variables present in the dataset — the Library variables of the dataset's domain whose role is Timing, Record Qualifier, Variable Qualifier, Result Qualifier, Synonym Qualifier or Grouping Qualifier, intersected with the columns present.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and natural_key_variables(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access").
Example
Bindings:
- name: "$natural_key"
expression: 'natural_key_variables()'
Check:
expression: 'not is_unique_set([USUBJID, --TESTCD, $natural_key])'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. Under the Define-XML fallback for an unreachable Library, an empty answer means the define could not answer and the rule is SKIPPED instead.
required_variables¶
required_variables() → value (a list)
The variables the CDISC Library marks Required (Req) for this dataset, as a list — for an ADaM dataset, the required variables of its detected data structure(s), naming templates substituted against the dataset's own columns.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and required_variables(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access").
Example
Bindings:
- name: "$required_variables"
expression: 'required_variables()'
Check:
expression: 'varname() in $required_variables and empty(value())'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. ⚠ Two exceptions SKIP the rule instead: an ADaM dataset for which the declared product publishes no data structure ("Rule skipped — library returned no data for required_variables"), and the Define-XML fallback for an unreachable Library answering nothing.
var_ccode¶
var_ccode(x, "DEFINE") → value
The NCI C-code of the bound codelist; DEFINE and LIBRARY only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE/LIBRARY |
Example
expression: 'empty(var_ccode("DEFINE"))'
var_codelist¶
var_codelist([x,] level) → value
The name of the codelist bound to the variable; DEFINE and LIBRARY only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE/LIBRARY |
Example
expression: 'not empty(var_codelist("LIBRARY"))'
var_codelist_coded_codes¶
var_codelist_coded_codes(x, level) → value
The codes of the bound codelist's terms, as a list; DEFINE and LIBRARY only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE/LIBRARY |
Example
expression: 'not empty(var_codelist_coded_codes("LIBRARY"))'
var_codelist_coded_values¶
var_codelist_coded_values(x, level) → value
The submission values of the bound codelist's terms, as a list; DEFINE and LIBRARY only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE/LIBRARY |
Example
expression: 'not empty(var_codelist_coded_values("LIBRARY"))'
var_codelist_extended_values¶
var_codelist_extended_values(x, "DEFINE") → value
The sponsor-added values of an extended codelist, as a list; DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE |
Example
expression: 'not empty(var_codelist_extended_values("DEFINE"))'
var_codelist_extensible¶
var_codelist_extensible(x, "LIBRARY") → value
Whether the bound codelist is extensible; LIBRARY only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: LIBRARY |
Example
expression: 'var_codelist_extensible("LIBRARY") == true'
var_core¶
var_core([x,] level) → value
The variable's core designation — Required, Expected or Permissible; DEFINE and LIBRARY only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE/LIBRARY |
Example
expression: 'var_core("LIBRARY") == "Perm"'
var_external_dictionary¶
var_external_dictionary(x, "DEFINE") → value
The external dictionary the variable is coded against; DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE |
Example
expression: 'var_name("DEFINE") in ["LBTOX", "LBTOXGR"] and empty(var_external_dictionary("DEFINE"))'
var_external_dictionary_version¶
var_external_dictionary_version(x, "DEFINE") → value
The version of that external dictionary; DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE |
Example
expression: 'var_external_dictionary_version(varname(), "DEFINE")'
var_format¶
var_format([x,] level) → value
The variable's display format; DATA and DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE |
Example
expression: 'empty(var_format("DATA"))'
var_has_codelist¶
var_has_codelist(x, "DEFINE") → value
Whether the variable binds a codelist at all; DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE |
Example
expression: 'var_has_codelist("DEFINE") == true'
var_has_comment¶
var_has_comment(x, "DEFINE") → value
Whether Define-XML attaches a comment to the variable; DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE |
Example
expression: 'not empty(var_name("DEFINE")) and var_has_comment("DEFINE") == false'
var_has_method¶
var_has_method(x, "DEFINE") → value
Whether Define-XML attaches a derivation method to the variable; DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE |
Example
expression: 'var_has_method("DEFINE") == false'
var_label¶
var_label([x,] level) → value
The variable's label; available at every level
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE/LIBRARY |
Example
expression: 'var_label("DATA") =~ /^[a-z]/'
At LIBRARY, a dataset whose domain the run's IG does not define has no label — nor a codelist, core designation or ordinal: the SDTM model's labels are class-level ones, not the label a standard gives the domain, and a sponsor may adjust the labels of a domain it defines. A rule guarded by not empty(var_label("LIBRARY")) therefore does not judge such a dataset. Its name, data type and role do come from the model (see var_type).
var_length¶
var_length([x,] level) → value
The variable's declared length; available at every level
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE/LIBRARY |
Example
expression: 'var_length("DATA") > 200'
var_mandatory¶
var_mandatory(x, "DEFINE") → value
Whether Define-XML marks the variable mandatory; DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE |
Example
expression: 'var_mandatory(varname(), "DEFINE") == "Yes"'
var_name¶
var_name([x,] level) → value
The variable's name; available at every level
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE/LIBRARY |
Example
expression: 'not empty(var_name("DEFINE"))'
At LIBRARY, a dataset whose domain the run's IG does not define — a sponsor-defined domain, or a standard one the IG leaves out (at SENDIG-AR 1.0 every SEND domain but DM, CM, FA and MH; at SENDIG-DART 1.1 EG, PM, TF, VS, CV and RE) — takes its name from the SDTM model's variable of the observation class the scope matcher gives the dataset. If no class places the dataset, if the class is a special-purpose, trial-design or relationship one, or if the model has no such variable (a sponsor's own variable), there is no value, as for any variable the Library does not know.
var_ordinal¶
var_ordinal([x,] level) → value
The variable's position in the declared column order; available at every level
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE/LIBRARY |
Example
expression: 'var_ordinal("DEFINE")'
var_origin_type¶
var_origin_type(x, "DEFINE") → value
The variable's Define-XML origin type — Collected, Derived and so on; DEFINE only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE |
Example
expression: 'not empty(var_name("DEFINE")) and empty(var_origin_type("DEFINE"))'
var_role¶
var_role([x,] level) → value
The variable's role — identifier, topic, qualifier and so on; DEFINE and LIBRARY only
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DEFINE/LIBRARY |
Example
expression: 'not empty(var_role("DEFINE"))'
At LIBRARY, a dataset whose domain the run's IG does not define — a sponsor-defined domain, or a standard one the IG leaves out (at SENDIG-AR 1.0 every SEND domain but DM, CM, FA and MH; at SENDIG-DART 1.1 EG, PM, TF, VS, CV and RE) — takes its role from the SDTM model's variable of the observation class the scope matcher gives the dataset. If no class places the dataset, if the class is a special-purpose, trial-design or relationship one, or if the model has no such variable (a sponsor's own variable), there is no value, as for any variable the Library does not know.
var_type¶
var_type([x,] level) → value
The variable's data type; available at every level
| parameter | type | required | description |
|---|---|---|---|
x |
column | no | The column to read; defaults to the variable being iterated |
level |
level | yes | Which metadata to read — supported here: DATA/DEFINE/LIBRARY |
Example
expression: 'var_type("DATA") != "Num"'
At LIBRARY, a dataset whose domain the run's IG does not define — a sponsor-defined domain, or a standard one the IG leaves out (at SENDIG-AR 1.0 every SEND domain but DM, CM, FA and MH; at SENDIG-DART 1.1 EG, PM, TF, VS, CV and RE) — takes its data type from the SDTM model's variable of the observation class the scope matcher gives the dataset. If no class places the dataset, if the class is a special-purpose, trial-design or relationship one, or if the model has no such variable (a sponsor's own variable), there is no value, as for any variable the Library does not know.
variable_names¶
variable_names() → value (a list)
Every variable name the standard publishes, across all of its datasets, as a list — the standard's whole variable vocabulary, not the current dataset's.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and variable_names(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access").
Example
Bindings:
- name: "$variable_names"
expression: 'variable_names()'
Check:
expression: 'QNAM in $variable_names'
The example above is the complete call.
When there is nothing to answer — ⚠ the rule is SKIPPED, an exception to the totality rule above: a Library that publishes no variable names for the standard is library not available ("Rule skipped — library returned no data for variable_names").
Define-XML and value-level metadata¶
The vlm_* accessors read the value-level metadata of a column of the dataset under
evaluation, its WhereClause judged on the evaluated row. A qualified name (vlm_length(DM.AGE),
or the string form) fails to load, naming the bare spelling: a joined dataset's value-level
metadata is not served. (Until 2026-10-01 it never matched a value-level definition, silently.)
define_dataset_names¶
define_dataset_names() → value (a list)
The dataset names the Define-XML declares, upper-cased, as a list.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and define_dataset_names(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the sponsor Define-XML: without one the rule is SKIPPED before any row is read.
Example
Bindings:
- name: "$define_datasets"
expression: 'define_dataset_names()'
Check:
expression: 'not contains_all($study_datasets, $define_datasets)'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires.
define_key_variables¶
define_key_variables() → value (a list)
The key variables the Define-XML declares for the current dataset's domain, in key order, as a list.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and define_key_variables(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the sponsor Define-XML: without one the rule is SKIPPED before any row is read.
Example
Bindings:
- name: "$define_key_variables"
expression: 'define_key_variables()'
Check:
expression: 'not is_unique_set([STUDYID, $define_key_variables])'
The example above is the complete call.
When there is nothing to answer — ⚠ the rule is SKIPPED, an exception to the totality rule above: a Define-XML that declares no key variables for the domain leaves a uniqueness check with no key to test, so the answer is Define-XML not available ("Rule skipped — Define-XML returned no data for define_key_variables") rather than an empty key set that would make is_unique_set vacuous.
define_variable_decode_matches¶
define_variable_decode_matches([x]) → value
Whether the record's code and decode agree at variable level, per the Define-XML: the current
variable is the code variable, its ItemDef codelist supplies the coded-value → decode map, and
the record's decode partner (the code name without its trailing N, NUM or CD — AVISITN →
AVISIT, VISITNUM → VISIT, PARAMCD → PARAM) must hold the decode of the record's coded
value. The variable-level twin of vlm_decode_matches. Written as the
operand define_variable_decode_matches in a Value Check against Define XML Variable rule.
| parameter | type | required | description |
|---|---|---|---|
x |
any | no | variable_name / varname(), or nothing — the variable currently being iterated |
Example
expression: 'not empty(value()) and define_variable_decode_matches(variable_name) == false'
When there is nothing to answer — No decision, so the row does not fire: an empty code value, a variable whose codelist carries no decodes, a decode partner that cannot be resolved, or a code value that is not a term of the codelist (an out-of-codelist value is another rule's concern). Without a Define-XML the rule is SKIPPED.
define_variable_names¶
define_variable_names() → value (a list)
The Define-XML ItemDef names for the current dataset's domain, in Define order, as a list.
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and define_variable_names(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the sponsor Define-XML: without one the rule is SKIPPED before any row is read.
Example
Bindings:
- name: "$define_variables"
expression: 'define_variable_names()'
Check:
expression: 'not contains_all($dataset_variables, $define_variables)'
The example above is the complete call.
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires.
vlm_codelist_coded_codes¶
vlm_codelist_coded_codes(X) → value
The codes of the codelist bound by the value-level match, as a list
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'variable_value not in vlm_codelist_coded_codes(varname())'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_codelist_coded_codes())'
vlm_codelist_coded_values¶
vlm_codelist_coded_values(X) → value
The submission values of the codelist bound by the value-level match, as a list
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'value() not in vlm_codelist_coded_values(variable_name)'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_codelist_coded_values())'
vlm_codelist_extensible¶
vlm_codelist_extensible(X) → value
Whether the codelist bound by the value-level match is extensible
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'vlm_codelist_extensible(variable_name) == true'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_codelist_extensible())'
vlm_data_type¶
vlm_data_type(X) → value
The @DataType of the Define-XML item matched at value level
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'vlm_data_type(varname()) == "text"'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_data_type())'
vlm_decode_matches¶
vlm_decode_matches(X) → value
Whether the record's code and decode agree at value level
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'not empty(value()) and vlm_decode_matches(variable_name) == false'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_decode_matches())'
vlm_has_codelist¶
vlm_has_codelist(X) → value
Whether the value-level match binds a codelist
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'vlm_has_codelist(variable_name) == true'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_has_codelist())'
vlm_length¶
vlm_length(X) → value
The @Length of the Define-XML item matched at value level
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'not empty(value()) and vlm_value_length(variable_name) > vlm_length(variable_name)'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_length())'
vlm_mandatory¶
vlm_mandatory(X) → value
Whether the Define-XML item matched at value level is mandatory
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'vlm_mandatory(variable_name) == "Yes" and empty(value())'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_mandatory())'
vlm_type_conforms¶
vlm_type_conforms(X) → value
Whether the record's value conforms to the matched @DataType
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'not empty(value()) and vlm_type_conforms(variable_name) == false'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_type_conforms())'
vlm_value_length¶
vlm_value_length(X) → value
The stored length of the record's value under the matched type
| parameter | type | required | description |
|---|---|---|---|
name |
any | no | The column to read |
Example
expression: 'not empty(value()) and vlm_value_length(variable_name) > vlm_length(variable_name)'
Minimal — required parameters only
Check:
expression: 'not empty(vlm_value_length())'
Controlled terminology and dictionaries¶
codelist_terms¶
codelist_terms(codelists=, level=, returntype=) → value (a list)
The terms of the named CT codelists, in the representation level= / returntype= select, as one de-duplicated list in Library order.
| parameter | type | required | description |
|---|---|---|---|
codelists |
list of strings | yes | Which codelists to read, by codelist short name, as a list of string literals — ["DOMAIN"], ["ND"]; several are unioned in order |
level |
string | yes | "term" reads the terms of each codelist; "codelist" reads the codelist's own entry. Any other value fails to load |
returntype |
string | no | Which attribute to return: "value" (submission value), "code" (NCI concept id, the C-code) or "pref_term" (NCI preferred term). Any other value fails to load. Absent: code at level="term", value at level="codelist" |
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and codelist_terms(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access"). The three parameters are read once per call and must be literals — a bare codelists=[DOMAIN] names the DOMAIN column and fails to load, naming the quoted spelling. The six level × returntype shapes: term/value the terms' submission values · term/code their C-codes · term/pref_term their preferred terms · codelist/value the codelist's own submission value · codelist/code its C-code · codelist/pref_term its preferred term. ⚠ Compare the representation the other operand really carries: a codelist compared against 2-character submission values wants "value", one compared against C… codes wants "code".
Example
Bindings:
- name: "$sndigver_terms"
expression: 'codelist_terms(codelists=["SNDIGVER"], level="term", returntype="value")'
Check:
expression: 'TSPARMCD == "SNDIGVER" and not empty(TSVAL) and TSVAL not in $sndigver_terms'
Minimal — required parameters only
Bindings:
- name: "$domain_codes"
expression: 'codelist_terms(codelists=["DOMAIN"], level="term")'
Check:
expression: 'not empty(DOMAIN) and DOMAIN not in $domain_codes'
When there is nothing to answer — ⚠ the rule is SKIPPED, an exception to the totality rule above: when the named codelists resolve no term in the selected representation — a codelist the Library does not hold, or a shape the metadata store cannot serve — the answer is library not available ("Rule skipped — library returned no data for codelist_terms"), never an empty list a not in would fire over.
dictionary_available¶
dictionary_available(type) → boolean
The external-dictionary availability gate: true on every row when a dictionary of the named type is loaded for the run, else false. The loader injects it as a Precondition for every inline valid_external_dictionary_* call, so a rule whose dictionary is not supplied SKIPs instead of passing; a declared ($-bound) dictionary function needs no gate, because the runner skips the rule from the function's own dictionary need. (The dictionary_available(external_dictionary_type=…) operation form was deleted by wave 1 of the operation→function programme; only this builtin remains.)
| parameter | type | required | description |
|---|---|---|---|
type |
string | yes | Which external dictionary to test for, e.g. "meddra" |
Example
Precondition:
expression: 'dictionary_available("meddra")'
When there is nothing to answer — false — the predicate was evaluated and did not hold. It is not unknown.
dictionary_has_decode¶
dictionary_has_decode(name, external_dictionary_type=, case_sensitive=) → boolean
Decode presence against an external dictionary: true on a row whose code has any decode in the named dictionary (its code↔decode pairs or attribute tables). A blank or missing code has none (false). The code lookup is case-sensitive by default; case_sensitive=false folds it.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The code column (CMTRT) |
external_dictionary_type |
string | yes | Which external dictionary to check against — a string literal ("whodrug") |
case_sensitive |
boolean | no | Default true; only case_sensitive=false folds case. Must be a boolean literal — anything else fails to load |
name is a column reference; a quoted name fails to load, and an absent column answers false on every row. The dictionary type must be a static string literal: the function declares the dictionary it needs from it, so a rule whose dictionary is not loaded reports SKIPPED — never a finding, never a silent pass — before any row is read, and a run's provider forecast lists the type. Reached without its dictionary the function reports a rule ERROR, never false. (Until wave 3 of the operation→function programme this was an operation.)
Example
Bindings:
- name: "$cmtrt_has_decode"
expression: 'dictionary_has_decode(CMTRT, external_dictionary_type="whodrug")'
Check:
expression: '$cmtrt_has_decode == true and empty(CMDECOD)'
The example above is the complete call.
get_codelist_attributes¶
get_codelist_attributes(name, version, ct_attribute=) → value (a list)
The values of one CT-package attribute (e.g. "Term CCODE") for every CT package the rows name. Per
row, the package is derived from the target and the version: name = "CDISC" or "CDISC CT" with
version = 2024-09-27 names sdtmct-2024-09-27 under an SDTM standard (adamct-… / sendct-…
under ADaM / SEND); any other target names <target>-<version>; a blank version names none. The
answer is the order-preserving union over all rows — one list for the dataset.
| parameter | type | required | description |
|---|---|---|---|
name |
any | yes | The target: the column naming the CT dictionary (TSVCDREF) |
version |
any | yes | The column holding the per-row CT version (TSVCDVER) |
ct_attribute |
string | yes | Which CT-package attribute to extract, e.g. "Term CCODE" |
A registry function since PLAN-binding-expressions (wave 0 of the operations→functions
programme): the version column is the second positional argument — a column reference, not the
quoted version="TSVCDVER" of the retired operation, which would now be the string literal
"TSVCDVER". It is an aggregate: it folds every row of the dataset whichever row reads it, and
it is computed once per rule and dataset. It needs the CDISC Library.
Example
Bindings:
- name: "$VALID_TERM_CODES"
expression: 'get_codelist_attributes(TSVCDREF, TSVCDVER, ct_attribute="Term CCODE")'
Check:
expression: 'prefix(TSVCDREF, 5) == "CDISC" and not empty($VALID_TERM_CODES) and TSVALCD not in $VALID_TERM_CODES'
(CDISC-CG0288.) The call may also be written directly as the right-hand side of in / not in
— the verdict is the binding's.
When there is nothing to answer — the rule is SKIPPED, never passed: with no CDISC Library
("Rule skipped — no Library access"), and when the Library knows none of the packages the rows
name, or the dataset has no rows ("Rule skipped — library returned no data for
get_codelist_attributes"). It never answers an empty list, so not empty(...) cannot quietly read
false.
library_available¶
library_available() → boolean
RulePackageLoader injects this gate at load for a call that needs the CDISC Library; a not-met Precondition ⇒ SKIPPED
Takes no arguments.
library_variable_code_pair_matches¶
library_variable_code_pair_matches([x]) → value
Whether the record's code and its paired decode map to the same CDISC CT term: the current
variable is the code variable (e.g. --TESTCD), its decode partner follows the CDISC convention
(drop the trailing CD — --TEST), and each value is mapped to its term's concept id (C-code)
through its own variable's bound codelist; true when the two concept ids are equal. Written as the
operand library_variable_code_pair_matches in a Value Check against Library Metadata rule.
| parameter | type | required | description |
|---|---|---|---|
x |
any | no | variable_name / varname(), or nothing — the variable currently being iterated |
Example
expression: 'not empty(value()) and library_variable_code_pair_matches(variable_name) == false'
When there is nothing to answer — No decision, so the row does not fire: an empty code value, a decode variable that cannot be derived or is absent, or either value not a term of its codelist. Without the CDISC Library the rule is SKIPPED.
valid_codelist_dates¶
valid_codelist_dates(ct_package_types=) → value (a list)
The publication dates of the CT packages the Library publishes for the applicable package types (sdtmct-2023-10-26 → 2023-10-26), sorted, as a list.
| parameter | type | required | description |
|---|---|---|---|
ct_package_types |
list of strings | no | The CT package families to consider, as a list of string literals — ["SDTM"], ["SDTM", "ADAM"] (a family maps to its package type by lower-casing and appending ct). Omitted: the families of the rule's standard — sdtmig ⇒ SDTM CT, sendig ⇒ SEND CT, cdashig ⇒ CDASH CT, adamig ⇒ SDTM + ADaM CT, usdm ⇒ DDF + SDTM CT |
A registry function since wave 4 of the operations→functions programme (PLAN-list-functions). It takes no column target — the name / names rows of the retired operation are gone, and valid_codelist_dates(X) fails to load. It is an aggregate: one list for the dataset, computed once per rule and dataset and read by every row. It needs the CDISC Library: without one the rule is SKIPPED ("Rule skipped — no Library access"). The list is read once per call and must be a list literal of string literals — a bare [SDTM] names a column and fails to load, naming the quoted spelling.
Example
Bindings:
- name: "$valid_dates"
expression: 'valid_codelist_dates(ct_package_types=["SDTM"])'
Check:
expression: 'TSVCDREF == "CDISC" and TSVCDVER not in $valid_dates'
Minimal — required parameters only
Bindings:
- name: "$valid_dates"
expression: 'valid_codelist_dates()'
Check:
expression: 'TSVCDVER not in $valid_dates'
When there is nothing to answer — the empty set. X in $s is then vacuously false; X not in $s is vacuously true and fires. A Library that publishes no CT package, or none of the applicable families, answers the empty set — so TSVCDVER not in $valid_dates fires on every populated version. Under the Define-XML fallback for an unreachable Library, an empty answer means the define could not answer and the rule is SKIPPED instead.
valid_external_dictionary_code¶
valid_external_dictionary_code(name, external_dictionary_type=, dictionary_term_type=, case_sensitive=) → boolean
Code validity against an external dictionary: true on a row whose value is a member of the named dictionary at the level dictionary_term_type names (e.g. "PTCD", "LLTCD", "UNII", "SNOMEDCD", "MEDRTCD", "LOINC"). A blank or missing value is true — completeness is another rule's concern. By default the value must match the dictionary's preferred case; case_sensitive=false accepts any case. valid_external_dictionary_code and valid_external_dictionary_value are one function under two names: the level alone decides whether terms or codes are checked.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The column holding the value to check |
external_dictionary_type |
string | yes | Which external dictionary to check against — a string literal ("meddra", "whodrug", "unii", "snomed", "medrt", "loinc") |
dictionary_term_type |
string | yes | Which level of the dictionary to check. A static string literal — anything else fails to load |
case_sensitive |
boolean | no | Default true (the preferred case); case_sensitive=false accepts any case. Must be a boolean literal — anything else fails to load |
name is a column reference; a quoted name fails to load, and an absent column is a column of blanks (valid on every row). The dictionary type must be a static string literal: the function declares the dictionary it needs from it, so a rule whose dictionary is not loaded reports SKIPPED — never a finding, never a silent pass — before any row is read, and a run's provider forecast lists the type. Reached without its dictionary the function reports a rule ERROR, never false. (Until wave 3 of the operation→function programme this was an operation.)
Example
Bindings:
- name: "$tdigrp_code_valid"
expression: 'valid_external_dictionary_code(TSVALCD, external_dictionary_type="snomed", dictionary_term_type="SNOMEDCD")'
Check:
expression: 'TSPARMCD == "TDIGRP" and $tdigrp_code_valid == false'
Minimal — required parameters only
Bindings:
- name: "$comptrt_srs_code"
expression: 'valid_external_dictionary_code(TSVALCD, external_dictionary_type="unii", dictionary_term_type="UNII")'
Check:
expression: 'TSPARMCD == "COMPTRT" and $comptrt_srs_code == false'
valid_external_dictionary_code_term_pair¶
valid_external_dictionary_code_term_pair(name, external_dictionary_term_variable, external_dictionary_type=, case_sensitive=) → boolean
Code↔decode pairing against an external dictionary: true on a row whose code (the first column) decodes to the term (the second column) in the named dictionary; a blank code or a blank term is true (completeness is another rule's concern). Code and decode compare case-sensitively by default; case_sensitive=false folds both.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The code column (TSVALCD, --STRESC) |
external_dictionary_term_variable |
column | yes | The decode / term column to pair with the code (TSVAL, --RESCAT) |
external_dictionary_type |
string | yes | Which external dictionary to check against — a string literal ("unii", "snomed", "medrt", "neoplasm") |
case_sensitive |
boolean | no | Whether the comparison is case-sensitive; default true (compares verbatim). Only case_sensitive=false folds case. Must be a boolean literal — anything else fails to load |
Both column parameters are column references; a quoted name (external_dictionary_term_variable="TSVAL") is a string literal and fails to load, and a call without the term column fails to load. The dictionary type must be a string literal: the function declares the dictionary it needs from it, so a rule whose dictionary is not loaded reports SKIPPED — never a finding, never a silent pass — before any row is read, and a run's provider forecast lists the type. (Until wave 1 of the operation→function programme this was an operation taking external_dictionary_term_variable="TSVAL" as a quoted string.)
Example
Bindings:
- name: "$neoplasm_aligned"
expression: 'valid_external_dictionary_code_term_pair(--STRESC, --RESCAT, external_dictionary_type="neoplasm")'
Check:
expression: '--RESCAT in ["BENIGN", "MALIGNANT"] and $neoplasm_aligned == false'
Minimal — required parameters only
Bindings:
- name: "$comptrt_pair_valid"
expression: 'valid_external_dictionary_code_term_pair(TSVALCD, TSVAL, external_dictionary_type="unii")'
Check:
expression: 'TSPARMCD == "COMPTRT" and $comptrt_pair_valid == false'
When the dictionary is not loaded — the rule SKIPs (the reason names the type and its state). The function has no silent default: reached without its dictionary it reports a rule ERROR, never false.
valid_external_dictionary_hierarchy¶
valid_external_dictionary_hierarchy(name, dictionary_parent, external_dictionary_type=, case_sensitive=) → boolean
Hierarchy ancestor test against an external dictionary: true on a row whose child term (the first column) lies on the hierarchy path of the parent term (the second column); a blank child or a blank parent is true. Operands compare case-sensitively by default; case_sensitive=false folds both.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The child term column (--HLT, --HLGT) |
dictionary_parent |
column | yes | The candidate ancestor column (--SOC) |
external_dictionary_type |
string | yes | Which external dictionary to check against — a string literal ("meddra") |
case_sensitive |
boolean | no | Whether the comparison is case-sensitive; default true (compares verbatim). Only case_sensitive=false folds case. Must be a boolean literal — anything else fails to load |
Both column parameters are column references: the -- in --HLT / --SOC is resolved like any other variable name, and a quoted name (dictionary_parent="--SOC") is a string literal and fails to load. The dictionary type must be a string literal; a rule whose dictionary is not loaded reports SKIPPED before any row is read.
Example
Bindings:
- name: "$hlgt_on_path"
expression: 'valid_external_dictionary_hierarchy(--HLGT, --SOC, external_dictionary_type="meddra")'
Check:
expression: '$hlgt_on_path == false'
Minimal — required parameters only
Bindings:
- name: "$hlt_on_path"
expression: 'valid_external_dictionary_hierarchy(--HLT, --SOC, external_dictionary_type="meddra")'
Check:
expression: '$hlt_on_path == false'
When the dictionary is not loaded — the rule SKIPs. Reached without its dictionary the function reports a rule ERROR, never false.
valid_external_dictionary_value¶
valid_external_dictionary_value(name, external_dictionary_type=, dictionary_term_type=, case_sensitive=) → boolean
Term validity against an external dictionary: true on a row whose value is a member of the named dictionary at the level dictionary_term_type names (e.g. "PT", "LLT", "SOC", "SRS", "SNOMED", "MEDRT"). A blank or missing value is true — completeness is another rule's concern. By default the value must match the dictionary's preferred case; case_sensitive=false accepts any case. valid_external_dictionary_value and valid_external_dictionary_code are one function under two names: the level alone decides whether terms or codes are checked.
| parameter | type | required | description |
|---|---|---|---|
name |
column | yes | The column holding the value to check |
external_dictionary_type |
string | yes | Which external dictionary to check against — a string literal ("meddra", "whodrug", "unii", "snomed", "medrt", "loinc") |
dictionary_term_type |
string | yes | Which level of the dictionary to check. A static string literal — anything else fails to load |
case_sensitive |
boolean | no | Default true (the preferred case); case_sensitive=false accepts any case. Must be a boolean literal — anything else fails to load |
name is a column reference; a quoted name fails to load, and an absent column is a column of blanks (valid on every row). The dictionary type must be a static string literal: the function declares the dictionary it needs from it, so a rule whose dictionary is not loaded reports SKIPPED — never a finding, never a silent pass — before any row is read, and a run's provider forecast lists the type. Reached without its dictionary the function reports a rule ERROR, never false. (Until wave 3 of the operation→function programme this was an operation.)
Example
Bindings:
- name: "$bodsys_valid"
expression: 'valid_external_dictionary_value(--BODSYS, external_dictionary_type="meddra", dictionary_term_type="SOC", case_sensitive=false)'
Check:
expression: '$bodsys_valid == false'
Minimal — required parameters only
Bindings:
- name: "$comptrt_srs_term"
expression: 'valid_external_dictionary_value(TSVAL, external_dictionary_type="unii", dictionary_term_type="SRS")'
Check:
expression: 'TSPARMCD == "COMPTRT" and $comptrt_srs_term == false'
Supplemental qualifiers and trial summary¶
read_value¶
read_value(name, domain=, filter=, mode=, group=, keep_missings=) → value
One value of another dataset, read once per rule execution and broadcast to every row: the name
column of domain, taken from the rows a filter over that dataset's own columns selects, by the
mode the author names. Replaced ts_parameter_value (runbook W2a): the TS/TX parameter lookup is
read_value(TSVAL, domain=TS, filter=(TSPARMCD == "SPECIES"), mode="FIRST").
| parameter | type | required | description |
|---|---|---|---|
name |
column of domain |
yes | The column to read — bare, never quoted, never dotted, never -- |
domain |
dataset reference | yes | The dataset to read from: TS or "TS" (both spellings name the dataset). A -- in the dataset name resolves against the dataset under evaluation: domain="SUPP--" on AE reads SUPPAE (and on SUPPAE too), as Match_Datasets names do. The dataset is read raw: the declared SUPP merge (Supp_Merge) serves the dataset under evaluation only, so a SUPP-- qualifier is never a column of domain — neither as name nor in filter |
filter |
boolean over domain's columns |
no | Which rows qualify, in parentheses: filter=(TSPARMCD == "SPECIES"). Only columns of domain — a dotted, $ or -- reference is a load error. Absent ⇒ every row |
mode |
"FIRST" · "ONLY" · "MIN" · "MAX" |
yes | Which qualifying row answers: the first in dataset order; exactly one (a second qualifying row is a rule ERROR); the smallest / largest name by the engine's one ordering (a missing below every value, numbers numerically, text as text) |
group |
list of columns of domain |
no | Per-group reading (runbook W5): the mode selects within each group of domain, and every row of the evaluated dataset reads its own group's value by the same columns. ONLY then asserts one qualifying row per group. A row whose key has no group reads the type default. A member may be qualified (DM.RPATHCD): the record reads the group of its bound DM record's value |
keep_missings |
boolean | no | With group: whether a row with a missing group key stays in its group (default true) |
Example
Bindings:
- name: "$exp_start"
expression: 'read_value(TSVAL, domain=TS, filter=(TSPARMCD == "EXPSTDTC"), mode="FIRST")'
Check:
expression: 'not empty(EXSTDTC) and date(EXSTDTC) < date($exp_start)'
Two datasets, one key each
Bindings:
- name: "$ts_species"
expression: 'read_value(TSVAL, domain=TS, filter=(TSPARMCD == "SPECIES"), mode="FIRST")'
- name: "$tx_species"
expression: 'read_value(TXVAL, domain=TX, filter=(TXPARMCD == "SPECIES"), mode="FIRST")'
Check:
expression: 'empty(SPECIES) and empty($ts_species) and empty($tx_species)'
When there is nothing to answer — the column's type default, never an error: "" for a
character column, missing for a numeric one — so empty($x) is true either way. The character
default "" is an ordinary empty text: $x == "" is true, and != against a present literal
($x != "RAT") is true. The numeric default is a missing: != against it fires (rulings register
D34a); == is true only against the same missing; an order comparison treats it as the lowest
value (D34 #5): X > $x and $x < X fire, X < $x does not. That is the answer for a filter no row satisfies, for an absent domain dataset and for a
name the dataset does not carry; the rule executes (it does not skip). A qualifying row whose
name cell is missing hands that missing through. mode="ONLY" is the one loud case: two or more
qualifying rows report the rule as ERROR (… — ONLY asserts exactly one qualifying row), because the
rule asserted a single row and the data says otherwise.
⚠ read_value cannot express presence — a no-match answers the type default (D13), never an
error, whether or not group= is given.
Values and references¶
char¶
char(x) → value
The first character of the value as its numeric code point
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to read |
Example
expression: 'not empty(PARAMCD) and not between(char(PARAMCD), char("A"), char("Z"))'
Missing and empty — A missing input yields that missing value, identity kept (char(.A) is .A, rulings register D85c); "" has no first character to take and yields the plain missing (MIS).
colref¶
colref(x) → value, or a list of values when x is a list of names
The value of the column named by x — a dynamic column read. A bare name reads the dataset under
validation (with the parent columns a Child: true entry merged in); DS.X reads the joined
dataset DS exactly as the written DS.X does. The value keeps its column's type (an ADaM date
stays a number). Over a list of names — colref(find_vars("ADSL.TRTxxA")) — it answers one value
per name, in the list's order: TRTA in colref(find_vars("ADSL.TRTxxA")) is the function spelling
of TRTA in ADSL.TRT${*}A.
| parameter | type | required | description |
|---|---|---|---|
x |
string, or list of strings | yes | The column name(s), per row |
Example
expression: 'not empty(IDVAR) and not empty(IDVARVAL) and str(IDVARVAL) != str(colref(IDVAR))'
Bindings:
- name: "$ap_sdt"
expression: colref(concat("ADSL.AP", printf("%02d", APERIOD), "SDT"))
Check:
expression: not empty(APERSDT) and not empty($ap_sdt) and APERSDT != $ap_sdt
Missing and empty — A named-but-absent column takes the default the written name would
take at the same position: the plain missing where the expression expects a number (colref(…) <
3), "" otherwise (rulings register DCF Q14). A missing x yields that missing value
(D85c); a present x that is not text names no column and yields the plain missing (DCF Q7);
a list keeps a missing member as a member (DCF Q4). ⚠ Through a binding the position is the
binding reference's, which carries no kind — so $x < 3 over $x: colref("X") defaults to "",
exactly as $x: X does.
Names. A name matches its column whatever its case, and so does the absent default:
colref("zz") and colref("ZZ") answer alike. A written -- name (colref("--SEQ")) is
specialised to the domain like any written name; a name computed per row that starts with
-- names no column and takes the absent default. A written colref("DS._matched_") fails
the rule — the join-match flag is a condition, never a value — exactly as DS._matched_ written as
a value does; a name computed per row that spells the flag names no column. A dataset qualifier
matches the rule's Match_Datasets name whatever its case (colref("adsl.TRT01A") reads ADSL).
In a Match_Datasets Filter. A written name — colref("AESEV"), or a list of written
names — is checked like the plain name: a column the filtered dataset does not carry fails the rule
unless the rule declares it in Requirements.Variables (then the rule is skipped), and a written
colref("DM.SEX") is refused like DM.SEX — a filter sees only its own dataset's columns. A name
computed per row cannot be checked before the run.
Real columns only. colref reads the dataset's own columns (with a Child: true parent's
merged in) and the joined datasets' columns — not a SUPP qualifier merged in by the SUPP merge,
which the written bare name does read. Whether it should is an open owner question
(PLAN-dynamic-column-functions F1); today's behaviour is pinned by a test so a change is visible.
In a membership test. On the right of in, a list of names is a per-row set:
TRTA in colref(find_vars("ADSL.TRTxxA")), or through a binding, $vars: find_vars("ADSL.TRTxxA")
and then TRTA in colref($vars) (a binding holding one name is a one-member set). On the left,
colref(find_vars(…)) in [...] compares element by element and holds when any member is in
the set — as a list-valued metadata accessor does on the left. colref($x) decides row by row: a
row whose binding holds a list is compared as above; any other row is an ordinary value, compared
as the written name would be (numerically against a number list, as dates against date(…)
members). An absent member of a list takes the absent default like any colref read: "",
unless the name is expected to be a number elsewhere in the rule (then the plain missing).
date¶
date(x) → date
The value read as an ISO-8601 date or datetime. Nothing is flattened: the ISO text itself is the
carrier, so a partial date (2012-06) stays partial. Written on either side of a comparison it
makes the comparison temporal — the hull rule:
a partial date is the range of instants it could denote. A date(…) probe against a written-out
list compares dates too: date(--DTC) in [date("2020-01-01")].
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The ISO-8601 value — a column, a string literal or a binding |
Example
expression: 'not empty(DVSTDTC) and date(DVSTDTC) < date(DM.RFICDTC)'
Missing and empty — A missing input yields that missing value. A value that cannot be read
as a date at any precision — "", malformed text — is not an error: every comparison over it
answers false (Junk answers false), so guard it with
is_valid_date(…) or not empty(…) when that is not what you want.
find_vars¶
find_vars(entry) → list of column names
The names of the columns one Requirements.Variables entry
selects — the same entry grammar and the same matcher: a template ("ADSL.TRTxxPN": xx/zz
two digits, y one or more, w one), a glob ("TRT*P"), a regex over the variable name with the
qualifier outside the slashes ("ADSL./TRT[0-9]+PN/"), or a literal name (an existence test).
Unqualified entries read the dataset under validation; a qualified entry reads the joined dataset's
real columns (never a SUPP qualifier), its qualifier matched to the rule's Match_Datasets name
whatever its case. The names come in the dataset's column order — bare
(TRT01P) for an unqualified entry, DS.COLUMN for a qualified one; colref dereferences them. It never expands the rule, so
count(find_vars("TRTxxP")) == 0 asks "is no TRTxxP present?" and the rule runs either way.
| parameter | type | required | description |
|---|---|---|---|
entry |
string | yes | One Requirements.Variables entry |
Example
expression: 'not var_exists("TRTP") and count(find_vars("TRTxxP")) == 0'
⛔ Load errors. A /regex/ entry must be a string literal (a computed one is an evaluation
error); a type suffix (:N), a qualifier written inside the regex ("/ADSL.TRT…/" — write
"ADSL./TRT…/"), a -- in a qualified name and an invalid regex fail the rule at load.
Missing and empty — A missing entry yields a missing result (so not empty(find_vars(X)) does
not fire on it); "" selects nothing ([]).
When there is nothing to answer — []: for a qualifier the rule does not declare in
Match_Datasets or a dataset the run was not given (the loader also reports an undeclared
qualifier, as it does for a written DS.X), and for a computed entry that starts with -- (only a
written entry is specialised to the domain).
lpad¶
lpad(x, width, fill) → text
x left-padded with fill (one character, default a space) to width characters. A longer x
is returned unchanged — never truncated.
| parameter | type | required | description |
|---|---|---|---|
x |
string | yes | The text to pad |
width |
number | yes | The target width, an integer ≥ 0 |
fill |
string | no | The one-character fill, default " " |
Example
expression: 'lpad(str(APERIOD), 2, "0") == "01"'
⛔ Load errors. A written width that is negative, not a whole number or above 32767, and a
written fill that is not exactly one character (a number too, by its text: lpad(X, 3, 0) is
fine, lpad(X, 3, 10) is not), fail the rule at load.
Missing and empty — A missing x yields that missing value; "" pads to width fills.
When width or fill comes from the data, a missing, negative or non-whole width, a width
above 32767, or a fill that is not exactly one character yields the plain missing (MIS).
num¶
num(x) → number
The value as a number: a numeric cell as it is, text parsed as a number. It also selects numeric
comparison: num(QVAL) > 8 compares numerically where a character QVAL > 8 is a type error.
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to convert |
Example
expression: 'num(QVAL) > 8'
Missing and empty — A missing input yields that missing value; text that is not a number,
and "", yield the plain missing (MIS).
printf¶
printf(format, args…) → text
Formats its arguments, always in the root locale (%.1f of 1.5 is 1.5 on every machine).
Supported: %s %d %f %e %x %%, the flags 0 - + space, a width and a precision. %d / %x take
a whole number — judged with the engine's 12-digit tolerance, so a stored 2.0000000000001 counts as
2 — and format the nearest whole number; %f / %e format the number as stored; %s renders
through str.
| parameter | type | required | description |
|---|---|---|---|
format |
string | yes | The format — a string literal |
args |
any | one per conversion | The values |
Example
expression: 'printf("%02d", APERIOD) == "01"'
⛔ Load errors. A computed format, any other conversion (%n, %t…, %1$s), a number of
arguments that differs from the conversions, a string literal at a numeric conversion (%d %f %e
%x), and a written number that is not whole at %d / %x (printf("%d", 1.5)) fail the rule at
load.
Missing and empty — A missing argument makes the result that missing value (two different
missing arguments give the plain missing). %d / %x of a value that is not a whole number (1.5,
or text) yields the plain missing — never a truncated 1, unlike the ${APERIOD:%02d} template,
which keeps its truncation — and so does a negative value at %x (no two's complement).
str¶
str(x) → text
The value as text — a cell's own text: a floating-point cell's cleaned plain text (the engine's
12-digit numeric cleaning; no .0 on a whole number, never scientific), an integer cell's exact
digits (a large integer stays exact), a character value as it is. A computed number (str(AGE +
1)) is written in the same plain notation, and so is a written number (str(3.0) is "3").
str(A) == str(B) compares two values as text, whatever their column types. ⚑ Until 2026-09-30
that comparison read a number written on its left side as "3.0"; whether the new plain
notation stands there is an open owner question (PLAN-dynamic-column-functions F3) — no shipped
rule writes a number inside str.
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The value to convert |
Example
expression: 'str(IDVARVAL) != str(colref(IDVAR))'
Missing and empty — A missing input yields that missing value, identity kept.
time¶
time(x) → time
The value read as an ISO-8601 time of day, partial precision retained — time mirrors
date: written on either side of a comparison it makes the comparison temporal, under the
same hull rule on times of day.
| parameter | type | required | description |
|---|---|---|---|
x |
any | yes | The ISO-8601 time — a column, a string literal or a binding |
Example
expression: 'not empty(QVAL) and time(QVAL) < time("06:00")'
Missing and empty — As for date: a missing input yields that missing value; a
value that cannot be read as a time answers false in every comparison.
value¶
value() → value
The value of the variable currently being iterated, for this row
Takes no arguments.
Example
expression: 'len(value()) > 200'
Missing and empty — A "" cell yields "". A missing cursor or an absent column yields missing.
varname¶
varname() → value
The name of the variable currently being iterated
Takes no arguments.
Example
expression: 'len(varname()) > 8'
Missing and empty — Always present — it is the variable's name, never a data value.