To change this title, go to Notes Master 12/5/2018 Define.XML A CASE study describing how to produce Define.XML from within SAS Dianne Weatherall Sep 2012

Topics for Discussion Why do we create the Define? Requirements to create the Define? What is Define.XML? How do we create the Define in SAS? Summary

Note Examples and code are based on the Draft Define V2 Slides are based on SDTM Define, but similar principles can be applied to the ADaM Define Key differences are explained in the Define Draft V2

WHY

To change this title, go to Notes Master Why? Requirements? What? How? Summary To change this title, go to Notes Master Why? 12/5/2018 Data Management: imagine getting vendor data without non-CRF guidelines. Bios: imagine getting CRF data without an aCRF / specifications

Why? Requirements? What? How? Summary Why? To describe what is included in the electronic data transfer (datasets, variables, codelists, etc) -> METADATA -> an elaborate “PROC CONTENTS” and more To provide a user-friendly document with links to navigate easily, and to access information easily To easily access the annotated CRF and datasets To have a standard format to describe the electronic data transfer Why XML? Machine readable format for use by software applications Browser-based report (through the use of an XSL stylesheet) Vendor neutral, platform independent

REQUIREMENTS

Why? Requirements? What? How? Summary Requirements? Metadata in a usable format, easy to capture and ability to import into SAS (recommended format = Excel) Dataset metadata: list of domains -> name, description, class, structure, purpose, keys, location Variable metadata: list of variables: -> name, label, type, controlled terms / format, origin, role, comment Controlled terms: coded value, decode Value-level metadata: variable, where, type, controlled terms or format, origin, computation method Computational algorithms: reference name, name, computation method Data in XPT format Annotated CRF in PDF format Supporting documentation: Reviewers guide / complex algorithms in PDF format

Requirements? Example: dataset metadata Why? Requirements? What? How? Summary Requirements? Example: dataset metadata

Requirements? Example: variable metadata Why? Requirements? What? How? Summary Requirements? Example: variable metadata

Requirements? Example: controlled terms Why? Requirements? What? How? Summary Requirements? Example: controlled terms Usually includes all possibilities on the CRF, not only those in the data Needs to be set up from the CRF, not the data

Requirements? Example: value-level metadata Why? Requirements? What? How? Summary Requirements? Example: value-level metadata 2 types: SUPPQUAL (QVAL) and FINDINGS (ORRES) Can be generated from the data, especially electronic labs

Requirements? Example: computational algorithms Why? Requirements? What? How? Summary Requirements? Example: computational algorithms Used for standard algorithms that can be applied across variables Very long derivations should rather be specified in a PDF file, and linked from the variable comment

Requirements? Specification vs Metadata Specification Why? Requirements? What? How? Summary Requirements? Specification vs Metadata Specification Instructions to a programmer to get to the final SDTM / ADaM dataset Contains derivations that often refer to raw variable names (for programming) May contain SAS code in some cases May refer to other documents (e.g. SAP etc) Metadata Describes the contents of the final SDTM/ADaM dataset Contains derivations that describe in words how the data was derived (for traceability and reviewer information) Does not contain SAS code and does not refer to raw variables Contains links to other documents

Requirements? Specification vs Metadata To combine or not to combine? Why? Requirements? What? How? Summary Requirements? Specification vs Metadata To combine or not to combine? It makes sense to create one document that serves both purposes Prevents rework Consistency Less work BUT… make sure you separate programmer notes from reviewer comments Example:

WHAT

What? Define.XML with and without stylesheet

Why? Requirements? What? How? Summary What?

Why? Requirements? What? How? Summary What?

Why? Requirements? What? How? Summary What?

Why? Requirements? What? How? Summary What?

Why? Requirements? What? How? Summary What?

What? Define-XML Version 2.0.0 can be used for SDTM and ADaM Why? Requirements? What? How? Summary What? Define-XML Version 2.0.0 can be used for SDTM and ADaM Terminology: Def: declaration of an object Ref: reference to an object OID: identify a metadata object Validation of the Define.XML: It must properly reference versions of the CDISC standards Conform to schemas Meet all requirements of the Define-XML Specification Can be checked using OpenCDISC according to defined rules

What? Structure of the XML file Why? Requirements? What? How? Summary What? Structure of the XML file XML header, the ODM root element, Study and MetaDataVersion Linked supporting PDF documents (e.g. aCRF) Value List definitions (e.g. for Supplemental Qualifiers / Findings Tests) Where Clause definitions (referenced in Value List definitions) Dataset definitions (ItemGroup) Variable definitions (ItemDef) Code List definitions (Codelist) Methods definitions (MethodDef) Comments definitions (CommentDef) Leafs definitions

HOW

PREPARATION BEFORE WRITING TO XML FILE Why? Requirements? What? How? Summary To change this title, go to Notes Master PREPARATION BEFORE WRITING TO XML FILE 12/5/2018 Include the precision of numeric variables, but running through the data Calculate “repeating” information for Dataset Metadata Determine “repeating” (e.g. STUDYID, VISITNUM) vs “unique” variables (e.g. AESEV) – variables can only be defined once in a ITEMDEF statement, so the program needs to check for variables appearing in more than one domain (e.g. STUDYID, VISITNUM, etc) Special characters: “&” -> & “<“ -> < Etc Create XPT files of the SDTM datasets Import the specifications into SAS and create a dataset containing the Dataset and Variable metadata Import the methods into SAS and merge onto the metadata by the method name XML does not like special characters – convert characters to text Create a value-level metadata dataset by choosing “TESTCD”, “PARMCD” and “QNAM” variables and obtaining the values in those variables from the data Create a codelist dataset by running through variables and value-level variables with codelists attached to them and obtaining the values for those variables Codelists -> set up in specs vs create from data

How? Create XML file within SAS using: DATA steps Why? Requirements? What? How? Summary How? Create XML file within SAS using: DATA steps FILE and PUT statements

XML Header + ODM root element Why? Requirements? What? How? Summary XML Header + ODM root element Example code:

XML Header + ODM root element Why? Requirements? What? How? Summary XML Header + ODM root element Example code: Study-specific derivations: - Creation date/time

XML Header + ODM root element Why? Requirements? What? How? Summary XML Header + ODM root element Example code: Simple FILE and PUT statements Study-specific parameters can be read in using macro parameters or derived - e.g. creation date/time

Study + MetaDataVersion Why? Requirements? What? How? Summary Study + MetaDataVersion Example code:

Study + MetaDataVersion Why? Requirements? What? How? Summary Study + MetaDataVersion

Study + MetaDataVersion Why? Requirements? What? How? Summary Study + MetaDataVersion Example code: Simple FILE and PUT statements – use the MOD option on the FILE statement to append to the text file Study-specific parameters can be read in using macro parameters or derived - e.g. study name and description

Linked supporting PDF documents (e.g. aCRF) + Leafs definition Why? Requirements? What? How? Summary Linked supporting PDF documents (e.g. aCRF) + Leafs definition Example code:

Linked supporting PDF documents (e.g. aCRF) + Leafs definition Why? Requirements? What? How? Summary Linked supporting PDF documents (e.g. aCRF) + Leafs definition

Linked supporting PDF documents (e.g. aCRF) + Leafs definition Why? Requirements? What? How? Summary Linked supporting PDF documents (e.g. aCRF) + Leafs definition Example code: Simple FILE and PUT statements with a MOD option

Linked supporting PDF documents (e.g. aCRF) + Leafs definition Why? Requirements? What? How? Summary Linked supporting PDF documents (e.g. aCRF) + Leafs definition Example code: Simple FILE and PUT statements with a MOD option

Why? Requirements? What? How? Summary Value List definitions (e.g. Findings Tests) and Where Clause definitions Example code:

Why? Requirements? What? How? Summary Value List definitions (e.g. Findings Tests) and Where Clause definitions Example code:

Why? Requirements? What? How? Summary Value List definitions (e.g. Findings Tests) and Where Clause definitions

Why? Requirements? What? How? Summary Value List definitions (e.g. Findings Tests) and Where Clause definitions Example code: Example: VSORRES Create a dataset in SAS of value-level variables and their values. Output an ITEMREF statement for each value of VSORRES (e.g. DIABP) and reference a WHERECLAUSE.

Why? Requirements? What? How? Summary Value List definitions (e.g. Findings Tests) and Where Clause definitions Example code: Example: VSORRES Output a WHERECLAUSEDEF statement for each value of VSORRES (e.g. DIABP) and use the same WHERECLAUSE name referenced in the ITEMREF.

Why? Requirements? What? How? Summary Value List definitions (e.g. for Supplemental Qualifiers) and Where Clause definitions Example code:

Why? Requirements? What? How? Summary Value List definitions (e.g. for Supplemental Qualifiers) and Where Clause definitions Example code:

Why? Requirements? What? How? Summary Value List definitions (e.g. for Supplemental Qualifiers) and Where Clause definitions

Why? Requirements? What? How? Summary Value List definitions (e.g. for Supplemental Qualifiers) and Where Clause definitions Example code: Example: SUPPDM.QVAL Output an ITEMREF statement for each value of SUPPDM.QNAM (e.g. RACE1) and reference a WHERECLAUSE.

Why? Requirements? What? How? Summary Value List definitions (e.g. for Supplemental Qualifiers) and Where Clause definitions Example code: Example: SUPPDM.QVAL Output a WHERECLAUSEDEF statement for each value of SUPPDM.QVAL (e.g. RACE1) and use the same WHERECLAUSE name referenced in the ITEMREF.

Dataset definitions (ItemGroup) Why? Requirements? What? How? Summary Dataset definitions (ItemGroup) Dataset Definitions: Dataset definitions: ItemGroupDef element Include references to variable definitions Include references to actual data file Variable references: ItemDef element Dataset definition: def:leaf element

Dataset definitions (ItemGroup) Why? Requirements? What? How? Summary Dataset definitions (ItemGroup) Attributes: Repeating: No for datasets with one record per subject Yes for datasets with more than one record per subject Mandatory: Yes for required variables No for Expected or Permissible variables Domain: Name of the domain IsReferenceData: Yes for reference datasets (no subjects) No for subject-level datasets

Dataset definitions (ItemGroup) Why? Requirements? What? How? Summary Dataset definitions (ItemGroup) Example code:

Dataset definitions (ItemGroup) Why? Requirements? What? How? Summary Dataset definitions (ItemGroup)

Dataset definitions (ItemGroup) Why? Requirements? What? How? Summary Dataset definitions (ItemGroup) Example code: Example: DM Output ITEMGROUP statement for each domain and include a ITEMREF statement for each variable. Include a link to the dataset.

Variable definitions (ItemDef) Why? Requirements? What? How? Summary Variable definitions (ItemDef) Variable Definitions: Variable definitions: ItemDef element Other elements: Controlled terminology: CodeList Value level metadata: def:ValueListDef Computational method: MethodDef Comments: def:CommentDef Origin: def:Origin

Variable definitions (ItemDef) Why? Requirements? What? How? Summary Variable definitions (ItemDef) Data types: text integer float datetime date time partialDate partialTime incompleteDatetime durationDatetime

Variable definitions (ItemDef) Why? Requirements? What? How? Summary Variable definitions (ItemDef) Example code:

Variable definitions (ItemDef) Why? Requirements? What? How? Summary Variable definitions (ItemDef)

Variable definitions (ItemDef) Why? Requirements? What? How? Summary Variable definitions (ItemDef) Example code: Example: DM Output ITEMDEF statement for each variable. Include a link to the BLANKCRF for CRF Page origins and include the page number. This comes from the metadata in specs.

Code List definitions (Codelist) Why? Requirements? What? How? Summary Code List definitions (Codelist) Example code:

Code List definitions (Codelist) Why? Requirements? What? How? Summary Code List definitions (Codelist) Example code:

Code List definitions (Codelist) Why? Requirements? What? How? Summary Code List definitions (Codelist)

Code List definitions (Codelist) Why? Requirements? What? How? Summary Code List definitions (Codelist)

Code List definitions (Codelist) Why? Requirements? What? How? Summary Code List definitions (Codelist) Example code: Example: AE.AESEV Output CODELISTREF in the ITEMDEF statement for each variable with a codelist.

Code List definitions (Codelist) Why? Requirements? What? How? Summary Code List definitions (Codelist) Example code: Example: AE.AESEV Output a CODELIST statement for each codelist and include each value as a CODEDVALUE. Use the same name for the codelist as referenced in the ITEMDEF statement.

Methods definitions (MethodDef) Why? Requirements? What? How? Summary Methods definitions (MethodDef) Example code:

Methods definitions (MethodDef) Why? Requirements? What? How? Summary Methods definitions (MethodDef) Example code:

Methods definitions (MethodDef) Why? Requirements? What? How? Summary Methods definitions (MethodDef)

Methods definitions (MethodDef) Why? Requirements? What? How? Summary Methods definitions (MethodDef) Example code: Example: EG.EGDRVFL For variables with method attached to them, include the METHODOID in the ITEMREF in the ITEMGROUP statement.

Methods definitions (MethodDef) Why? Requirements? What? How? Summary Methods definitions (MethodDef) Example code: Example: EG.EGDRVFL Output a METHODDEF statement for each method. Use the same name as referenced in the ITEMREF statement. Include a link to the Complex Algorithms document if required.

Comments definitions (CommentDef) Why? Requirements? What? How? Summary Comments definitions (CommentDef) Example code:

Comments definitions (CommentDef) Why? Requirements? What? How? Summary Comments definitions (CommentDef) Example code:

Comments definitions (CommentDef) Why? Requirements? What? How? Summary Comments definitions (CommentDef)

Comments definitions (CommentDef) Why? Requirements? What? How? Summary Comments definitions (CommentDef) Example code: Example: AE.AEENDY For variables with comments attached to them, include the COMMENTOID in the ITEMDEF. Output a COMMENTDEF statement for each comment. Use the same name as referenced in the ITEMDEF statement.

SUMMARY

Why? Requirements? What? How? Summary Summary Define.XML files help to describe what is in an electronic submission of data Define.XML is a user-friendly document when rendered using a stylesheet DATA steps and PUT statements can be used to create a Define.XML file in SAS using dataset, variable and value-level metadata and codelists/method information

Q&A