Human readable pretty statement results for FHIR

[lmd59]

Summary

Previously, statement results for FHIR would default to json-like appearances for objects. They now show the most relevant fields for FHIR objects and use mappings to identify more useful information and labels (such as displays for code systems and relevant path properties).

New behavior

Statement results have improved pretty field for results that are objects or codes

Code changes

• Adds parse-code-systems script to package.json, which uses the parseCodeSystems.ts script to create the code system URL to pretty code system mapping. This leverages the files in the code-systems folder as input and output to go from the cts-metadata file to the easily consumable system-map file.
• Adds code-attributes/codePaths.ts taken from fqm-testify for easy identification of primary code path
• Updates to ClauseResultBuilder.ts
  • Pulls in all valuable mappings
  • Updates the prettyResult function to more flexibly show type information, show a prettier version of the code system using the system-map, show array elements as singular if there isn't more than one, remove unused QDM logic, and handle FHIR objectlogic
  • Updates FHIR object logic to handle tuples without QDM logic and calls prettyFHIRObject for base FHIRObjects
  • Adds prettyFHIRObject to work with FHIRObjects that come from the calculation results to identify the resource type and component pieces in a human readable (similar to Bonnie) format
• Updates integration testing to add proportion-Encounter-tuple for tuple testing and makes sure other integration results (as in ratio-Encounter-reuseObservationFunction) have pretty results
• Updates unit tests to make sure codes and code systems are better displayed.

Testing guidance

• npm run check
• npm run test:integration

Play around with different calculations with interesting FHIR results. Some examples are included in the integration tests:

• npm run cli -- -p "test/integration/proportion-Encounter-tuple/patients/patient-2Enc-1day-3day.json" -m "test/integration/proportion-Encounter-tuple/proportion-Encounter-tuple-bundle.json" -o --debug -s 2022-01-01 -e 2022-12-31 creates tuple outputs (look for "Enc with Durations" in the statement results), which you can compare to Bonnie tuple outputs (some differences exist in how intervals are rendered):

• npm run cli -- -p "test/integration/ratio-Encounter-reuseObservationFunction/patients/patient-3enc-1in-all-2in-denom.json" -m "test/integration/ratio-Encounter-reuseObservationFunction/ratio-Encounter-reuseObservationFunction-bundle.json" -o --debug -s 2022-01-01 -e 2022-12-31 creates results with multiple FHIRObjects (look for the "denom" statement) or results with a single FHIR object (look for the "numer" statement). This could be compared with a simple FHIR object in Bonnie:

• You can also play with other measures that have object results for statements. For instance ecqm-content-r4-2021/bundles/measure/CervicalCancerScreeningFHIR/CervicalCancerScreeningFHIR-bundle.json may have an encounter result for the statement Qualifying Encounters or an observation result for the statement Cervical Cytology Within 3 Years. As a note, this measure uses outdated gender administration code system URLs, so the human-readable code system lookup does not work (and the URL is shown instead).

[github-actions[bot]]

Coverage report

St.:grey_question:	Category	Percentage	Covered / Total
🟢	Statements	85.95% (-0.37% 🔻)	2307/2684
🟡	Branches	72.97% (-2.55% 🔻)	2122/2908
🟢	Functions	89.1% (-0.33% 🔻)	425/477
🟢	Lines	86.28% (-0.36% 🔻)	2227/2581

Show new covered files 🐣

|

St.^{:grey_question:}

| File | Statements | Branches | Functions | Lines | | :----------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------- | :--------- | :------- | :-------- | :---- | | 🟢 |

`...` / system-map.ts

| 100% | 100% | 100% | 100% | | 🟢 |

`...` / codePaths.ts

| 100% | 100% | 100% | 100% |

Show files with reduced coverage 🔻

|

St.^{:grey_question:}

| File | Statements | Branches | Functions | Lines | | :----------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :-------------------------------------------------------------- | :------------------------------------------------------------ | :------------------------------------------------------------- | | 🟡 |

`...` / ClauseResultsBuilder.ts

|

74.32% (-1.39% 🔻)

|

49.75% (-14.78% 🔻)

|

87.8% (-4.09% 🔻)

|

74.17% (-1.15% 🔻)

|

Test suite run success

431 tests passing in 31 suites.

Report generated by 🧪jest coverage report action from 9d411923f75d3c634d6c90d47842477f1e392295

[mgramigna]

This fails when running with an old connectathon bundle:

In this case, resourceType is actually Coding. Are we assuming that we always have a FHIR resource by the time we access the primaryCodePath? Or is this just identifying an edge-case that we aren't handling?

EDIT: This also happens with the ColorectalCancerScreeningsFHIR bundle in ecqm-content-r4-2021:

[lmd59]

This fails when running with an old connectathon bundle:

In this case, resourceType is actually Coding. Are we assuming that we always have a FHIR resource by the time we access the primaryCodePath? Or is this just identifying an edge-case that we aren't handling?

EDIT: This also happens with the ColorectalCancerScreeningsFHIR bundle in ecqm-content-r4-2021:

I have this fixed, but I'm looking into some other code-like types handling based on some additional discussion with @hossenlopp .

[lmd59]

Great stuff! Some small inline comments and some open questions. I tested this on all the ecqm-content-r4-2021 and connectathon measures and found two things I wasn't completely sure about:

1. It looks like medication request looks doesn't have a space between the two words:

Not sure if this even matters but I thought I would point it out. Relevant measure is EXM105-8.2.000 & the numerator patient.

2. Sometimes the observation statement pretty result isn't in square brackets. An example of it without square brackets can be seen in the DiabetesHemoglobinA1cHbA1cPoorControl9FHIR measure & denom patient (with measurementPeriodStart: 2019-01-01 and measurementPeriodEnd: 2019-12-31):

1. MedicationRequest is the name of the resource type, which I think we receive as camel case - maybe gets a bit confusing when we all-caps it. I could potentially not capitalize the whole type, leaving it camel case. I don't think that would be too different from Bonnie, though not what I initially discussed with @hossenlopp. Would that work better?
2. The square brackets are to indicate that it's an array, so if there are square brackets, that just means the type of the result is an array (even if it just has one item). This depends on the statement being made and what kind or results are expected from that statement calculation. We experimented a bit with getting rid of the brackets when there's just one item, but it might still be valuable for the user to know whether the type of the result is an array or not, so we left it with the brackets.

[lmd59]

Nice! Great additions. Just one inline suggestion. Also, I noticed that buildStatementAndClauseResults has doPretty as a parameter, even though I think it is always set to true. Do we still want this?

Hmm- yeah looks like buildStatementAndClauseResults() is only ever called with doPretty: true. It certainly isn't hurting anything. Maybe we were thinking of making this configurable at a higher level at some point?