1. 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

2. 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

3. 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

4. WHY

5. 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

6. 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

7. REQUIREMENTS

8. 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

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

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

11. 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

12. 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

13. 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

14. 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

15. 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:

16. WHAT

17. What?
Define.XML with and without stylesheet

18. Why?
Requirements?
What?
How?
Summary
What?

19. Why?
Requirements?
What?
How?
Summary
What?

20. Why?
Requirements?
What?
How?
Summary
What?

21. Why?
Requirements?
What?
How?
Summary
What?

22. Why?
Requirements?
What?
How?
Summary
What?

23. What? Define-XML Version 2.0.0 can be used for SDTM and ADaM
Why?
Requirements?
What?
How?
Summary
What?
Define-XML Version 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

24. 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

25. HOW

26. 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

27. 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

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

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

30. 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

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

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

33. 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

34. 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:

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

36. 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

37. 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

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

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

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

41. 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.

42. 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.

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

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

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

46. 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.

47. 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.

48. 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

49. 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

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

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

52. 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.

53. 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

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

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

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

57. 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.

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

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

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

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

62. 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.

63. 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.

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

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

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

67. 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.

68. 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.

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

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

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

72. 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.

73. SUMMARY

74. 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

75. Q&A