VariableDefinition - Evidence Based Medicine on FHIR Implementation Guide v1.0.0-ballot3

Evidence Based Medicine on FHIR Implementation Guide, published by HL7 International / Clinical Decision Support. This guide is not an authorized publication; it is the continuous build for version 1.0.0-ballot3 built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/ebm/ and changes regularly. See the Directory of published versions

Resource Profile: VariableDefinition

Official URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/variable-definition	Version: 1.0.0-ballot3	Highlight text changes?
Standards status: Trial-use	Maturity Level: 1	Computable Name: VariableDefinition
Other Identifiers: OID:2.16.840.1.113883.4.642.40.44.42.121

Profile of EvidenceVariable for Evidence Based Medicine IG. The VariableDefinition Profile uses a CodeableReference Datatype to provide a concept (e.g. coding in a code system) and/or a reference to a Group Resource for structured data to define the variable.

See Understanding the EvidenceVariable Resource for additional information.

Usages:

You can also check for usages in the FHIR IG Statistics

Formal Views of Profile Content

Description Differentials, Snapshots, and other representations.

Key Elements Table
Differential Table
Snapshot Table
Statistics/References
All

Name	Flags	Card.	Type	Description & Constraints Filter: Bindings Constraints Obligations
EvidenceVariable	C	0..*	EvidenceVariable	A definition of an exposure, outcome, or other variable Interfaces Implemented: MetadataResource Constraints: cnl-0
EvidenceVariable.implicitRules	This element is a modifier element. This element is included in summaries.	0..1	uri	A set of rules under which this content was created
EvidenceVariable.contained		0..*	Resource	Contained, inline Resources
EvidenceVariable.Slices for extension				Content/Rules for all slices
EvidenceVariable.Slices for extension.extension:publicationStatus		0..1	CodeableConcept	Publication status URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/artifact-publication-status Binding: Cited Artifact Status Type (preferred)
EvidenceVariable.modifierExtension	This element is a modifier element. This element is included in summaries.	0..*	Extension	Extensions that cannot be ignored Slice: Unordered, Open by value:url
EvidenceVariable.status	This element is a modifier element. This element is included in summaries.	0..1	code	draft \| active \| retired \| unknown Binding: PublicationStatus (required): The lifecycle status of an artifact.
EvidenceVariable.handling		1..1	CodeableConcept	boolean \| continuous \| dichotomous \| ordinal \| polychotomous \| time-to-event \| not-specified Binding: Evidence Variable Handling (extensible)
Documentation for this format

Terminology Bindings

Path	Status	Usage	ValueSet	Version	Source
EvidenceVariable.status	Base	required	PublicationStatus	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.handling	Base	extensible	Evidence Variable Handling	📦2.0.0	THO v7.5

Constraints

Id	Grade	Path(s)	Description	Expression
cnl-0	warning	EvidenceVariable	Name should be usable as an identifier for the module by machine processing applications such as code generation	`name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')`
ele-1	error	ALL elements	All FHIR elements must have a @value or children	`hasValue() or (children().count() > id.count())`

This structure is derived from EvidenceVariable

Name	Card.	Type	Description & Constraints Filter: Bindings Constraints Obligations
EvidenceVariable	0..*	EvidenceVariable	A definition of an exposure, outcome, or other variable Interfaces Implemented: MetadataResource
EvidenceVariable.Slices for extension			Content/Rules for all slices
EvidenceVariable.Slices for extension.extension:publicationStatus	0..1	CodeableConcept	Publication status URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/artifact-publication-status Binding: Cited Artifact Status Type (preferred)
EvidenceVariable.relatesTo
EvidenceVariable.relatesTo.Slices for extension			Content/Rules for all slices
EvidenceVariable.relatesTo.Slices for extension.extension:quotation	0..1	markdown	Quoted portion from related artifact URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/relates-to-with-quotation
EvidenceVariable.relatesTo.Slices for extension.extension:classifier	0..1	CodeableConcept	A classifier of the target artifact in a relatesTo element URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/relatesto-classifier
EvidenceVariable.handling	1..1	CodeableConcept	boolean \| continuous \| dichotomous \| ordinal \| polychotomous \| time-to-event \| not-specified
Documentation for this format

Description & Constraints Filter:

EvidenceVariable

0..*

EvidenceVariable

A definition of an exposure, outcome, or other variable
Interfaces Implemented: MetadataResource
Constraints: cnl-0

0..1

Logical id of this artifact

Terminology Bindings

Path	Status	Usage	ValueSet	Version	Source
EvidenceVariable.language	Base	required	All Languages	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.versionAlgorithm[x]	Base	extensible	Version Algorithm	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.status	Base	required	PublicationStatus	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.relatesTo.type	Base	extensible	Artifact Relationship Type	📦1.0.0	THO v7.5
EvidenceVariable.definition	Base	example	Evidence Variable Definition	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.definitionModifier.code	Base	example	Evidence Variable Definition Modifier Code	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.handling	Base	extensible	Evidence Variable Handling	📦2.0.0	THO v7.5
EvidenceVariable.classifier	Base	example	Evidence Variable Classifier Example	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.dataStorage.datatype	Base	preferred	All FHIR Types	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.constraint.conditional	Base	example	AdministrativeGender	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.constraint.code	Base	example	Evidence Variable Constraint	📦1.0.0	THO v7.5
EvidenceVariable.missingDataMeaning	Base	example	Data Absent Reason	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.unacceptableDataHandling	Base	example	Evidence Variable Unacceptable Data Handling	📦1.0.0	THO v7.5

Constraints

Id	Grade	Path(s)	Description	Expression
cnl-0	warning	EvidenceVariable	Name should be usable as an identifier for the module by machine processing applications such as code generation	`name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')`
cnl-1	warning	EvidenceVariable.url	URL should not contain \| or # - these characters make processing canonical references problematic	`exists() implies matches('^[^\|# ]+$')`
ele-1	error	ALL elements	All FHIR elements must have a @value or children	`hasValue() or (children().count() > id.count())`

This structure is derived from EvidenceVariable

Summary

Mandatory: 1 element

Extensions

This structure refers to these extensions:

Maturity: 1

Key Elements View

Name	Flags	Card.	Type	Description & Constraints Filter: Bindings Constraints Obligations
EvidenceVariable	C	0..*	EvidenceVariable	A definition of an exposure, outcome, or other variable Interfaces Implemented: MetadataResource Constraints: cnl-0
EvidenceVariable.implicitRules	This element is a modifier element. This element is included in summaries.	0..1	uri	A set of rules under which this content was created
EvidenceVariable.contained		0..*	Resource	Contained, inline Resources
EvidenceVariable.Slices for extension				Content/Rules for all slices
EvidenceVariable.Slices for extension.extension:publicationStatus		0..1	CodeableConcept	Publication status URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/artifact-publication-status Binding: Cited Artifact Status Type (preferred)
EvidenceVariable.modifierExtension	This element is a modifier element. This element is included in summaries.	0..*	Extension	Extensions that cannot be ignored Slice: Unordered, Open by value:url
EvidenceVariable.status	This element is a modifier element. This element is included in summaries.	0..1	code	draft \| active \| retired \| unknown Binding: PublicationStatus (required): The lifecycle status of an artifact.
EvidenceVariable.handling		1..1	CodeableConcept	boolean \| continuous \| dichotomous \| ordinal \| polychotomous \| time-to-event \| not-specified Binding: Evidence Variable Handling (extensible)
Documentation for this format

Terminology Bindings

Path	Status	Usage	ValueSet	Version	Source
EvidenceVariable.status	Base	required	PublicationStatus	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.handling	Base	extensible	Evidence Variable Handling	📦2.0.0	THO v7.5

Constraints

Id	Grade	Path(s)	Description	Expression
cnl-0	warning	EvidenceVariable	Name should be usable as an identifier for the module by machine processing applications such as code generation	`name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')`
ele-1	error	ALL elements	All FHIR elements must have a @value or children	`hasValue() or (children().count() > id.count())`

Differential View

This structure is derived from EvidenceVariable

Name	Card.	Type	Description & Constraints Filter: Bindings Constraints Obligations
EvidenceVariable	0..*	EvidenceVariable	A definition of an exposure, outcome, or other variable Interfaces Implemented: MetadataResource
EvidenceVariable.Slices for extension			Content/Rules for all slices
EvidenceVariable.Slices for extension.extension:publicationStatus	0..1	CodeableConcept	Publication status URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/artifact-publication-status Binding: Cited Artifact Status Type (preferred)
EvidenceVariable.relatesTo
EvidenceVariable.relatesTo.Slices for extension			Content/Rules for all slices
EvidenceVariable.relatesTo.Slices for extension.extension:quotation	0..1	markdown	Quoted portion from related artifact URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/relates-to-with-quotation
EvidenceVariable.relatesTo.Slices for extension.extension:classifier	0..1	CodeableConcept	A classifier of the target artifact in a relatesTo element URL: http://hl7.org/fhir/uv/ebm/StructureDefinition/relatesto-classifier
EvidenceVariable.handling	1..1	CodeableConcept	boolean \| continuous \| dichotomous \| ordinal \| polychotomous \| time-to-event \| not-specified
Documentation for this format

Snapshot ViewView

Description & Constraints Filter:

EvidenceVariable

0..*

EvidenceVariable

A definition of an exposure, outcome, or other variable
Interfaces Implemented: MetadataResource
Constraints: cnl-0

0..1

Logical id of this artifact

Terminology Bindings

Path	Status	Usage	ValueSet	Version	Source
EvidenceVariable.language	Base	required	All Languages	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.versionAlgorithm[x]	Base	extensible	Version Algorithm	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.status	Base	required	PublicationStatus	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.relatesTo.type	Base	extensible	Artifact Relationship Type	📦1.0.0	THO v7.5
EvidenceVariable.definition	Base	example	Evidence Variable Definition	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.definitionModifier.code	Base	example	Evidence Variable Definition Modifier Code	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.handling	Base	extensible	Evidence Variable Handling	📦2.0.0	THO v7.5
EvidenceVariable.classifier	Base	example	Evidence Variable Classifier Example	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.dataStorage.datatype	Base	preferred	All FHIR Types	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.constraint.conditional	Base	example	AdministrativeGender	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.constraint.code	Base	example	Evidence Variable Constraint	📦1.0.0	THO v7.5
EvidenceVariable.missingDataMeaning	Base	example	Data Absent Reason	📍6.0.0-snapshot1	FHIR Std.
EvidenceVariable.unacceptableDataHandling	Base	example	Evidence Variable Unacceptable Data Handling	📦1.0.0	THO v7.5

Constraints

Id	Grade	Path(s)	Description	Expression
cnl-0	warning	EvidenceVariable	Name should be usable as an identifier for the module by machine processing applications such as code generation	`name.exists() implies name.matches('^[A-Z]([A-Za-z0-9_]){1,254}$')`
cnl-1	warning	EvidenceVariable.url	URL should not contain \| or # - these characters make processing canonical references problematic	`exists() implies matches('^[^\|# ]+$')`
ele-1	error	ALL elements	All FHIR elements must have a @value or children	`hasValue() or (children().count() > id.count())`

This structure is derived from EvidenceVariable

Summary

Mandatory: 1 element

Extensions

This structure refers to these extensions:

Maturity: 1

Other representations of profile: CSV, Excel, Schematron

Notes:

See Understanding the EvidenceVariable Resource for additional information.

Examples from the QUARTET USA trial will be described here and can be viewed at Medication Adherence at 12 weeks and Adverse event free and hypertension control at 12 weeks .

These 2 VariableDefinition examples are outcome measures that were used in the QUARTET USA trial.

The concepts needed to describe the outcome measure of ‘Medication Adherence at 12 weeks’ include:

The definition of the outcome is coded with a term that means ‘medication adherence’
The definition of ‘medication adherence’ is modified in this instance to more explicitly require > 80% adherence to be met.
The variable will be handled as either met or not met when recording the data.
The timing of this variable reflects 12 weeks from the start of the trial.

We start by creating a FHIR EvidenceVariable Resource with a VariableDefinition Profile. Because the definition is expressed with a codeable concept, this example uses EvidenceVariable.definition.concept as follows:

"definition": {
  "concept": {
        "coding": [
            {
                "system": "http://snomed.info/sct",
                "code": "1156699004",
                "display": "Complies with drug therapy (finding)"
            }
        ],
        "text": "Medication Adherence defined as 80% or greater use measured by pill count"
    }
}

The explicit definition of “80% or greater use measured by pill count”, though shared in EvidenceVariable.definition.concept.text, is not machine-interpretable, so this can be expressed with an EvidenceVariable.definitionModifier element:

"definitionModifier": [
    {
      "code": {
              “coding": [
                  {
                      "system": "http://snomed.info/sct",
                      "code": "266710000",
                      "display": "Drugs not taken/completed"
                  }
              ],
              "text": "measured by pill count"
          },
      "valueQuantity": {
              "comparator": "<=",
              "value": 20,
              "unit": "%",
              "system": "http://unitsofmeasure.org",
              "code": "%"
        }
    }
  ]

The variable will be handled as either met or not met when recording the data, so this is coded as a boolean variable in the EvidenceVariable.handling element:

"handling": {
  "coding": [
    {
      "system": "https://fevir.net/sevco",
      "code": "STATO:0000724",
      "display": "boolean variable"
    }
  ]
}

In prior versions of FHIR, the EvidenceVariable.handling element used a code datatype instead of a CodeableConcept datatype so looked like:

"handling": "boolean"

The timing of this variable reflects 12 weeks from the start of the trial, so this is expressed in the EvidenceVariable.timing element:

"timing": {
  "contextCode": {
    "coding": [
      {
        "system": "http://snomed.info/sct",
        "code": "709491003",
        "display": "Enrollment in clinical trial (procedure)"
      }
    ]
  },
  "offsetDuration": {
    "value": 12,
    "unit": "weeks",
    "system": "http://unitsofmeasure.org",
    "code": "wk"
  },
  "text": "at 12 weeks"
}

The outcome measure of ‘Adverse event free and hypertension control at 12 weeks’ introduces an outcome for which the EvidenceVariable.definition.concept (defining the variable with a CodeableConcept) and EvidenceVariable.definitionModifier are not sufficient to express the definition in structured form. The definition of this outcome is a combination of 2 characteristics (free from adverse events AND hypertension control), and the structure to support a combination of characteristics is found in the Group Resource. We therefore define this variable with a reference to a Group Resource using a ConceptualCohortDefinition Profile.

The corresponding JSON for the EvidenceVariable.definition element is:

"definition": {
    "reference": {
          "reference": "Group/375279",
          "type": "Group",
          "display": "Adverse event free and hypertension control"
    }
  }