Simple HIV (for testing only)

Getting started with cqf-ruler

These instructions are temporary until feature-stratification are merged into main branch and a Publisher bug fix is released which prevents errors. Approach:

Use an XML IG and not the Sushi, including includes/menu.xml not Sushi
Comment out input/cql binary stuff in XML
FSHOnly - true in sushi
mv libraries or publisher errors with duplicate resources

git clone git@github.com:DBCG/cqf-ruler.git
cd cqf-ruler/
git checkout feature-stratification
# mvn jetty:run -am --projects cqf-ruler-r4
mvn package
docker build -t cqf .
docker run -p "8080:8080" cqf

# if making changes to the cql/measures, may have to delete database on each iteration
rm -rf target

Prep repo:

git@github.com:citizenrich/simple-hiv-ig.git
cd simple-hiv-ig
bash _updateCQFTooling.sh
bash _updatePublisher.sh

Steps:

rm -rf input/resources/Library-* input/resources/library-*
sushi
mv fsh-generated/resources/Library-* input/resources/
bash _refresh.sh
bash _genonce.sh -no-sushi

Load FHIR-ModelInfo just in case

curl -X PUT -H "Content-Type: application/fhir+json" --data @Library-FHIR-ModelInfo.json http://localhost:8080/cqf-ruler-r4/fhir/Library/FHIR-ModelInfo | jq .

cd output ; for FILE in OpenCR OpenHIE \
; do curl -X PUT -H "Content-Type: application/fhir+json" --data @CodeSystem-${FILE}.json http://localhost:8080/cqf-ruler-r4/fhir/CodeSystem/${FILE} | jq . ; done ; cd ../

cd output ; for FILE in FHIRHelpers FHIRCommon AgeRanges KitchenSink GoldenRecord Blaze \
; do curl -X PUT -H "Content-Type: application/fhir+json" --data @Library-${FILE}.json http://localhost:8080/cqf-ruler-r4/fhir/Library/${FILE} | jq . ; done ; cd ../

cd output ; for FILE in BlazeAgeGroupLocation BlazeGenderLocation BlazeStratifierTest BlazeStratifierAgeGroup \
JustGender JustAgeGroup JustLocation AgeGroupGender AgeGroupGenderLocation Cohort SuppData \
; do curl -X PUT -H "Content-Type: application/fhir+json" --data @Measure-${FILE}.json http://localhost:8080/cqf-ruler-r4/fhir/Measure/${FILE} | jq . ; done ; cd ..

cat output/Bundle-Example-HIVSimple.json | curl -X POST -H "Content-Type: application/fhir+json" --data-binary @- http://localhost:8080/cqf-ruler-r4/fhir | jq .
cat output/Bundle-Example-HIVSimple2.json | curl -X POST -H "Content-Type: application/fhir+json" --data-binary @- http://localhost:8080/cqf-ruler-r4/fhir | jq .

# set fhir server base as necessary
export FHIR="http://localhost:8080/cqf-ruler-r4/fhir"
curl $FHIR'/Measure/JustGender/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/JustAgeGroup/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/JustLocation/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/AgeGroupGender/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/AgeGroupGenderLocation/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/Cohort/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/SuppData/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/BlazeStratifierAgeGroup/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/BlazeAgeGroupLocation/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/BlazeGenderLocation/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .
curl $FHIR'/Measure/BlazeStratifierTest/$evaluate-measure?periodStart=2021&periodEnd=2021' | jq .

Authoring

Implementation Guides are the FHIR community's supported approach to authorship, creation of Library and Measure resources, versioning. The Atom editor and package for CQL are recommended for iterating on CQL.

Install the Atom editor and Atom CQL language package.
To test that your setup is working, clone this repo, open a CQL file then make sure you have focus on the CQL file. Then right-click and at the bottom will be the CQL menu to Execute CQL. This will bring up a results window as it processes tests.

The folder structure must be set up accordingly (from Atom CQL language package):

input/cql
input/tests
input/tests/<cql-library-name>
input/tests/<cql-library-name>/<patient-id>
input/tests/<cql-library-name>/<patient-id>/<resource-type-name>/<resource files> // flexible structure
input/vocabulary/codesystem
input/vocabulary/valueset

Observe the above or there will be issues.

For example:

The CQL files are all under input/cql
Library and Measure templates are under input/resources. They must be named and fields match the CQL files.
The _genonce script in Publisher will convert those template Library and Measure resources into full resources that can be PUT on a FHIR server.
Tests must have the resource.id of the resource as a folder name. Thus, there is a separate folder for each Patient bundle.
The Patient bundles inside the folder can actually be named anything, but they are named here by resource.id.

Patient bundles for tests do not have to be complex (these were generated by a custom Synthea module), but they must have the codesystems required in the CQL. It is important to determine codesystems in advance to author CQL or create temp ones while doing authorship.

There must be an input/vocabulary/valueset folder even if it is empty.

$ cd input/
~/src/github.com/intrahealth/simple-hiv-ig/input
$ tree
.
├── cql
│   ├── AgeRanges.cql
│   ├── FHIRCommon.cql
│   ├── HIVSimpleAgeGroup.cql
│   └── cql-options.json
...
├── resources
│   ├── library-AgeRanges.json
│   ├── library-FHIRCommon.json
│   ├── library-HIVSimpleAgeGroup.json
...
├── tests
│   ├── HIVSimpleAgeGroup
│   │   ├── 0695de04-1a5d-e2c0-3e4f-79121465ba67
│   │   │   └── 0695de04-1a5d-e2c0-3e4f-79121465ba67.json
│   │   ├── 0ae954fa-eff8-0d38-c840-3af401abc9fd
│   │   │   └── 0ae954fa-eff8-0d38-c840-3af401abc9fd.json
...
└── vocabulary
    └── valueset

Some hints on authorship from recent workshops:

Double quotes are for identifiers and single quotes represent string literals, for example, "female" should be 'female'.
Check for odd copy/paste errors in quotes.
Required libraries: include FHIRHelpers version '4.0.1' Use of FHIRHelpers is implicit in the translator, based on the modelinfo file with FHIR. This must be included in the boilerplate of any CQL that processes FHIR.

Measure options and examples

The $evaluate-measure operation runs

// parameter "Measurement Period" Interval<DateTime> default Interval[@2020-01-01T, @2020-12-31T]
parameter "Measurement Period" Interval<DateTime>

measure-scoring

// options: proportion | ratio | continuous-variable | cohort

scoring = $measure-scoring#proportion

$measure-scoring#cohort

A proportion Measure requires at least Initial Population, Denominator, and Numerator.

// * type.coding.code = #process <- this is not used in calculations

// "The reportType %s is invalid. Please use one of ."

report-type

$evaluate-measure

subject, subject-list or population
population is the default.
subject-list must be a POST. subject-list gives a List resource of the Patients that meet the criteria, no further details, e.g.

"entry": [
  {
    "item": {
      "reference": "Patient/C6Z3TMVKRCH2O6VX"
    }
  },
  {
    "item": {
      "reference": "Patient/C6Z44QYHMQ7AGD2M"
    }
  },
  {
    "item": {
      "reference": "Patient/C6Z4GYJYLPR6FCST"
    }
  },
  {
    "item": {
      "reference": "Patient/C6Z4H2E5VIJ7BPCU"
    }
  },
  {
    "item": {
      "reference": "Patient/C6Z4KP3RDJHDYCCR"
    }
  }
]

citizenrich / simple-hiv-ig