Population Group: group-1
...\"\n }\n ...\n }\n ...\n ]\n */\n```\n\n**NOTE**: Measure logic highlighting is not available when calculating a population `MeasureReport` with `reportType = 'summary'`\n\n### Population Relevance for Highlighting\n\nHowever, highlighted HTML provided by `fqm-execution` is not solely based on whether individual pieces of the measure logic CQL had \"truthy\" or \"falsy\" values. When there are populations that depend on each other, a relevance hierarchy is built to ensure that populations that are subsets of others aren't considered for membership until membership is determined for their superset population. If a statement's superset statement is false, then no highlighting will appear, regardless of whether that statement's value is \"truthy\" or \"falsy\". This pattern reflects the actual population results that are being returned during calculation.\n\nThe following example of a proportion boolean measure shows how the logic highlighting will not style the numerator and denominator despite their truthy raw values because the initial population evaluates to false. The relevance calculation matches the semantics for proportion measures defined in [this flowchart](https://hl7.org/fhir/us/cqfmeasures/STU5/measure-conformance.html#proportion-measure-scoring).\n\n\n\n### CQL Statement Ordering in HTML\n\nBy default, the CQL statements in the generated HTML output are sorted into population statements, non-functions, and functions, respectively. Non-population statements appear in alphabetical order. Population statements are sorted in the following order:\n\n1. initial-population\n2. denominator\n3. denominator-exclusion\n4. denominator-exception\n5. numerator\n6. numerator-exclusion\n7. measure-population\n8. measure-population-exclusion\n9. measure-observation (alphabetically sorted if multiple)\n\nThe order of these populations is determined by most inclusive to least inclusive populations as shown in the following diagram found [here](http://hl7.org/fhir/us/cqfmeasures/STU1/measure-conformance.html#conformance-requirement-11):\n\n\n\nTo disable this behavior, use the `disableHTMLOrdering` calculation option.\n\n### Statement-level HTML\n\nOptionally, `fqm-execution` can generate the stylized HTML markup for each individual statement. To access the statement-level HTML, specify the `buildStatementLevelHTML` in the `CalculationOptions` prior to measure calculation. From the `detailedResults` returned for a given patient, the `statementLevelHTML` will be available as an element on each `statementResult` whose relevance is _not_ N/A.\n\n```typescript\n[\n {\n patientId: 'test-patient',\n detailedResults: [\n {\n groupId: 'test-group',\n statementResults: [\n // no HTML returned since relevance is NA\n {\n libraryName: 'MATGlobalCommonFunctionsFHIR4',\n statementName: 'Patient',\n final: 'NA',\n relevance: 'NA',\n isFunction: false,\n pretty: 'NA'\n },\n {\n libraryName: 'CancerScreening',\n statementName: 'SDE Sex',\n final: 'TRUE',\n relevance: 'TRUE',\n isFunction: false,\n pretty: 'CODE: http://hl7.org/fhir/v3/AdministrativeGender F, Female',\n statementLevelHTML:\n '
\\n...\\n
'\n }\n ]\n }\n ]\n }\n];\n```\n\n## Group Clause Coverage Highlighting\n\n`fqm-execution` can generate highlighted HTML that indicates which individual pieces of the measure logic CQL were processed at all during calculation and held \"truthy\" values. This is often referred to as \"Clause Coverage\". \"Covered\" clauses will\nhave a blue background and dashed underline in the highlighted HTML, indicating that those clauses were processed during measure calculation and had \"truthy\" values. This is useful for testing measure logic, as it is often desired to create a set of patients that cover 100% of the measure logic.\n\nThe highlighted HTML also provides an approximate percentage for what percentage of the measure logic is covered by the patients that were passed in to execution.\n\nThis option, `calculateClauseCoverage`, defaults to enabled. When running the CLI in `--debug` mode this option will be enabled and output to the debug directory.\n\n\n\nHTML strings are returned for each group defined in the `Measure` resource in the lookup object, `groupClauseCoverageHTML`, which maps `group ID -> HTML string`\n\n```typescript\nimport { Calculator } from 'fqm-execution';\n\nconst { results, groupClauseCoverageHTML } = await Calculator.calculate(measureBundle, patientBundles, {\n calculateClauseCoverage: true /* true by default, but explicitly shown for demonstration */\n});\n\n// groupClauseCoverageHTML\n/* ^?\n {\n 'population-group-1': '
population-group-1 Clause Coverage: X%
...'\n ...\n }\n\n\n*/\n```\n\n### Uncoverage Highlighting\n\n`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.\n\nThis option, `calculateClauseUncoverage`, defaults to disabled. When running the CLI in `--debug` mode this option will be enabled and output to the debug directory.\n\nHTML strings are returned for each group defined in the `Measure` resource in the lookup object,`groupClauseUncoverageHTML`, which is structured similarly to Group Clause Coverage.\n\n```typescript\nimport { Calculator } from 'fqm-execution';\n\nconst { results, groupClauseUncoverageHTML } = await Calculator.calculate(measureBundle, patientBundles, {\n calculateClauseUncoverage: true /* false by default */\n});\n\n// groupClauseUncoverageHTML\n/* ^?\n {\n 'population-group-1': '
population-group-1 Clause Uncoverage: X of Y clauses
...'\n ...\n }\n\n\n*/\n```\n\n### Coverage Details\n\nDetails 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.\n\nThis option, `calculateCoverageDetails`, defaults to disabled. When running the CLI in `--debug` mode this option will be enabled and output to the debug directory.\n\nThis 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.\n\n```typescript\nimport { Calculator } from 'fqm-execution';\n\nconst { results, groupClauseCoverageDetails } = await Calculator.calculate(measureBundle, patientBundles, {\n calculateCoverageDetails: true /* false by default */\n});\n\n// groupClauseCoverageDetails\n/* ^?\n {\n \"population-group-1\": {\n \"totalClauseCount\": 333,\n \"coveredClauseCount\": 330,\n \"uncoveredClauseCount\": 3,\n \"uncoveredClauses\": [\n {\n \"localId\": \"97\",\n \"libraryName\": \"MAT6725TestingMeasureCoverage\",\n \"statementName\": \"Has Medical or Patient Reason for Not Ordering ACEI or ARB or ARNI\"\n },\n ...\n ]\n }\n ...\n }\n*/\n```\n\n### Clause Coverage of Null and False Literal Values\n\nSince 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.\n\nFor 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.\n\n\n\n### Visual Issues with Coverage Highlighting\n\nClause 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.\nThis 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.\n\nIf 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).\n\n## ValueSet Resolution\n\nIf 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).\n\nTo 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`.\n\n`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.\n\n## Custom PatientSource\n\nVia 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\nto work alongside `cql-execution`. The following skeleton code showcases the implementations that would be required for a hypothetical custom `DataProvider`:\n\n```typescript\nimport { PatientObject, DataProvider, RecordObject } from 'cql-execution';\n\n// NOTE: it is recommended here to re-use the FHIRObject class from cql-exec-fhir, if possible\nclass CustomRecordObject implements RecordObject {\n get(field: any) {\n /* Implementation that returns the value of any field on this object */\n }\n\n // Required by cql-execution API\n getId() {\n /* Implementation that returns the value of the id field on this object */\n }\n\n // Required by cql-execution API (but not currently used in the cql-exec-fhir FHIR data model)\n getCode(field: any) {\n /* Implementation that returns the value of the field on this object as a cql-execution Code type */\n }\n\n // Required by cql-execution API (but not currently used in the cql-exec-fhir FHIR data model)\n getDate(field: any) {\n /* Implementation that returns the value of the field on this object as a cql-execution Date type */\n }\n\n // Required by cql-execution API (but not currently used in the cql-exec-fhir FHIR data model)\n getDateOrInterval(field: any) {\n /* Implementation that returns the value of the field on this object as a cql-execution Date or Interval type */\n }\n}\n\nclass CustomPatientObject extends CustomRecordObject implements PatientObject {\n findRecords(profile: string | null, retrieveDetails?: RetrieveDetails): CustomRecordObject[] {\n /* Implementation that finds all relevant `profile` records on this Patient */\n }\n}\n\nclass CustomPatientSource implements DataProvider {\n currentPatient(): CustomPatientObject | undefined {\n /* Implementation that returns an instance of the CustomPatientObject class */\n }\n\n nextPatient(): CustomPatientObject | undefined {\n /* Implementation that returns an instance of the CustomPatientObject class */\n }\n}\n```\n\nWith 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:\n\n```typescript\nimport { Calculator } from 'fqm-execution';\n\n// ...\n\nconst customPatientSource = new CustomPatientSource();\n\n// do whatever needs to be done to load patient data into customPatientSource, if anything\n\nconst { results } = await Calculator.calculate(measureBundle, [], {\n /* other options */\n patientSource: customPatientSource\n});\n```\n\n## Usage with TypeScript\n\n`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:\n\n- [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)\n- [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\n- [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\n- [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)\n\nTypes defined in any of the above files are exported by the root `fqm-execution` library, and can be imported directly:\n\n```typescript\nimport { CalculationOptions, PopulationType, MeasureScoreType, FinalResult, Relevance } from 'fqm-execution';\n\nconst calculationOptions: CalculationOptions = {\n /* type-safe options */\n};\n\n// Check if a population is the code for initial population\nif (somePopulation === PopulationType.IPP) {\n // ...\n}\n\n// Check if some measure scoring code is the code for ratio measure scoring\nif (someScoringCode === MeasureScoreType.RATIO) {\n // ...\n}\n\n// Check if some population result has a truthy final result\nif (somePopulationFinalResult === FinalResult.TRUE) {\n // ...\n}\n\n// Check if some population result is not relevant for eCQM calculation (i.e. wasn't considered)\nif (somePopulationRelevanceResult === Relevance.NA) {\n // ...\n}\n```\n\n### DEPRECATION NOTICE\n\nThe following style of importing `fqm-execution` types is still supported, but will be removed in the next major version of `fqm-execution`:\n\n```typescript\nimport { CalculatorTypes, Enums, CQLTypes, ELMTypes } from 'fqm-execution';\n```\n\n# Recipes\n\n## Displaying Highlighted HTML in a React App\n\nA common use case for the highlighted logic HTML described in the [Measure Logic Hig","readmeFilename":"README.md"}