Update measurement period precision to millisecond

[sarahmcdougall]

Summary

Fixes https://github.com/projecttacoma/fqm-execution/issues/241 Updates measurement period precision support down to the millisecond.

New behavior

Fqm-execution now supports precision of measurement period down to the millisecond rather than only down to the minute. This has potential impacts on the calculation results, depending on the measurement period precision being used (i.e. results may be different between the master branch and this branch when using millisecond precision in the CalculationOptions measurement period)

Code changes

• src/execution/ValueSetHelper.ts —> update the moment format to moment.defaultFormatUtc in parseTimeStringAsUTC and parseTimeStringAsUTCConvertingToEndOfYear (see the moment documentation for more info on formatting)
  • parseTimeStringAsUTCConvertingToEndOfYear does not get used anywhere in the code base, so open to thoughts on whether to keep it
• README.md —> documentation updates for measurement period precision
  • In terms of typing, the defaultFormatUtc format seems to align with the values allowed by a FHIR dateTime, which I included in the documentation. Open to thoughts on whether to explicitly cite the type as a dateTime or not.

Testing guidance

1. Test with the measure/patient bundle provided in #241 (attached below as a .zip) with the measurement period specified in the issue:
   • Measurement period start: 2024-01-01T00:00:00.000+00:00
   • Measurement period end: 2024-12-31T23:59:59.999+00:00

Example CLI command (assuming the bundles are at the root of fqm-execution):

npm run cli -- detailed -m measureBundle.json -p patientBundle.json -o --vs-api-key <your-api-key> --debug -s 2024-01-01T00:00:00.000+00:00 -e 2024-12-31T23:59:59.999+00:00

Pay attention to the “Narcolepsy Exclusion” statement. On the master branch, the statement will contain red clauses due to minute precision of the measurement period (Condition.onsetDateTime is 2024-12-31T23:59:01:000Z):

On this branch, the entire statement should be green due to millisecond precision:

2. Test different measurement periods with different levels of precision against the example measure/patient bundle. Some examples include:
   • YYYY-MM-DD format: when measurement period end is set to 2025-01-01, the statement should be green; when measurement period end is set to 2024-12-31, the statement should be red
   • YYYY format: when measurement period end is set to 2025, the statement should be green; when measurement period end is set to 2024, the statement should be red
   • YYYY-MM format: when measurement period end is set to 2025-01, the statement should be green; when measurement period end is set to 2024-12, the statement should be red

Bundles from GH issue: precisionBundles.zip

[github-actions[bot]]

Coverage report

St.:grey_question:	Category	Percentage	Covered / Total
🟢	Statements	86.25%	2258/2618
🟡	Branches	75.4%	2087/2768
🟢	Functions	89.41%	422/472
🟢	Lines	86.57%	2178/2516

Test suite run success

424 tests passing in 31 suites.

Report generated by 🧪jest coverage report action from 673731dd97b7af5c6868c6eb8493a236228c0aa3

[mgramigna]

Do we actually want moment.defaultFormat instead of moment.defaultFormatUtc?

defaultFormatUtc seems to actually ignore any timezone offsets present in the datetime and just always use Z, whereas defaultFormat accounts for the timezone offset when spitting out the UTC date:

I missed this when initially looking at the moment docs

[sarahmcdougall]

Do we actually want moment.defaultFormat instead of moment.defaultFormatUtc?

Update: After some discussion, using defaultFormatUtc seems more appropriate given the possible CQL logic that could be encountered during measure calculation. Added a sentence to the documentation explaining that timezone offsets are not taken into account when they are supplied on the measurement period.

I did some more testing with moment.defaultFormatUtc with provided measurement periods that do specify offsets, and the offsets get ignored, as expected.