Define-XML 2.0.

0
PresentedatDCDISCOctober27,2015
Rockville,MD
,

JaneDiefenbachwithJohnBrega andLindaCollins
PharmaStatLLC

Topics and Demos

WhatisDefineXML,wherediditcomefrom,andwhyisituseful?
DefineXMLV1.0wasagamechanger.
DefineXMLV2.0isbetterbuthow?
Notesfromthefield
Whatsdifferent
ChallengesfacingDefineXMLV2.0.0producersandusers

What is Define-XML?
Define XML?
LatestversionofCDISCmodeltodocumentdatabases
BasedonCDISCODMschema(xmlformat)
WorksonSDTM,SEND,ADaMandvirtuallyanyproprietarystructure
Machinereadableand browseable withtherightstylesheet

Where did it come from?

199901GeneralConsiderationsElectronicFormat.
Documentdatabasesusingmetadata.Simple
d b
d
l specfordefine.pdf.
f d f
df
20050205

CRTDDS/define.xmlV1.0.
M hi
Machinereadable,muchmorecompleteandspecificthan
d bl
h
l t
d
ifi th
define.pdf.Stylesheetisaproblem.

2009 11 27
20091127

DefineXMLDraftV2.0;
Define
XML Draft V2 0; extends1.0withflexiblevaluelevel
extends 1 0 with flexible value level
metadatasoitworksbetterforADaMandsolvessomeproblemsin
SDTMdocumentation.

20130305

FinalDefineXMLV2.0, includesarobuststylesheet.Thisversionis
implementable.

First generation, 1999

d fi
define.pdf
df
Specification
Example

Second generation, 2005

CRT-DDS
CRT
DDS V1
V1-0-0,
0 0, define.xml
Specification
Example

Third generation, 2013

D fi XML V2
Define-XML
V2.0.0,
00 d
define.xml
fi
l
Specification
Example

Problems define
define.xml
xml solves
Databasedocumentationwasincomplete,everybodydidit
differently.
Paperandpdfdocumentation,evenonstandardizedelectronic
databases, creates data islands. To combine databases you have to
databases,createsdataislands.Tocombinedatabasesyouhaveto
readthedocumentationandwriteprogramstoexecutedocumented
rules.
Paperandpdfshideinconsistenciesbetweenthedatabaseandits
Paper and pdfs hide inconsistencies between the database and its
documentation.

with content rules, machine-readable

metadata
t d t
BecauseCDISCauthors...
Designedacommonsetofdataelementsfordatabasedocumentation
(metadata)
Specifiedhowtorepresentthem
Publishedtheelementsinamachinereadableformat

Userscan...
Producemoreconsistentdocumentationforhumanreaders
Produce more consistent documentation for human readers
Automatedata/documentationcomparisons
Usemetadatatoloadandquerydatarepositories

With define
define.xml
xml V1 we got
Sixclassesofmetadata:

SStudylevel
d l l
Domainlevel
Variablelevel
Value level
Valuelevel
ControlledTerminology
ComputationalMethod

Amachinereadablemodelthatcouldsupportflat(twodimensionaltables)
pp
(
)
andmultidimensionalrepresentations(linksinalldirections)
Unambiguouscontentrules(mostly)
Automated linking
Automatedlinking
DemoV1define.xmlanddefine.pdf,compareto1999define.pdf

Neat new features in V2 (Janes

(Jane s top 5)
1.
2.
3.
4.
5.

Thestylesheetworks!
Datasetscanhavecomments.Andmethods.
Commentscanlinkouttooneormoreexternaldocuments.
Valuelevelmetadatacanbemorespecificwithwhereclauses.
Codelistmetadatamodelisricher.

The stylesheet works!

Itdoesn
It doesnttget
get stuck
stuck onTA
on TA
Thebackbuttonisreliable
pdfoptionforprinting

DemoV1define.xmlanddefine.pdf

Datasets can have comments. And

methods!
th d !
Examplesofdatasetsthatneedit:
Examples of datasets that need it:
EXandPP,bothderiveddomains
Customdomains
Standarddomainswhentheyareusedofflabel
StudyDataReviewersGuide(SDRG)hadtomakeupforthis
d fi i
deficiencyinV1.0.Besttokeepdatasetmetadatawiththedataset
i V1 0 B t t k
d t t
t d t ith th d t t

Describing datasets in V1
V1.0
0

14

Describing datasets in V2

15

Comments can link to other documents

LinkouttoReviewer
Link out to ReviewerssGuides(SDRGorADRG)e.g.
Guides (SDRG or ADRG) e.g.
WindowingrulesinADRG
EXderivationfromECandDAinSDRG
EfficacydatasetconstructioninADRG

DemoV2Commentswithexternalpage:file links

Value-level metadata can be specific:

SDTM example
SDTM,
l 1
V1.0doesnotsupportonetestwithtwosetsofattributes,e.g.
SerumProteinhasacontinuousnumericresult(LBCAT=CHEMISTRY,
LBSPEC=SERUM,LBSTRESC=80,LBSTRESU=mg/dL)
UrineProteinusuallyhasanordinalcharacterresult(LBCAT=URINALYSIS,
LBSPEC URINE LBSTRESC 1 LBSTRESU )
LBSPEC=URINE,LBSTRESC=+1,LBSTRESU=)
LBTESTCD=PROTandLBTEST=Proteinforbothbuttypeisdifferentand
urinalysisneedsacodelistonresultandunits

V1.0onlysupportsoneversionofvaluelevelmetadataattheTestor
Suppqual level.Theresultisanonspecificmashup.
V2.0 supports two and more.
V2.0supportstwoandmore.

Describing Value-level
Value level Record Types
Example from 2.0, part 4: Same LBTESTCD different LBCAT
Variable

Where

LBSTRESC LBCAT="CHEMISTRYand
LBTESTCD=BILI(Bilirubin)
LBSTRESC LBCAT="CHEMISTRY"
LBCAT "CHEMISTRY"
andLBTESTCD="GLUC"(Glucose)
LBSTRESC LBCAT="URINALYSISand
LBTESTCD=BILI(Bilirubin)
LBSTRESC

18

LBTESTCD="GLUC"(Glucose)and
LBCAT=URINALYSIS

Type

Length/ControlledTermsor
Display Format
Format
Float
8

eDT

fl
float

eDT
DT

text

text

24

Origin Derivation/Comment

8["1+",2+",
eDT
+3,"NEGATIVE"]
<Uriin>
8["1+","2+","NEGATIVE", eDT
"TRACE"]
<Urin>

Value-level metadata can be specific:

SDTM example
SDTM,
l 2
ECGdatacanbecontinuousorcategorical,dependingonthetest,
whichmightbeameasurement,afinding,oraninterpretation
V1.0onlysupportsoneversionofvaluelevelmetadatasowecould
not put code lists on results or units.
notputcodelistsonresultsorunits.
V2.0useswhereclausestodefinevaluelevelmetadatathatcanrefer
tomanysubsetsofobservations

Describing Value-level
Value level Record Types
Example from 2.0, part 1: VariablelevelLinks

20

Describing Value-level
Value level Record Types
Example from 2.0, part 2: Value Level

21

Value-level metadata can be specific:

AD M
ADaM
Studyendpointisbloodpressure.Variousapproachestoimputation
producethreekindsofrecords:
Noimputation:PARAM=DIABP,DTYPE=
Lastobservationcarriedforward:PARAM=DIABP,DTYPE=LOCF
Meanoflastthreeobservations:PARAM=DIABP,DTYPE=MEANP3

Theserecordshavethreedifferentorigins(onetraceabletoSDTM,
the other two derived with different rules) V1 0 lumps all in one
theothertwoderivedwithdifferentrules).V1.0lumpsallinone
PARAMinthevaluelevelmetadataandthethreeoriginsendup
mashedupinComments.
V2.0useswhereclauses.
V2 0
h
l

ADaM value-level metadata example

AVAL varies
i b
by PARAMCD and
d DTYPE
Variable

Where

AVAL

PARAMCD=
PARAMCD
= 'DIABP'
DIABP and
and integer
DTYPE=''
PARAMCD='DIABP'and integer
DTYPE='LOCF'

Predecessor: VS VSSTRESN
Predecessor:VS.VSSTRESN

PARAMCD='DIABP'and integer
DTYPE='MEANP3'

Derivation:VS.VSSTRESNwith
missingvaluesimputedusingthe
lastobservationcarriedforward
method.SeeADRG,page27.
Derivation:VS.VSSTRESNwith
g
p
g
missingvaluesimputedusingthe
meanoflastthreenonmissing
observations.SeeADRG,page28.

AVAL

AVAL

Type

Length/
Length
/ Controlled
Controlled Source/Derivation/Comment
Display Termsor
Format Format

ADaM value-level metadata example

ADT varies
i b
by PARAMCD and
d DTYPE
Variable Where

Type

Length/
/
Display
Format

Controlled
Termsor
Format

ADT

CNSOR=0

date

8ISO8601da.

ADT

CNSOR=1

date

8ISO8601da.

Source/Derivation/Com
/
/
ment
Predecessor:
DM.DTHDTCwhere
DM.DTHFL='Y'
Predecessor:
DM.RFPENDTCwhere
DM.DTHFL=''

Code list metadata is richer

IdentifiescodelistsbasedonCDISC(orother)published
Identifies code lists based on CDISC (or other) published
terminology,indicatesifcodelistisextensibleornot.
DifferentiatesEnumeratedlists(Mild,Moderate,)from
Code/Decode lists (1 Mild 2 Moderate )
Code/Decodelists(1=Mild,2=Moderate,)
IdentifiescontrolledterminologybyCDISCCcode
Indicates if code list is extensible or not
Indicatesifcodelistisextensibleornot
Bettercontroloverorderingofcodelistelements.

Richer Code List Metadata

Example from 1.0

26

Richer Codelist Metadata

Example from 2.0

27

Enhanced functionality comes at a cost

Somethingsthatusedtobeimpossiblearenowpossibleifyou
Some things that used to be impossible are now possible if you
canscroungeupthemetadata.
Somethingsthatusedtobesimplebutinflexiblearenowflexible
but complicated
butcomplicated.
2.0enablesmoreprecisedescriptionofyourdata,butdemands
moredetailstoachieveit.

Thechangesarenotincrementalorbackwardlycompatible.
TheymakeV1Definedocumentationsystemsobsolete.

Notes from the field

Originisdifferent
g
Keyvariablesaredifferent
Newdatatypesincludingpartialandincompletedates/datetimes
MorechoicesforCommentsandMethods.Theyusedtobejust
textstrings.Nowtheyredatastructuresthatcanalsoreference
anexternaldocumentandprovidealocationreference.
Methodsneedtobenamed.Reusablerulesarebest.Methods
canhavecommentstoo.
PagereferencesdontneedDestinationsinthetargetdocument
anymore(e.g.aCRF)

Final Points
Somethingsareeasiersaidthandone.We
Some things are easier said than done. Weve
veshownafewcases
shown a few cases
toillustrateconcepts.Theresmuchmoregoingon.
MigratingfromDefineXMLV1.0isnotatallstraightforward.
Much editing needed even if you map over content (FDA
Mucheditingneededevenifyoumapovercontent.(FDA
reviewerspleasebepatient.)
Whatvaluelevelmetadatashouldwedocument?Metadata
overlapsdata.Needsarigorousstudyofusecases.

Final Points
Muchmoretotheschemathanwe
Much more to the schema than weve
veshownandit
shown and itssdifferent.
different.
Neteffectisasubstantiallynewandmorecomplexxmlstructure
whichmakes1.0systemsobsolete.Wehadtoredesignoursystem
top to bottom
toptobottom.
Enhancedfunctionalityiscompellingandweexpectrapiduptake,
despitethechallengesofimplementation.

Thank you!

JaneDiefenbach:JDiefenbach@PharmaStat.com
JohnBrega:JBrega@PharmaStat.com
LindaCollins:Lcollins@PharmaStat.com
32