fhir-data-evaluator: overview

[juliangruendner]

This project should implement a command line tool in java, which evaluates FHIR data.

It takes a FHIR Measure resource as input, pages the necessary data from a FHIR server and then evaluates the data based on the Measure to finally create a FHIR MeasureReport.

The input Measure should look something like this:

{
    "resourceType": "Measure",
    "id": "fdpg-plus-fhir-evaluator-example-measure",
    "meta": {
        "profile": [
            "http://hl7.org/fhir/StructureDefinition/Measure"
        ]
    },
    "identifier": [
        {
            "system": "https://medizininformatik-initiative.de/fdpg/fhir/Measure",
            "value": "fhirEvaluator/v1"
        }
    ],
    "version": "1.0",
    "status": "active",
    "experimental": false,
    "publisher": "FDPG-Plus",
    "name": "FHIR Evaluator example Measure Input",
    "title": "FHIR Evaluator example Measure Input",
    "description": "This measure defines the set of rule by which to extract information from the FHIR server",
    "date": "2024-02-29",
    "group": [
        {
            "basis": "Condition", 
            "description": "Simple Stratifier concept",
            "population": [
                {
                    "criteria": {
                        "language": "text/x-fhir-query",
                        "expression": "Condition?_profile=https://www.medizininformatik-initiative.de/fhir/core/modul-diagnose/StructureDefinition/Diagnose"
                    }
                }
            ],
            "stratifier": [
                {
                    "criteria": {
                        "language": "text/fhirpath",
                        "expression": "Condition.code.coding.where(system='http://fhir.de/CodeSystem/bfarm/icd-10-gm').first()"
                    }
                }
            ]
        },
        {
            "basis": "Condition",
            "description": "",
            "population": [
                {
                    "criteria": {
                        "language": "text/fhirpath",
                        "expression": "Condition.meta.profile=https://www.medizininformatik-initiative.de/fhir/core/modul-diagnose/StructureDefinition/Diagnose"
                    }
                }
            ],
            "stratifier": [
                {
                    "component": [
                        {
                            "criteria": {
                                "language": "text/fhirpath",
                                "expression": "Condition.code.coding.system(where='http://fhir.de/CodeSystem/bfarm/icd-10-gm')"
                            }
                        },
                        {
                            "criteria": {
                                "language": "text/fhirpath",
                                "expression": "Condition.status"
                            }
                        }
                    ]
                }
            ]
        },
        {
            "basis": "Condition",
            "description": "Simple Stratifier patients by code",
            "population": [
                {
                    "code": {
                        "coding": [
                            {
                                "code": "patient-population"
                            }
                        ]
                    },
                    "criteria": {
                        "language": "text/fhirpath",
                        "expression": "Condition.meta.profile=https://www.medizininformatik-initiative.de/fhir/core/modul-diagnose/StructureDefinition/Diagnose"
                    }
                }
            ],
            "stratifier": [
                {
                    "criteria": {
                        "language": "text/fhirpath",
                        "expression": "Condition.code.coding.system(where='http://fhir.de/CodeSystem/bfarm/icd-10-gm')"
                    }
                }
            ]
        },
        {
            "basis": "Condition",
            "description": "Simple Stratifier patients by code",
            "scoring": {
                "system": "http://terminology.hl7.org/CodeSystem/measure-scoring",
                "code": "continuous-variable"
            },
            "population": [
                {
                    "code": {
                        "system": "http://terminology.hl7.org/CodeSystem/measure-population",
                        "code": "initital-population"
                    },
                    "criteria": {
                        "language": "text/fhirpath",
                        "expression": "Observation.meta.profile=https://www.medizininformatik-initiative.de/fhir/core/modul-diagnose/StructureDefinition/Lab"
                    }
                },
                {
                    "code": {
                        "system": "http://terminology.hl7.org/CodeSystem/measure-population",
                        "code": "measure-population"
                    },
                    "criteria": {
                        "language": "text/fhirpath",
                        "expression": "True"
                    }
                },
                {
                    "code": {
                        "system": "http://terminology.hl7.org/CodeSystem/measure-population",
                        "code": "measure-observation"
                    },
                    "criteria": {
                        "language": "text/fhirpath",
                        "expression": "Observation.value as Quantity"
                    },
                    "aggregateMethod": {
                        "system": "http://hl7.org/fhir/CodeSystem/measure-aggregate-method",
                        "code": "average"
                    }
                }
            ],
            "stratifier": [
                {
                    "criteria": {
                        "language": "text/fhirpath",
                        "expression": "Observation.code.coding.system(where='http://loinc.org')"
                    }
                }
            ]
        }
    ]
}

And the corresponding output MeasureReport could look like this:

{
    "resourceType": "MeasureReport",
    "id": "measurereport-fhir-cds-evaluator-example",
    "contained": [
        {
            "resourceType": "Organization",
            "id": "reporter",
            "name": "Good Health Hospital"
        }
    ],
    "identifier": [
        {
            "value": "measurereport-fhir-cds-evaluator-example"
        }
    ],
    "status": "complete",
    "type": "summary",
    "measure": "link-to-measure",
    "date": "2014-04-01",
    "reporter": {
        "reference": "#fhir-cds-evaluator"
    },
    "period": {
        "start": "1950-01-01",
        "end": "2100-01-01"
    },
    "group": [
        {
            "id": "simple stratifier concept",
            "population": [
                {
                    "code": [
                        {
                            "coding": {
                                "code": "initial-population"
                            }
                        }
                    ],
                    "count": 250
                }
            ],
            "stratifier": [
                {
                    "code": {
                        "text": "stratifier-icd10-codes"
                    },
                    "stratum": [
                        {
                            "valueCodeableConcept": {
                                "coding": [
                                    {
                                        "system": "http://fhir.de/CodeSystem/bfarm/icd-10-gm",
                                        "code": "E13.0"
                                    }
                                ]
                            },
                            "population": [
                                {
                                    "code": {
                                        "coding": [
                                            {
                                                "code": "initial-population"
                                            }
                                        ]
                                    },
                                    "count": 100 //this count wold be the population of Conditions with E13.0
                                }
                            ]
                        },
                        {
                            "valueCodeableConcept": {
                                "system": "http://fhir.de/CodeSystem/bfarm/icd-10-gm",
                                "code": "E13.1"
                            },
                            "population": [
                                {
                                    "code": {
                                        "coding": [
                                            {
                                                "code": "initial-population"
                                            }
                                        ]
                                    },
                                    "count": 150
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "id": "component stratifier icd10 and status",
            "stratifier": [
                {
                    "code": {
                        "text": "stratifier-icd10-codes"
                    },
                    "stratum": [
                        {
                            "component": [
                                {
                                    "code": {
                                        "system": "http://fhir-evaluator/strat/system",
                                        "code": "icd10-code"
                                    },
                                    "valueCodeableConcept": {
                                        "coding": [
                                            {
                                                "system": "http://fhir.de/CodeSystem/bfarm/icd-10-gm",
                                                "code": "E13.0"
                                            }
                                        ]
                                    }
                                },
                                {
                                    "code": {
                                        "system": "http://fhir-evaluator/strat/system",
                                        "code": "status"
                                    },
                                    "valueCodeableConcept": {
                                        "coding": [
                                            {
                                                "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                                                "code": "active"
                                            }
                                        ]
                                    }
                                }
                            ],
                            "population": [
                                {
                                    "code": {
                                        "coding": [
                                            {
                                                "code": "initial-population"
                                            }
                                        ]
                                    },
                                    "count": 100 //this count wold be the population of Conditions with E13.0 with status active
                                }
                            ]
                        },
                        {
                            "component": [
                                {
                                    "code": {
                                        "system": "http://fhir-evaluator/strat/system",
                                        "code": "icd10-code"
                                    },
                                    "valueCodeableConcept": {
                                        "coding": [
                                            {
                                                "system": "http://fhir.de/CodeSystem/bfarm/icd-10-gm",
                                                "code": "E13.0"
                                            }
                                        ]
                                    }
                                },
                                {
                                    "code": {
                                        "system": "http://fhir-evaluator/strat/system",
                                        "code": "status"
                                    },
                                    "valueCodeableConcept": {
                                        "coding": [
                                            {
                                                "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                                                "code": "inactive"
                                            }
                                        ]
                                    }
                                }
                            ],
                            "population": [
                                {
                                    "code": {
                                        "coding": [
                                            {
                                                "code": "initial-population"
                                            }
                                        ]
                                    },
                                    "count": 100 //this count wold be the population of Conditions with E13.0 with status active
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "id": "simple stratifier icd10codes with pat",
            "stratifier": [
                {
                    "code": {
                        "text": "stratifier-icd10-codes-with-pat"
                    },
                    "stratum": [
                        {
                            "valueCodeableConcept": {
                                "coding": [
                                    {
                                        "system": "http://fhir.de/CodeSystem/bfarm/icd-10-gm",
                                        "code": "E13.0"
                                    }
                                ]
                            },
                            "population": [
                                {
                                    "code": {
                                        "coding": [
                                            {
                                                "code": "patient-population"
                                            }
                                        ]
                                    },
                                    "count": 100 //this count wold be the population of Conditions with E13.0
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        {
            "id": "scoring for averages by code",
            "code": {
                "system": "fhir-cds-evaluator-groupd-type",
                "code": "lab-average"
            },
            "stratifier": [
                {
                    "code": {
                        "text": "stratifier-loinc-codes-scoring-averages"
                    },
                    "stratum": [
                        {
                            "valueCodeableConcept": {
                                "coding": [
                                    {
                                        "system": "http://loinc.org",
                                        "code": "718-7"
                                    }
                                ]
                            },
                            "population": [
                                {
                                    "code": {
                                        "system": "http://terminology.hl7.org/CodeSystem/measure-population",
                                        "code": "initital-population"
                                    },
                                    "count": 100
                                },
                                {
                                    "code": {
                                        "system": "http://terminology.hl7.org/CodeSystem/measure-population",
                                        "code": "measure-population"
                                    },
                                    "count": 100
                                    
                                },
                                {
                                    "code": {
                                        "system": "http://terminology.hl7.org/CodeSystem/measure-population",
                                        "code": "measure-observation"
                                    },
                                    "count": 90     // only the ones which acutally have a value Quantity
                                }  
                            ],
                        "measureScoreQuantity": {
                            "value": 13.5,
                            "system": "ucum",
                            "code": "g/dL"
                        }
                        }
                    ]
                }
            ]
        }
    ]
}

Each group of the Measure will result in a group in the MeasureReport.
In a Group, the base population is specified with a fhir search query, that is send to a fhir server. Additional stratifiers can be specified, where again each stratifier in the Measure has one corresponding stratifier result in the MeasureReport.
A stratifier can have either a single criteria field, or multiple compontents which each have a criteria field. In that case, only those resources of the population are considered, that meet the criteria of all components.
Each stratifier of the MeasureReport then contains one stratum result that counts every unique value that is observed in the data that satisfy the stratifier.