...'
...
}
*/
```
### Uncoverage Highlighting
`fqm-execution` can also generate highlighted HTML that indicate which pieces of the measure logic did NOT have a "truthy" value during calculation. This is the complement to coverage. Clauses that are not covered will be highlighted red.
This option, `calculateClauseUncoverage`, defaults to disabled. When running the CLI in `--debug` mode this option will be enabled and output to the debug directory.
HTML strings are returned for each group defined in the `Measure` resource in the lookup object,`groupClauseUncoverageHTML`, which is structured similarly to Group Clause Coverage.
```typescript
import { Calculator } from 'fqm-execution';
const { results, groupClauseUncoverageHTML } = await Calculator.calculate(measureBundle, patientBundles, {
calculateClauseUncoverage: true /* false by default */
});
// groupClauseUncoverageHTML
/* ^?
{
'population-group-1': '
population-group-1 Clause Uncoverage: X of Y clauses
...'
...
}
*/
```
### Coverage Details
Details on clause coverage can also be returned. This includes a count of how many clauses there are, how many are covered and uncovered, and information about which clauses are uncovered.
This option, `calculateCoverageDetails`, defaults to disabled. When running the CLI in `--debug` mode this option will be enabled and output to the debug directory.
This information is returned for each group defined in the `Measure` resource in the lookup object,`groupClauseCoverageDetails`, which maps `group ID -> coverageDetails`. See example below for structure of this object.
```typescript
import { Calculator } from 'fqm-execution';
const { results, groupClauseCoverageDetails } = await Calculator.calculate(measureBundle, patientBundles, {
calculateCoverageDetails: true /* false by default */
});
// groupClauseCoverageDetails
/* ^?
{
"population-group-1": {
"totalClauseCount": 333,
"coveredClauseCount": 330,
"uncoveredClauseCount": 3,
"uncoveredClauses": [
{
"localId": "97",
"libraryName": "MAT6725TestingMeasureCoverage",
"statementName": "Has Medical or Patient Reason for Not Ordering ACEI or ARB or ARNI"
},
...
]
}
...
}
*/
```
### Clause Coverage of Null and False Literal Values
Since clause coverage calculation and highlighting are based on whether individual pieces of the measure logic CQL were processed at all during calculation and held "truthy" values, `Null` and false `Literal`s that are processed during calculation would prevent 100% clause coverage and highlighting. In order to handle this special case, these clauses that will never hold "truthy" values will be highlighted and counted as covered if they were simply processed during calculation.
For example, the define statement of "SDE Sex" is a case statement where the `else` is `null`. The `null` is an example of a clause that will never hold a "truthy" value. If the set of patients includes a patient where either `Patient.gender` does not exist or `Patient.gender` does not equal `'male'` or `'female'`, `else null` is highlighted and counted in the clause coverage percentage.
### Visual Issues with Coverage Highlighting
Clause coverage HTML generation relies on annotations generated from the [cql-to-elm translator](https://github.com/cqframework/clinical_quality_language/blob/main/Src/java/cql-to-elm/README.md). In some cases, the identifying information for snippets of text in these annotations may not be consistent with what is in the actual ELM expression.
This leads to a discrepancy in the clause coverage view where the percentage value is accurate, but parts of the HTML appear to be falsely uncovered.
If a case like this is encountered where something is not highlighting despite the clause actually being covered by a given patient, please feel free to [submit an issue](/contributing.md#issue-reports).
## ValueSet Resolution
If the Measure bundle provided doesn't contain all the required `ValueSet` resources (with expansions or composes) to calculate the measure, an API key can be provided to resolve the ValueSets from their provided URLs. Currently only tested with ValueSets from the [NLM FHIR ValueSet API](https://cts.nlm.nih.gov/fhir).
To find your VSAC API key, sign into [the UTS homepage](https://uts.nlm.nih.gov/uts/), click on `My Profile` in the top right, and copy the `API KEY` value from the `UMLS Licensee Profile`.
`ValueSets` can also be passed in directly to the calculation functions via the `valueSetCache` argument in most calculation functions. This is an alternative solution to including them directly in the `Bundle` when it is not feasible to do so.
## Custom PatientSource
Via the `patientSource` calculation option, users can provide their own provider of patient data to `fqm-execution` that will be called by the underlying `cql-execution` engine. The [type definitions in cql-execution](https://github.com/cqframework/cql-execution/blob/e4d3f24571daf3ae9f891df11bb22fc964f6de5d/src/types/cql-patient.interfaces.ts#L8) indicate which functions a custom `DataProvider` must implement
to work alongside `cql-execution`. The following skeleton code showcases the implementations that would be required for a hypothetical custom `DataProvider`:
```typescript
import { PatientObject, DataProvider, RecordObject } from 'cql-execution';
// NOTE: it is recommended here to re-use the FHIRObject class from cql-exec-fhir, if possible
class CustomRecordObject implements RecordObject {
get(field: any) {
/* Implementation that returns the value of any field on this object */
}
// Required by cql-execution API
getId() {
/* Implementation that returns the value of the id field on this object */
}
// Required by cql-execution API (but not currently used in the cql-exec-fhir FHIR data model)
getCode(field: any) {
/* Implementation that returns the value of the field on this object as a cql-execution Code type */
}
// Required by cql-execution API (but not currently used in the cql-exec-fhir FHIR data model)
getDate(field: any) {
/* Implementation that returns the value of the field on this object as a cql-execution Date type */
}
// Required by cql-execution API (but not currently used in the cql-exec-fhir FHIR data model)
getDateOrInterval(field: any) {
/* Implementation that returns the value of the field on this object as a cql-execution Date or Interval type */
}
}
class CustomPatientObject extends CustomRecordObject implements PatientObject {
findRecords(profile: string | null, retrieveDetails?: RetrieveDetails): CustomRecordObject[] {
/* Implementation that finds all relevant `profile` records on this Patient */
}
}
class CustomPatientSource implements DataProvider {
currentPatient(): CustomPatientObject | undefined {
/* Implementation that returns an instance of the CustomPatientObject class */
}
nextPatient(): CustomPatientObject | undefined {
/* Implementation that returns an instance of the CustomPatientObject class */
}
}
```
With this hypothetical `CustomPatientSource` class defined, we can now pass it in to `fqm-execution`'s calculation functions instead of including patient `Bundle` resources directly in the function call:
```typescript
import { Calculator } from 'fqm-execution';
// ...
const customPatientSource = new CustomPatientSource();
// do whatever needs to be done to load patient data into customPatientSource, if anything
const { results } = await Calculator.calculate(measureBundle, [], {
/* other options */
patientSource: customPatientSource
});
```
## Usage with TypeScript
`fqm-execution` exports custom-defined TypeScript interfaces used within the code to allow for easy integration into other TypeScript projects. The TypeScript files defining these interfaces can be found [here](https://github.com/projecttacoma/fqm-execution/tree/master/src/types), and the specific types that are exposed via `fqm-execution`'s exports can be seen [here](https://github.com/projecttacoma/fqm-execution/blob/master/src/index.ts#L16). They are described as follows:
- [src/types/Calculator.ts](https://github.com/projecttacoma/fqm-execution/blob/master/src/types/Calculator.ts): Contains all interfaces used to specify types during calculation (e.g. return types of calculation functions, type of calculation options object)
- [src/types/CQLTypes.ts](https://github.com/projecttacoma/fqm-execution/blob/master/src/types/CQLTypes.ts): Low-level types that interface with the `cql-execution` engine. Unlikely to be needed outside of `fqm-execution` itself, but provided anyway for convenience
- [src/types/ELMTypes.ts](https://github.com/projecttacoma/fqm-execution/blob/master/src/types/ELMTypes.ts): Low-level types that define basic structure of ELM. Does not define the entire ELM logical specification. Unlikely to be needed outside of `fqm-execution` itself, but provided anyway for convenience
- [src/types/Enums.ts](https://github.com/projecttacoma/fqm-execution/blob/master/src/types/Enums.ts): Contains any `enum`s used across the codebase, specifically with respect to population results reporting (e.g. population types, scoring types, truthy/falsy result reporting)
Types defined in any of the above files are exported by the root `fqm-execution` library, and can be imported directly:
```typescript
import { CalculationOptions, PopulationType, MeasureScoreType, FinalResult, Relevance } from 'fqm-execution';
const calculationOptions: CalculationOptions = {
/* type-safe options */
};
// Check if a population is the code for initial population
if (somePopulation === PopulationType.IPP) {
// ...
}
// Check if some measure scoring code is the code for ratio measure scoring
if (someScoringCode === MeasureScoreType.RATIO) {
// ...
}
// Check if some population result has a truthy final result
if (somePopulationFinalResult === FinalResult.TRUE) {
// ...
}
// Check if some population result is not relevant for eCQM calculation (i.e. wasn't considered)
if (somePopulationRelevanceResult === Relevance.NA) {
// ...
}
```
### DEPRECATION NOTICE
The following style of importing `fqm-execution` types is still supported, but will be removed in the next major version of `fqm-execution`:
```typescript
import { CalculatorTypes, Enums, CQLTypes, ELMTypes } from 'fqm-execution';
```
# Recipes
## Displaying Highlighted HTML in a React App
A common use case for the highlighted logic HTML described in the [Measure Logic Highlighting section](#measure-logic-highlighting) is displaying it in a web application of some kind. In the case of React, trying to render an HTML string directly will not work
due to React's security measures to prevent Cross Site Scripting by escaping/sanitizing HTML strings that attempt to be rendered in the DOM.
To display the highlighted HTML in a React app, it is recommended to use a package such as [html-react-parser](https://www.npmjs.com/package/html-react-parser) to parse the content of the highlighted HTML string into actual `ReactNode` entities that can be rendered in the DOM:
```tsx
import { Calculator } from 'fqm-execution';
import parse from 'html-react-parser';
import { useState } from 'react';
export default function CalculationComponent() {
const [htmlStrings, setHtmlStrings] = useState
([]);
const calculateMeasure = async () => {
const { results } = await Calculator.calculate(measureBundle, [patientBundle], {
calculateHTML: true
});
// @example Display HTML string for every group result
// could modify this to look up results for a specific group
const htmls: string[] = [];
results.forEach(patientResult => {
patientResult.detailedResults?.forEach(groupResultForPatient => {
htmls.push(groupResultForPatient.html ?? '');
});
});
setHtmlStrings(htmls);
};
const calculateMeasureReports = async () => {
const { results } = await Calculator.calculateMeasureReports(measureBundle, [patientBundle], {
calculateHTML: true,
reportType: 'individual'
});
// individual MeasureReport calculation returns a list of individual MeasureReports
// access the first one in this example since we only have one patient
const [mr] = results as fhir4.MeasureReport[];
setHtmlStrings([mr.text?.div ?? '']);
};
return (
{htmlStrings.map(s => (
{parse(s)}
))}