Questionnaire authoring and possible extraction types

[ekigamba]

Sample Questionnaires

Purpose	Extracted Resources	Extraction method	Reasons for extraction-method
1. Register an OPD patient and their emergency/immediate contact	- Patient	Definition-based	Extraction to a single resource
2. Register vaccinations given	- Encounter - +1 Immunization - Each Immunization referencing the Encounter	- StructureMap-based - Definition-based (Encounter generated before)	Extraction to multiple resources requiring ID references between them
3. Register a pregnancy outcome where we can have multiple births and collect birth observations(eg. weight)	- Encounter - +1 Patient - +1 Observation ??	??
4. Child U5 registration - Register child with birth weight, birth height, mother details, doses of TdV & mother's HIV status	- Patient (child) - Observation (birth height) - Observation (birth weight) - RelatedPerson (Mother details with Patient reference to child) - Patient (mother) - Mother observations	- StructureMap-based	- Extraction to multiple resource - Multiple resources of similar type - References between patient and observation resources - https://www.hl7.org/fhir/patient.html#maternity
5. ANC registration	- Patient	Definition-based	Extraction to a single resource
6. Maternity registration	- Patient - OccupationData	- Definition-based	- Extraction of a single resource with extension on occupation - Extraction of 2 resources with a one resource having a reference to the other resource

Extraction types

1. Definition-based extraction

• Can handle extraction to multiple Resources eg. Patient and Observation
• Can handle direct mapping to Resources
• Cannot handle a lot of misalignment in the Questionnaire eg. related questions need to be in the same group question - This is because definition-based only allows the author to define the definition property which helps map the question to the Resource property/element. If misalignment occurs, the processor does not easily handle ambiguity and the method does not allow defining enough details for easier mapping.
• Does not allow transformations on answers

2. Structure-map based extraction

• Explicit mappings for every property
• Uses the FHIR mapping language, can be very complex but flexible, it is a transform language
• Use the questionnaire-targetStructureMap extension on the questionnaire
• Reuse of structure maps inside other structure maps
• This requires expertise on the FHIR Mapping language
• Enables transformations of data and conditional processing
• Allows use of FHIR path expressions for conversions and conditional statements. An example can be found below

Examples of structure maps

1. An example of a structure map used to map QuestionnaireResponse to Patient using FHIR Path expression

map "http://hl7.org/fhir/StructureMap/tutorial" = 'tutorial'
      
uses "http://hl7.org/fhir/StructureDefinition/QuestionnaireReponse" as source
uses "http://hl7.org/fhir/StructureDefinition/Patient" as target

group tutorial(source src : TLeft, target tgt : TRight) {
	src.item as item where(linkId = 'PR') -> tgt.birthDate = evaluate(item, $this.item.where(linkId = 'patient-0-birth-date').answer.valueDate.value) "rule_a";
}

2. An example of a structure map used to map QuestionnaireResponse to Patient using when.. then.. FHIR mapping language constructs

map "http://hl7.org/fhir/StructureMap/tutorial" = 'tutorial'
      
uses "http://hl7.org/fhir/StructureDefinition/QuestionnaireReponse" as source
uses "http://hl7.org/fhir/StructureDefinition/Patient" as target

group tutorial(source src : TLeft, target tgt : TRight) {
	 src.item as item where(linkId = 'PR') then {
		 item.item as inner_item where (linkId = 'patient-0-birth-date') then {
			 inner_item.answer first as ans then { 
				 ans.value as val -> tgt.birthDate = val "rule_a";
			 } ;
		 } ;
	 } ;
}

3. An example of a structure map used to map a FakeInpatientDrugChart to a Patient, Observation and MedicationRequest

/// version = 0.1
/// title = "FHIR Mapper Tutorial : FakeInpatientDrugChart"
/// status = draft
/// contact = "Firely"

/*
  The following FHIR Mapping Language file demonstrates the currently supported features of the FHIR Mapper
    (Firely's implementation of the FHIR Mapping Language).
  To learn more about the FHIR Mapper, see http://docs.simplifier.net/mappingengine/index.html

  This is a pretty extensive example - feel free to refer to it when writing your own maps!

  Maps are monodirectional: in this case we map from a logical model to FHIR resources.
  
  Latest version of this map lives on https://simplifier.net/fhirmapper/fhirmappertutorial
*/

map "http://vonk.fire.ly/fhir/StructureMap/FHIRMapperTutorial" = FHIRMapperTutorial

uses "http://hl7.org/fhir/StructureDefinition/FakeInpatientDrugChart" as source
uses "http://hl7.org/fhir/StructureDefinition/Patient" as target
uses "http://hl7.org/fhir/StructureDefinition/Observation" as target
uses "http://hl7.org/fhir/StructureDefinition/MedicationRequest" as target

group MapFakeInpatientDrugChart(source src: FakeInpatientDrugChart, target bundle: Bundle)
{
  src -> bundle.id = uuid();
  src -> bundle.type = 'collection';
  src -> bundle.entry as entry, entry.resource = create('Patient') as patient then
    TransformPatient(src, patient), TransformPatientPostHandler(src, patient, bundle);
}

group TransformPatient(source src : FakeInpatientDrugChart, target patient: Patient)
{
  src -> patient.id = uuid();
  src.mpi as mpi -> patient.identifier =
    id('http://vonk.fire.ly/fhir/CodeSystem/mpi', mpi) as identifier, identifier.use = 'official';
  src.patientName as patientName -> patient.name as humanName, humanName.text = patientName;
  src.dateOfBirth as dateOfBirth -> patient.birthDate = dateOp(dateOfBirth);

  src.contact as contact, contact.address as sourceAddress -> patient.address as targetAddress collate,
    targetAddress.line = sourceAddress;
  src.contact as contact, contact.email as email -> patient.telecom as telecom,
    telecom.system = 'email', telecom.value = email;
  src.contact as contact, contact.telephone as telephone -> patient.telecom as telecom,
    telecom.system = 'phone', telecom.value = telephone;

  src.guardian as guardian -> patient.contact = create('BackboneElement') as contact then
  {
    guardian.name as name -> contact.relationship =
      cc('http://terminology.hl7.org/CodeSystem/v2-0131', 'C', 'Emergency Contact'),
      contact.name as humanName, humanName.text = name;

    guardian.email as email -> contact.telecom as telecom,
      telecom.system = 'email', telecom.value = email;

    guardian.telephone as telephone -> contact.telecom as telecom,
      telecom.system = 'phone', telecom.value = telephone;
  };

  src.gender as gender -> patient.gender =
    translate(gender, 'http://vonk.fire.ly/fhir/ConceptMap/MyFakePatientGender', 'code');
}

group TransformPatientPostHandler(source src: FakeInpatientDrugChart, source patient: Patient,
  target bundle: Bundle) {

  src where "weight.exists()" -> bundle.entry as entry,
            entry.resource = create('Observation') as observation
            then TransformObservationWeight(src, patient, observation);

  src where "height.exists()" -> bundle.entry as entry,
         entry.resource = create('Observation') as observation
         then TransformObservationHeight(src, patient, observation);

  src where "pregnant.exists()" -> bundle.entry as entry,
         entry.resource = create('Observation') as observation
         then TransformObservationPregnancy(src, patient, observation);

  src.prescribedDrug as prescription -> bundle.entry as entry,
         entry.resource = create('MedicationRequest') as medicationrequest
         then TransformPrescription(prescription, patient, medicationrequest);

  src.drugSensitivity as sensitivity -> bundle.entry as entry,
         entry.resource = create('AllergyIntolerance') as allergyintolerance
         then TransformAllergyIntolerance(sensitivity, patient, allergyintolerance);
}

group TransformObservationWeight(source src: FakeInpatientDrugChart, source patient: Patient,
  target observation: Observation)
{
    src -> observation.id = uuid();
    src -> observation.status = 'final';
    src -> observation.category = cc('http://hl7.org/fhir/observation-category', 'vital-signs', 'Vital Signs');
    src -> observation.code = cc('http://loinc.org', '29463-7', 'Body weight');

    src.weight as weight -> observation.value = create('Quantity') as value collate, value.value = weight;
    src -> observation.value as value collate, value.unit = 'kg';
    src -> observation.value as value collate, value.code = 'kg';
    src -> observation.value as value collate, value.system = 'http://unitsofmeasure.org';

    patient.id as patientId log "$this" -> observation.subject = create('Reference') as subject,
      subject.reference = evaluate(patientId, '\'Patient/\' + $this');
}

group TransformObservationHeight(source src: FakeInpatientDrugChart, source patient: Patient,
  target observation: Observation)
{
    src -> observation.id = uuid();
    src -> observation.status = 'final';
    src -> observation.category = cc('http://hl7.org/fhir/observation-category', 'vital-signs', 'Vital Signs');
    src -> observation.code = cc('http://loinc.org', '8302-2', 'Body height');

    src.height as height -> observation.value = create('Quantity') as value collate, value.value = height;
    src -> observation.value as value collate, value.unit = 'cm';
    src -> observation.value as value collate, value.code = 'cm';
    src -> observation.value as value collate, value.system = 'http://unitsofmeasure.org';

    patient.id as patientId -> observation.subject = create('Reference') as subject,
      subject.reference = evaluate(patientId, '\'Patient/\' + $this');
}

group TransformObservationPregnancy(source src: FakeInpatientDrugChart, source patient: Patient,
  target observation: Observation)
{
    src -> observation.id = uuid();
    src -> observation.status = 'final';
    src -> observation.category = cc('http://hl7.org/fhir/observation-category', 'vital-signs', 'Vital Signs');
    src -> observation.code = cc('http://loinc.org', '11449-6', 'Pregnancy status');

    src.pregnant as pregnant where "$this.gender = f" -> observation.value;

    patient.id as patientId -> observation.subject = create('Reference') as subject,
      subject.reference = evaluate(patientId, '\'Patient/\' + $this');
}

group TransformPrescription(source prescription, source patient: Patient,
  target medicationrequest: MedicationRequest)
{
  prescription -> medicationrequest.id = uuid();
  prescription -> medicationrequest.intent = 'order';

  patient.id as patientId -> medicationrequest.subject = create('Reference') as subject,
    subject.reference = evaluate(patientId, '\'Patient/\' + $this');

  prescription.drug as drug -> medicationrequest.medicationCodeableConcept = cc(drug);
  prescription.dose as dose -> medicationrequest.dosageInstruction = create('Dosage') as dosage,
    dosage.text = dose;
  prescription.route as route -> medicationrequest.dosageInstruction as di,
    di.route = create('CodeableConcept') as cc, cc.text = route; // we can't trust it to be actually coded
}

group TransformAllergyIntolerance(source sensitivity, source patient: Patient,
  target allergyintolerance: AllergyIntolerance)
{
  sensitivity -> allergyintolerance.id = uuid();
  sensitivity -> allergyintolerance.clinicalStatus = 'active';
  sensitivity -> allergyintolerance.verificationStatus = 'confirmed';

  patient.id as patientId -> allergyintolerance.patient = create('Reference') as patient,
    patient.reference = evaluate(patientId, '\'Patient/\' + $this');

  sensitivity.drugOrSubstance as dos -> allergyintolerance.code = cc(dos);
  sensitivity.reaction -> allergyintolerance.reaction = create('BackboneElement') as reaction then {
    sensitivity.reaction as reactiontext -> reaction.manifestation = cc(reactiontext);
    sensitivity.dateRecorded as date -> reaction.onset = date;
  };
}

How to run extraction using StructureMap based extraction for R4

• Run the following code in a project with a dependency on the HL7 FHIR Core

// Initialize package manager cache to save packages on user home
FilesystemPackageCacheManager pcm = new FilesystemPackageCacheManager(true, ToolsVersion.TOOLS_VERSION);

// Package name manually checked from https://simplifier.net/packages?Text=hl7.fhir.core&fhirVersion=All+FHIR+Versions
// Create R4 context
SimpleWorkerContext contextR4 = SimpleWorkerContext.fromPackage(pcm.loadPackage("hl7.fhir.r4.core", "4.0.1"));
contextR4.setCanRunWithoutTerminology(true);

// Create an instance of StructureMapUtilities to use R4 context
org.hl7.fhir.r4.utils.StructureMapUtilities structureMapUtilities = new StructureMapUtilities(contextR4);

// Deserialize structuremap string
StructureMap map = structureMapUtilities.parse("{your-strucure-map-here}", "FHIRMapperTutorial");

// Generate empty target resource object
Resource targetResource = ResourceFactory.createResource(scu.getTargetType(map).getName());

// Deserialize source JSON
org.hl7.fhir.r4.elementmodel.Element baseElement = new JsonParser(contextR4)
  .parse(new ByteArrayInputStream(("{your-source-resource-json}").getBytes(StandardCharsets.UTF_8)));

// Perform extraction to targetResource
structureMapUtilities.transform(contextR4,  baseElement, map, targetResource);

• Make sure you have an internet connection for the first run. The library installs the FHIR Core package ,containing structure definitions, from the internet
• Replace your StructureMap here {your-strucure-map-here}
• Replace your FHIR Resource JSON here {your-source-resource-json}

3. Observation-based extraction

This method only work for extracting QuestionnaireResponse to an Observation

References

• StructureMap-based extraction
• FHIR Mapping language
• FHIR Mapping tutorial
• https://simplifier.net/fhirmapper/FakeInpatientDrugChart/~json
• http://clinfhir.com/mapping.html - Not working

[ekigamba]

Definition-based extraction returning multiple resources (WIP)

Scoping

1. Return type should be Bundle of type transaction - According to https://chat.fhir.org/#narrow/stream/179255-questionnaire/topic/SDC.20Extraction.20examples/near/232344943
2. The Extraction process will always return a Bundle - According to this update on FHIR spec
3. The questionnaire-itemExtractionContext extension will be used to shift context between Resource types
4. There can be only one Resource per Resource type for definition-based extraction
5. Only one context can be in play at the same time.

An example of a Questionnaire used to extract multiple Resources

{
  "resourceType": "Questionnaire",
  "id": "basic-child-registration",
  "title": "Child Registration",
  "status": "active",
  "date": "2021-05-25T13:05:47.111Z",
  "subjectType": [
    "Patient",
    "Observation"
  ],
  "item": [
    {
      "linkId": "PR",
      "type": "group",
      "item": [
        {
          "linkId": "PR-name",
          "type": "group",
          "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.name",
          "item": [
            {
              "linkId": "PR-name-text",
              "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.name.given",
              "type": "string",
              "text": "First Name"
            },
            {
              "linkId": "PR-name-family",
              "definition": "http://hl7.org/fhir/StructureDefinition/datatypes#Patient.name.family",
              "type": "string",
              "text": "Family Name"
            }
          ]
        },
        {
          "linkId": "patient-0-birth-date",
          "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.birthDate",
          "type": "date",
          "text": "Date of Birth"
        },
        {
          "linkId": "patient-0-gender",
          "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.gender",
          "type": "choice",
          "text": "Gender:",
          "answerOption": [
            {
              "valueCoding": {
                "code": "female",
                "display": "Female"
              },
              "initialSelected": true
            },
            {
              "valueCoding": {
                "code": "male",
                "display": "Male"
              }
            },
            {
              "valueCoding": {
                "code": "other",
                "display": "Other"
              }
            },
            {
              "valueCoding": {
                "code": "unknown",
                "display": "Unknown"
              }
            }
          ],
          "extension": [
            {
              "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-itemControl",
              "valueCodeableConcept": {
                "coding": [
                  {
                    "system": "http://hl7.org/fhir/questionnaire-item-control",
                    "code": "radio-button",
                    "display": "Radio Button"
                  }
                ],
                "text": "A control where choices are listed with a button beside them. The button can be toggled to select or de-select a given choice. Selecting one item deselects all others."
              }
            }
          ]
        },
        {
          "linkId": "PR-contact-party",
          "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.contact",
          "type": "group",
          "item": [
            {
              "linkId": "PR-contact-party-name",
              "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.contact.name",
              "type": "group",
              "item": [
                {
                  "linkId": "PR-contact-party-name-given",
                  "definition": "http://hl7.org/fhir/StructureDefinition/Patient#Patient.contact.name.given",
                  "type": "string",
                  "text": "Guardian First Name"
                },
                {
                  "linkId": "PR-contact-party-name-family",
                  "definition": "http://hl7.org/fhir/StructureDefinition/datatypes#Patient.contact.name.family",
                  "type": "string",
                  "text": "Guardian Last Name"
                }
              ]
            }
          ]
        }
      ],
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-itemExtractionContext",
          "valueExpression": {
            "language": "application/x-fhir-query",
            "expression": "Patient",
            "name": "patient"
          }
        }
      ]
    },
    {
      "link": "Obs",
      "type": "group",
      "extension": [
        {
          "url": "http://hl7.org/fhir/uv/sdc/StructureDefinition/sdc-questionnaire-itemExtractionContext",
          "valueExpression": {
            "language": "application/x-fhir-query",
            "expression": "Observation",
            "name": "observation"
          }
        }
      ],
      "item": [
        {
          "linkId": "Obs-birth-weight",
          "type": "group",
          "definition": "http://hl7.org/fhir/StructureDefinition/Observation#valueQuantity",
          "item": [
            {
              "linkId": "Obs-birth-weight-value",
              "type": "decimal",
              "text": "Birth weight (Kgs)",
              "definition": "http://hl7.org/fhir/StructureDefinition/Observation#valueQuantity#value"
            },
            {
              "linkId": "Obs-birth-weight-unit",
              "type": "string",
              "definition": "http://hl7.org/fhir/StructureDefinition/Observation#valueQuantity#unit",
              "initial": {
                "valueString": "Kg"
              },
              "extension": [
                {
                  "url": "http://hl7.org/fhir/StructureDefinition/questionnaire-hidden",
                  "valueBoolean": true
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

[ekigamba]

StructureMap-based extraction returning multiple resources

Scoping

1. Change the ResourceMapper#extraction return type to Bundle
2. Move definition based extraction functionality to a different function
3. Add structuremap-based extraction functionality on a different function
4. Both extraction functions should return a Bundle
5. StructureMap-based extraction should only be used if there is a questionnaire-targetStructureMap extension on the Questionnaire root
6. Fetch the StructureMap from the DB so that it can be invoked against the QuestionnaireResponse - The url of the StructureMap is retrieved from the extension's valueCanonical
7. Return the result