ADaMDatasetTemplate

The structural template for an ADaM dataset.

Usage

Source

ADaMDatasetTemplate(
    name,
    label,
    description,
    dataset_class,
    variables=list(),
    natural_keys=list(),
)

An ADaMDatasetTemplate describes the structure of one type of CDISC Analysis Data Model (ADaM) dataset: its label and class, the variables that form its natural key, and the specifications of its variables (as ADaMVariableSpec objects, in order). Templates are obtained with get_adam_dataset().

Parameters

name: str

The template name: "ADSL", "BDS", "ADAE" or "ADTTE".

label: str

The dataset label, such as "Subject Level Analysis Dataset".

description: str

A short description of what the dataset holds and what a record is.

dataset_class: str

The ADaM dataset class, which validate_adam() uses to choose the checks for the type of dataset. In the templates, it’s the same as name.

variables: list[ADaMVariableSpec] = list()

The specifications of the dataset’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 Basic Data Structure (BDS), the structure of analysis datasets such as ADVS (vital signs) and ADLB (laboratory results):

import pointblank as pb

bds = pb.get_adam_dataset("BDS")

print(bds.label, "|", bds.dataset_class)
print(bds.description)
print(bds.natural_keys)

Basic Data Structure | BDS
One or more records per subject per analysis parameter per analysis timepoint. Used for efficacy, lab, vital signs, etc.
['STUDYID', 'USUBJID', 'PARAMCD', 'AVISIT', 'ADT']

A BDS dataset has a record for each analysis parameter (PARAMCD) at each visit and date, for each subject. The template’s properties list the required and conditionally required variables:

print(bds.required_variables)
print(bds.conditional_variables)

['STUDYID', 'USUBJID', 'PARAMCD', 'PARAM', 'AVAL']
['TRT01P', 'AVALC', 'BASE', 'CHG', 'AVISIT', 'ADT', 'ABLFL']

Every BDS dataset needs the identifiers, the parameter and the analysis value. The conditional variables, such as the baseline value BASE and the change from baseline CHG, are needed only for some analyses.

See Also

get_adam_dataset()

Get the template for a type of dataset.

ADaMVariableSpec

The specification of a variable in the template.

SDTMDomainTemplate

The equivalent for SDTM domains.

Attributes

Name	Description
required_variables	The names of the required variables, in order.
conditional_variables	The names of the conditionally required variables, in order.
population_flags	The names of the population flag variables, 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 this type. validate_adam() adds a null check for each one, and validate_adam_structure() reports the ones that are missing.

Examples

import pointblank as pb

pb.get_adam_dataset("ADTTE").required_variables

['STUDYID', 'USUBJID', 'PARAMCD', 'PARAM', 'AVAL', 'STARTDT', 'ADT', 'CNSR']

A time-to-event dataset (ADTTE) needs the parameter, the time to the event (AVAL), the start and event dates, and the censoring indicator (CNSR). This is a property, so it’s used without parentheses.

conditional_variables

The names of the conditionally required variables, in order.

conditional_variables: list[str]

A conditionally required variable (core designation "Cond") is needed only in some situations, which the variable’s condition describes. validate_adam_structure() reports the ones that are missing when strict=True.

Examples

import pointblank as pb

adsl = pb.get_adam_dataset("ADSL")

for name in adsl.conditional_variables[:4]:
    print(name, "->", adsl.get_variable(name).condition)

TRT01A -> Required if actual differs from planned
TRT01PN -> Required if treatment mapped to numeric
TRTSDT -> Required if treatment start used in derivations
TRTEDT -> Required if treatment end used in derivations

These are the first four conditional variables of ADSL, with the condition for each one. This is a property, so it’s used without parentheses.

population_flags

The names of the population flag variables, in order.

population_flags: list[str]

Population flags, such as SAFFL (safety) and ITTFL (intent-to-treat), say whether each subject is in an analysis population, with the values "Y" and "N". Only the ADSL template has them.

Examples

import pointblank as pb

pb.get_adam_dataset("ADSL").population_flags

['SAFFL', 'ITTFL', 'EFFFL', 'RANDFL', 'ENRLFL', 'PPROTFL', 'COMPLFL']

validate_adam() checks each of these flags that is a column of the data. 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 ADaM variable names are in upper case.

Returns

ADaMVariableSpec | None

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

Examples

import pointblank as pb

adtte = pb.get_adam_dataset("ADTTE")

adtte.get_variable("CNSR")

ADaMVariableSpec(name='CNSR', label='Censor', dtype='Num', core='Req', required=True, max_length=None, controlled_term=None, source=None, condition=None, is_population_flag=False)

CNSR is the required censoring indicator of a time-to-event dataset. A name that isn’t in the template gives None:

print(adtte.get_variable("AESEQ"))

None

AESEQ belongs to the ADAE template, not to ADTTE.