Non-Standard Variables Registry

The Non-Standard Variables (NSV) Registry serves as a reference for using or creating non-standard variables to drive consistency in implementing CDISC Standards. The NSV Registry consists of the following resources:

  • NSVs: A singular resource curated across CDISC Standards to access NSVs to foster standardization when using non-standard variables.
  • Fragments: A list of suggested variable-naming fragments as well as principles for creating fragments.

Approved Non Standard Variables 2023-04-20
Approved Fragments 2023-04-20

The NSV team is composed of representatives from SDS, CT, SEND, CDASH, and ADaM Standards Development teams who approve the variables and metadata to ensure consistency across the Standards. Additionally, the NSV Team approves fragments to help implementers build the variables consistently.

NSVs and SUPPQUALs

The SDTM does not allow the addition of new variables. Therefore, the Supplemental Qualifiers special-purpose dataset model is used to capture NSVs and their association to parent records in General Observation class datasets (Events, Findings, Interventions), Demographics (DM), and Subject Visits (SV). Supplemental Qualifiers are represented as separate SUPP-- datasets for each dataset containing sponsor-defined variables (see SDTMIG v3.4, Section 8.4.2, Submitting Supplemental Qualifiers in Separate Datasets).

SUPP-- represents the metadata and data for each NSV/value combination. As the name suggests, this dataset is intended to capture additional qualifiers for an observation. Data that represent separate observations should be treated as separate observations.

The Supplemental Qualifiers dataset is structured similarly to the RELREC dataset, in that it uses the same set of keys to identify parent records. Each SUPP-- record also includes the name of the qualifier variable being added (QNAM), the label for the variable (QLABEL), the actual value for each instance or record (QVAL), the origin (QORIG) of the value (see SDTMIG v. 3.4, Section 4.1.8, Origin Metadata), and the evaluator (QEVAL) to specify the role of the individual who assigned the value (e.g., "ADJUDICATION COMMITTEE","SPONSOR"). Controlled Terminology for certain expected values for QNAM and QLABEL is included in Appendix C1, Supplemental Qualifiers Name Codes of the SDTMIG v3.4.

Non-standard Variables (NSVs)

NSVs are found in the Therapeutic Area User Guides (TAUGs), which follow the practices outlined in the Alternative Representation of Non-Standard Variables. Accordingly, SDTM-based examples that contain sample data requiring the use of a variable outside the standard set of variables included in the SDTM are represented not with Supplemental Qualifier records, but with NSVs appended to the end of the parent domain, followed by sample metadata for the NSVs.

CDASH-based examples that contain fields, which collect data that require the use of NSVs annotate their SDTMIG target as variables in the domain’s corresponding NS-- dataset, rather than as QNAM/QVAL pairs in the domain’s corresponding SUPP-- dataset (e.g., for an NSV "XXCCCC", as "NSXX.XXCCCC" rather than as "SUPPXX.QVAL where SUPPXX.QNAM = 'XXCCCC'"). To avoid confusion between standard variables and NSVs in the sample datasets, NSVs have been rendered visually distinct, as shown in Figure 1, with white text on black in the header row and separated from the standard variables by a small space.

Metadata for NSVs, from the Define-XML document that would accompany the submission, are tabulated below the example; only those attributes or elements that assist the example are included. (For more information on variable-level metadata in general, see Define-XML v2.1 Sections 4.3 and 5.3.12).

NSV Known Issue Graphic

Figure 1

NSV Curation Principles for entering data into the NSV Registry

 

Metadata Variable Rules
Variable Name
  • Should not contain the two letter domain code or "–" (this is represented in the "Used in Domain(s)" metadata variable.
  • Should be 6 characters or less.
  • Should use CDISC fragment rules.
  • Should have identical metadata as other NSVs with this name.
Label
  • Should be 40 characters or less.
Description and Notes
  • “Description” and “Notes” typically come together as "CDISC Notes" in a specification table.
  • "Description" describes what the NSV is/does.
  • "Notes" covers how to use it, including examples of values.
  • “CDISC Notes” may include any of the following:
    • A description of what the variable means.
    • Information about how this variable relates to another variable.
  • Rules for when or how the variable should be populated, or how the contents should be formatted.
  • Examples of values that might appear in the variable. Such examples are only examples, and although they may be CDISC controlled terminology values, their presence in a CDISC Note should not be construed as definitive. For authoritative information on CDISC Controlled Terminology, please visit NCI-EVS website.
Simple Datatype
  • Must be one of the following:
    • Char
    • Num
XML Datatype
  • Must be one of the following:
    • datetime = ISO 8601 format for date or date and time
    • duration = ISO 8601 format for time intervals
    • float = numeric format with a floating decimal point
    • string = text, no character or format restrictions
Limited to Domain(s)
  • Only used if the NSV would be limited to certain SDTM domains; if the NSV can be used in any domain then this should be blank.
Limited to Class(es)
  • Only used if the NSV would be limited to certain SDTM classes; if the NSV can be used in any class then this should be blank.
Codelist
  • Should be a CDISC/NCI codelist short name without the brackets.
  • Should be blank if External Dictionary is completed.
External Dictionary
  • Should be the name of an existing external dictionary (e.g., MedDRA, DSM-5).
  • Should be blank if "Codelist" is completed.
Role
  • Non-Standard Grouping Qualifier
    • Used to group together a collection of observations within the same domain (e.g., categories or subcategories).
  • Non-Standard Identifier
    • Such as those that identify the study, the subject involved in the study, the domain, and the sequence number of the record.
  • Non-Standard Record Qualifier
    • Defines additional attributes of the observation record as a whole, rather than describing a particular variable within a record (e.g., for a lab test, the specimen type and the name of lab that performed the test).
  • Non-Standard Result Qualifier
    • Describes the specific results associated with the topic variable in a Findings dataset and which answer the question raised by the topic variable.
  • Non-Standard Synonym Qualifier
    • Specifies an alternative name for a particular variable in an observation (e.g., coded version of a verbatim topic variable or the name associated with a test code).
  • Non-Standard Timing
    • Describes the timing of an observation (e.g., start date, end date).
  • Non-Standard Variable Qualifier
    • Used to further modify or describe one or more of a specific set of variables within an observation and which are only meaningful in the context of the variable they qualify (e.g., the unit for a numeric test result or a medication dose, or the laterality of an anatomic location).
Qualifying Variable(s)
  • Must contain an SDTM variable if "Role" is "Non-Standard Variable Qualifier" otherwise this field should be blank.
Source(s)
  • Must contain the Wiki document source of where the NSV has been used.
  • The "Source(s)" field is a controlled code-listed field; new sources should be added to the registry by the NSV Registry Admin.
Used in Domain(s)
  • Must contain the SDTM domain(s) that the NSV has been used in the Source(s).

 

Recommendations to help in developing Non-Standard Variables.
  • Follow ISO and CDISC principles!
  • A definition should not contain implementation instructions.
    • Definitions should not refer to other variables unless absolutely necessary.
  • Acronyms should be spelled out.
  • Suggestion: Define Root Variable first.
    • Domain specific variable definitions will follow exact language except for addition of domain name.
    • Inconsistencies in usage will be easily identified.
  • EVS has coded and created definitions for most CDISC metadata (tagged as NCI definitions in NCIt).
    • These can be used or edited as the team sees fit.

 

Metadata rules for entering data into the NSV Registry

 

Metadata Variable Rules
Variable Name
  • Should not contain the two letter domain code or "–" (this is represented in the "Used in Domain(s)" metadata variable.
  • Should be 6 characters or less.
  • Should use CDISC fragment rules.
  • Should have identical metadata as other NSVs with this name.
  • Reference Variable Label/Variable Fragment Names Rules.
Label
Description and Notes
  • “Description” and “Notes” typically come together as "CDISC Notes" in a specification table.
  • "Description" describes what the NSV is/does.
  • "Notes" covers how to use it, including examples of values.
  • “CDISC Notes” may include any of the following:
    • A description of what the variable means.
    • Information about how this variable relates to another variable.
  • Rules for when or how the variable should be populated, or how the contents should be formatted.
  • Examples of values that might appear in the variable. Such examples are only examples, and although they may be CDISC controlled terminology values, their presence in a CDISC Note should not be construed as definitive. For authoritative information on CDISC Controlled Terminology, please visit NCI-EVS website.
Simple Datatype
  • Must be one of the following:
    • Char
    • Num
XML Datatype
  • Must be one of the following:
    • datetime = ISO 8601 format for date or date and time
    • duration = ISO 8601 format for time intervals
    • float = numeric format with a floating decimal point
    • string = text, no character or format restrictions
Limited to Domain(s)
  • Only used if the NSV would be limited to certain SDTM domains; if the NSV can be used in any domain then this should be blank.
Limited to Class(es)
  • Only used if the NSV would be limited to certain SDTM classes; if the NSV can be used in any class then this should be blank.
Codelist
  • Should be a CDISC/NCI codelist short name without the brackets.
  • Should be blank if External Dictionary is completed.
External Dictionary
  • Should be the name of an existing external dictionary (e.g., MedDRA, DSM-5).
  • Should be blank if "Codelist" is completed.
Role
  • Non-Standard Grouping Qualifier
    • Used to group together a collection of observations within the same domain (e.g., categories or subcategories).
  • Non-Standard Identifier
    • Such as those that identify the study, the subject involved in the study, the domain, and the sequence number of the record.
  • Non-Standard Record Qualifier
    • Defines additional attributes of the observation record as a whole, rather than describing a particular variable within a record (e.g., for a lab test, the specimen type and the name of lab that performed the test).
  • Non-Standard Result Qualifier
    • Describes the specific results associated with the topic variable in a Findings dataset and which answer the question raised by the topic variable.
  • Non-Standard Synonym Qualifier
    • Specifies an alternative name for a particular variable in an observation (e.g., coded version of a verbatim topic variable or the name associated with a test code).
  • Non-Standard Timing
    • Describes the timing of an observation (e.g., start date, end date).
  • Non-Standard Variable Qualifier
    • Used to further modify or describe one or more of a specific set of variables within an observation and which are only meaningful in the context of the variable they qualify (e.g., the unit for a numeric test result or a medication dose, or the laterality of an anatomic location).
Qualifying Variable(s)
  • Must contain an SDTM variable if "Role" is "Non-Standard Variable Qualifier" otherwise this field should be blank.
Source(s)
  • Must contain the Wiki document source of where the NSV has been used.
  • The "Source(s)" field is a controlled code-listed field; new sources should be added to the registry by the NSV Registry Admin.
Used in Domain(s)
  • Must contain the SDTM domain(s) that the NSV has been used in the Source(s).

 

If a desired NSV can’t be identified in the NSV Registry, then the Fragment Database may be used to create a new non-standard variable. The fragment database was created to facilitate the development of the non-standard variables. The Variable Fragment Naming Rules will provide guidance for the creation of non-standard variables.

When using the fragment spreadsheet to create NSVs, it is important to remember that there are conventions used in CDASH and ADaM that have meaning dependent on where the fragment sits in the variable (whether prefix, suffix or in the middle). It is best to avoid using fragments in these locations for NSVs to avoid conflicts in traceability across the Foundational models.

Variable Label/Variable Fragment Naming Rules

Summary

  1. The Variable Label is designed to represent the essence of the variable through discrete concepts, breaking down the variable meaning/concept into the following topics sub-concepts:
    1. What is the primary topic of the given variable (Object or Main Concept)?
    2. What is being asked about the primary topic (Property and Property Qualifier)?
    3. What is/are the anticipated response(s) or answer(s) to Representation term, in turn, defines the data type of the answers provided. Having it defined properly helps significantly with identifying what kind of data is collected against the given variable.
  1. The Variable Label should be created as a combination of:

Object + Property Qualifier(s) + Property + Representation Qualifier (s) + Representation Term

  1. Use fragments that make the Variable Name as readable as possible.
  2. Six letters
    1. Use Main Concept first, following the design strategy in point #1.
    2. Remove vowels, skinny ones such as "I" first, then consonants (again, skinny letters first).
    3. Remove duplicate letters.
    4. Use fragment spreadsheet and more letters for the most important concepts.
    5. Have 1 - 6 characters available depending on the variable concept/idea
    6. May be helpful to see the different options to assess the best readability
    7. Look at the letters and consider if another word comes to mind, if yes, consider a different fragment variation

Considerations when Constructing Non-standard Variables Relative to ADaM

ADaM Non-standard Variables

  • Generally, for an ADaM Non-standard Variable, the naming convention is associated with an expected variable type, or an expected value considered overall. For example, if any variable ends with *FL, its value can only be null, Y or N; otherwise, it will trigger ADaM compliance.
  • Another example, any variable ending with *DT or DTM, the expected variable type is integer and can’t be character.
  • Another example, variables whose names end in GRy, Gy, or CATy are grouping character version of variables, where y is an integer [1-99, not zero-padded] representing a grouping scheme. Other required suffix fragments for use in ADaM variables with details see ADaMIG v1.3 table 3.1.5.1.

SDTM Non-standard Variables

  • When SDTM NSVs carry to ADaM datasets, how their name is chosen could impact the ADaM compliance if the ADaM naming convention associated with expected type and/or value is not followed. The SDTM NSV naming convention focuses on the name of the concept (the variable label).
  • Name fragments from the ADaMIG: FL, TM, DY, BL, CHG, SC (screening).
  • Name fragments from ADaM Oncology Examples: *STT (status), MS (metastasis), P (prior), TS (time since).

* is for suffix. Others with position of this fragment within the variable name are dependent on the purpose of the variable.

Recommendations to help in developing Non-Standard Variables.
  • Follow ISO and CDISC principles!
  • A definition should not contain implementation instructions.
    • Definitions should not refer to other variables unless absolutely necessary.
  • Acronyms should be spelled out.
  • Suggestion: Define Root Variable first.
    • Domain specific variable definitions will follow exact language except for addition of domain name.
    • Inconsistencies in usage will be easily identified.
  • EVS has coded and created definitions for most CDISC metadata (tagged as NCI definitions in NCIt).
    • These can be used or edited as the team sees fit.