Skip to main content

SDTMDomainTemplate

The structural template for an SDTM domain.

Usage

Source

SDTMDomainTemplate(
    domain,
    label,
    description,
    domain_class,
    repeating,
    variables=list(),
    natural_keys=list(),
)

An SDTMDomainTemplate describes the structure of one domain of the CDISC Study Data Tabulation Model (SDTM): its label and observation class, whether it has many records per subject, the variables that form its natural key, and the specifications of its variables (as SDTMVariableSpec objects, in the SDTM order). Templates are obtained with get_sdtm_domain().

Parameters

domain: str

The two-letter domain code, such as "DM", "AE" or "LB".

label: str

The domain label, such as "Demographics" or "Adverse Events".

description: str

A short description of what the domain holds.

domain_class: str

The SDTM observation class: "Special Purpose", "Events", "Interventions" or "Findings".

repeating: bool

Whether the domain can have more than one record per subject. Only DM, which has one record per subject, isn’t repeating.

variables: list[SDTMVariableSpec] = list()

The specifications of the domain’s variables, in order. The default is an empty list.

natural_keys: list[str] = list()
The names of the variables that together identify a record. The default is an empty list.

Examples

Let’s look at the template for the Adverse Events (AE) domain:

import pointblank as pb

ae = pb.get_sdtm_domain("AE")

print(ae.label, "|", ae.domain_class, "| repeating:", ae.repeating)
print(ae.description)
print(len(ae.variables), "variables")
Adverse Events | Events | repeating: True
Adverse events reported during the study.
28 variables

The variables are in the variables list. Here are the first eight, with their type, role and core designation:

for var in ae.variables[:8]:
    print(f"{var.name:9}{var.dtype:5}{var.role:12}{var.core}")
STUDYID  Char Identifier  Req
DOMAIN   Char Identifier  Req
USUBJID  Char Identifier  Req
AESEQ    Num  Identifier  Req
AEGRPID  Char Identifier  Perm
AEREFID  Char Identifier  Perm
AESPID   Char Identifier  Perm
AETERM   Char Topic       Req

The template’s properties collect the names of the variables with a given core designation or role, and get_variable() gets the specification of one variable.

See Also

get_sdtm_domain()

Get the template for a domain.

SDTMVariableSpec

The specification of a variable in the template.

ADaMDatasetTemplate

The equivalent for ADaM datasets.

Attributes

Name Description
required_variables The names of the required variables, in order.
expected_variables The names of the expected variables, in order.
identifier_variables The names of the variables with the Identifier role, in order.

required_variables

The names of the required variables, in order.

required_variables: list[str]

Required variables (core designation "Req") must be in every dataset of the domain and can’t be null. validate_sdtm() adds a null check for each one, and validate_sdtm_structure() reports the ones that are missing.

Examples

import pointblank as pb

pb.get_sdtm_domain("DM").required_variables
['STUDYID',
 'DOMAIN',
 'USUBJID',
 'SUBJID',
 'SITEID',
 'SEX',
 'ARMCD',
 'ARM',
 'COUNTRY']

These are the variables that every Demographics (DM) dataset must have. This is a property, so it’s used without parentheses.

expected_variables

The names of the expected variables, in order.

expected_variables: list[str]

Expected variables (core designation "Exp") should be in every dataset of the domain, but their values may be null when the data wasn’t collected or doesn’t apply. validate_sdtm_structure() reports the ones that are missing when strict=True.

Examples

import pointblank as pb

pb.get_sdtm_domain("DM").expected_variables
['RFSTDTC',
 'RFENDTC',
 'RFXSTDTC',
 'RFXENDTC',
 'AGE',
 'AGEU',
 'RACE',
 'ACTARMCD',
 'ACTARM']

For Demographics (DM), these include the reference dates (such as RFSTDTC), age, race and the actual arm. This is a property, so it’s used without parentheses.

identifier_variables

The names of the variables with the Identifier role, in order.

identifier_variables: list[str]

Identifier variables identify the study, the subject, the domain and the record, as with STUDYID, USUBJID, DOMAIN and the sequence number.

Examples

import pointblank as pb

pb.get_sdtm_domain("AE").identifier_variables
['STUDYID', 'DOMAIN', 'USUBJID', 'AESEQ', 'AEGRPID', 'AEREFID', 'AESPID']

Besides the identifiers that all domains share, the Adverse Events (AE) template has the sequence number AESEQ and the optional group, reference and sponsor identifiers. This is a property, so it’s used without parentheses.

Methods

Name Description
get_variable() Get the specification of a variable.

get_variable()

Get the specification of a variable.

Usage

Source

get_variable(name)

Parameters

name: str
The variable name. This is case-sensitive, and SDTM variable names are in upper case.

Returns

SDTMVariableSpec | None
The specification of the variable, or None if the template has no variable with that name.

Examples

import pointblank as pb

dm = pb.get_sdtm_domain("DM")

dm.get_variable("AGE")
SDTMVariableSpec(name='AGE', label='Age', dtype='Num', role='Qualifier', required=False, max_length=None, controlled_term=None, core='Exp')

AGE is an expected numeric variable, so it has no maximum length. A name that isn’t in the template gives None:

print(dm.get_variable("age"))
None

The lookup is case-sensitive, so the lower-case name doesn’t match AGE.