fqm-execution

FHIR Quality Measure Execution and Highlighting

Library for executing FHIR-based Electronic Clinical Quality Measures (eCQMs) written in Clinical Quality Language (CQL)

• Installation

• Usage

  • Module
  • Calculation Options
  • CLI
  • TypeScript

• Local Development

  • Prerequisites
  • Local Installation/Usage
  • Debugging in VS Code
  • Testing
  • Checks

• License

Installation

fqm-execution can be installed into your project with npm:

npm install --save fqm-execution

To install the global command line interface (CLI), use npm global installation:

npm install -g fqm-execution

Usage

Module

ES6

import { Calculator } from 'fqm-execution';

const rawResults = await Calculator.calculateRaw(measureBundle, patientBundles, options, valueSetCache); // Get raw results from CQL engine for each patient
const detailedResults = await Calculator.calculate(measureBundle, patientBundles, options, valueSetCache); // Get detailed population results for each patient
const measureReports = await Calculator.calculateMeasureReports(measureBundle, patientBundles, options, valueSetCache); // Get individual FHIR MeasureReports for each patient
const gapsInCare = await Calculator.calculateGapsInCare(measureBundle, patientBundles, options, valueSetCache); // Get gaps in care for each patient, if present
const dataRequirements = Calculator.calculateDataRequirements(measureBundle); // Get data requirements for a given measure (in a bundle)
const queryInfo = Calculator.calculateQueryInfo(measureBundle); // Get detailed query info for all statements in a meaasure

Require

const { Calculator } = require('fqm-execution');

const rawResults = await Calculator.calculateRaw(measureBundle, patientBundles, options, valueSetCache); // Get raw results from CQL engine for each patient
const detailedResults = await Calculator.calculate(measureBundle, patientBundles, options, valueSetCache); // Get detailed population results for each patient
const measureReports = await Calculator.calculateMeasureReports(measureBundle, patientBundles, options, valueSetCache); // Get individual FHIR MeasureReports for each patient
const gapsInCare = await Calculator.calculateGapsInCare(measureBundle, patientBundles, options, valueSetCache); // Get gaps in care for each patient, if present
const dataRequirements = Calculator.calculateDataRequirements(measureBundle); // Get data requirements for a given measure (in a bundle)
const queryInfo = Calculator.calculateQueryInfo(measureBundle); // Get detailed query info for all statements in a meaasure

Arguments

• measureBundle: Bundle containing a FHIR Measure and its dependendent Libraries. FHIR ValueSets may be included as well
• patientBundles: Array of FHIR Bundles containing patient data
• options (optional): Object of calculation options (see below)
• valueSetCache (optional): Array of FHIR ValueSet resources to use for calculation

Calculation Options

The options that we support for calculation are as follows:

option	type	optional?	description
enableDebugOutput	boolean	yes	Enable debug output from function calls. Defaults to false.
includeClauseResults	boolean	yes	Option to include clause results. Defaults to false.
includePrettyResults	boolean	yes	Option to include pretty results on statement results. Defaults to false.
includeHighlighting	boolean	yes	Include highlighting in MeasureReport narrative. Defaults to false.
measurementPeriodStart	string	yes	Start of measurement period.
measurementPeriodEnd	string	yes	End of measurement period.
patientSource	any	yes	PatientSource to use. If provided, the patientBundles will not be required.
reportType	string	yes	Type of MeasureReport to generate: "summary" or "individual".
calculateSDEs	boolean	yes	Include Supplemental Data Elements in calculation. Defaults to false.
calculateHTML	boolean	yes	Include HTML structure for highlighting. Defaults to false.
vsAPIKey	string	yes	API key, to be used to access a valueset API for downloading any missing valuesets
useValueSetCaching	boolean	yes	Whether to cache valuesets obtained by an API on the filesystem

CLI

To run the globally installed CLI (see above), use the global fqm-execution command

Usage: fqm-execution [options]

Options:
  -d, --debug                                 enable debug output (default: false)
  -o, --output-type <type>                    type of output, "raw", "detailed", "reports", "gaps", "dataRequirements", "queryInfo" (default: "detailed")
  -r, --report-type <type>                    type of MeasureReport (only for output type "reports"): "summary" or "individual" (default: "individual")
  -m, --measure-bundle <measure-bundle>       path to measure bundle
  -p, --patient-bundles <patient-bundles...>  paths to patient bundle
  -s, --measurement-period-start <date>       start date for the measurement period, in YYYY-MM-DD format (defaults to the start date defined in the Measure, or 2019-01-01 if not set there)
  -e, --measurement-period-end <date>         end date for the measurement period, in YYYY-MM-DD format (defaults to the end date defined in the Measure, or 2019-12-31 if not set there)
  -a, --vs-api-key <key>                      API key, to authenticate against the valueset service to be used for resolving missing valuesets
  -c, --cache-valuesets                       Whether or not to cache ValueSets retrieved from the ValueSet service (default: false)
  -h, --help                                  display help for command

E.g.

fqm-execution -o reports -m /path/to/measure/bundle.json -p /path/to/patient1/bundle.json > reports.json

ValueSets

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.

To find your VSAC API key, sign into the UTS homepage, click on My Profile in the top right, and copy the API KEY value from the UMLS Licensee Profile.

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

Local Development

Prerequisites

• Node.js >=10.15.1
• Git

Local Installation/Usage

Clone the source code:

git clone https://github.com/projecttacoma/fqm-execution.git

Install dependencies:

npm install

Optionally, you can install the ts-node utility globally to execute the TypeScript files directly instead of running the build script:

npm install -g ts-node

Run the CLI with ts-node:

ts-node --files src/cli.ts [options]

Or using the built JavaScript:

npm run build
node build/cli.js [options]

Debug Option

The CLI comes built with a debug option (-d/--debug) which will include a debugOutput property on the results object containing any CQL, ELM, ValueSets, and engine results processed during execution.

Debugging in VS Code

To attach a debugger to the TypeScript files for deeper inspection of the tool's functionality, we recommend using the VS Code text editor to be able to provide easy debugger configuration.

Add the following contents to .vscode/launch.json in the root of the project directory:

{
    // Use IntelliSense to learn about possible attributes.
    // Hover to view descriptions of existing attributes.
    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
    "version": "0.2.0",
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "Launch Program",
            "skipFiles": [
              "<node_internals>/**"
            ],
            "preLaunchTask": "npm: build",
            "program": "${workspaceFolder}/src/cli.ts",
            "outFiles": [
              "${workspaceFolder}/build/**/*.js"
            ],
            "internalConsoleOptions": "openOnSessionStart",
            "args": ["-m", "${workspaceFolder}/relative/path/to/measure/bundle.json", "-p", "${workspaceFolder}/relative/path/to/patient/bundle.json", "-o", "<reports | detailed | raw | gaps>"]
          }
    ]
}

This will allow you to run the CLI from the Run tab in VS Code, and will halt execution of the program at any breakpoints or debugger statements in the code, to allow for debugging of the functionality.

Testing

We use Jest for unit-testing fqm-execution. Tests can be running using the test script in package.json:

npm test

Checks

When contributing new code, ensure that all tests, lint, and prettier checks pass with the following command:

npm run check

Architecture Overview

A visual representation of the calculate sequence of the application can be seen below:

License

Copyright 2020 The MITRE Corporation

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.