Common CQL Artifacts for FHIR (US-Based)
2.0.0-ballot - Informative 2 Ballot

Common CQL Artifacts for FHIR (US-Based) - Downloaded Version null See the Directory of published versions

## Patient Patterns

Page standards status: Informative | Highlight text changes?

USCore defines the USCore Patient

### Modifier Elements

The base Patient resource defines the following modifier elements:

- active
- deceased
- link

In general, applications should ensure that the `active`, `deceased`, and `link` elements for a Patient resource are appropriately set for their use case. Note that for many applications, such as prior-authorization, the context will already have established that the patient in question is active and not deceased (or that the values for these elements are appropriate for the prior-authorization in progress).

Note that US Core does not profile the `link` element, so applications should consider whether their functionality would be impacted by the presence of `link` elements on the Patient resource.

### Search Parameters

In general, the patient under consideration will be established by application context, so although US Core does define search parameters for Patient based on identifiers, name, birthdate, and gender, no special considerations are discussed here.

### Cross-Version Considerations

There are no significant backwards-compatibility issues between versions for the Patient profiles. Newer versions of US Core add additional extensions, as well as additional expectations on elements like `use` for name, contact, and address elements. Applications should ensure that they allow for the possibility that these newly supported elements will not be available when operating on Patient resources retrieved from servers implementing earlier versions of US Core.

### Common Elements and Functions

#### Patient name

Although patient name will typically already be known and established by application context, patterns for accessing and displaying patient name are provided for applications that may still need to establish, discover, or display this information.

Because FHIR allows for multiple names for different uses, as well as different usage periods, the name of a patient is not always straightforward to determine. For completeness, the US Core Elements library defines several functions for accessing the name of a Patient. In the most common case, the `.name()` function can be used:

    Patient.name()

The name function is just the first official, usual, or non-official non-usual name that is defined for the Patient. The avaiable name functions defined in the US Core Elements library are:

- ​`.name()`
- ​`.usualName()`
- ​`.officialName()`
- ​`.firstNonOfficialNonUsualName()`

In addition, the library defines functions for common use cases for the HumanName type:

- ​`.firstName()`
- ​`.middleNames()`
- ​`.lastName()`
- ​`.firstMiddleLast()`
- ​`.lastFirstMiddle()`

#### Patient birthDate

Typically, patient birthDate is just represented using the birthDate element:

    Patient.birthDate

However, FHIR also defines a `birthTime` extension, and applications that want to consider this level of specificity when determining patient age can make use of this extension.

Since the birthTime extension is defined in the extensions pack, it can be used anywhere, and the FHIRCommon CQL library defines a function for accessing it, as well as a function for accessing the birthDate as a dateTime, considering this birthTime extension if present:

    Patient.birthTime()
    Patient.birthDateTime()

- `.birthTime()`
- `.birthDateTime()`

#### Patient age

Patient information includes the birth date, and CQL provides a built-in function to calculate the age of a patient, either current age (i.e. as of now), or as of a particular date. In quality improvement artifacts, age is typically calculated as of a particular date. In the context of a Questionnaire, this is typically just today's date, and can be accessed using the `ageInYears()` function:

    define "Patient Age Between 50 and 75":
      Patient.ageInYears() between 50 and 75

The US Core Elements library defines the following patient age calculation functions:

- ​`.ageInDaysAt()`
- ​`.ageInDays()`
- ​`.ageInMonthsAt()`
- ​`.ageInMonths()`
- ​`.ageInYearsAt()`
- ​`.ageInYears()`

> NOTE: The AgeInYearsAt function in CQL uses the data model (US Core in this case) to understand how to access the patient's birth date information.

> NOTE: CQL supports age calculation functions using both `Date` and `DateTime` values. In both cases the function is shorthand for a date/datetime duration calculation. If the `DateTime` overloads are used, note that the timezone offset is considered and there may be edge cases that result in unexpected results, depending on how large the timezone offset is from the execution timestamp. To avoid these edge cases, best practice is to use the `date from` extractor as shown in the above pattern to ensure the `Date` calculation is used.

#### Patient gender

Patient gender in FHIR is represented using codes from the AdministrativeGender code system:

    define "Patient Is Male":
      Patient.gender = 'male'

> NOTE: Terminology-valued elements in FHIR resources are bound to value sets. The gender element is an example of a required binding, which means that only the codes in the bound value set are allowed to be used. This allows the logic in this example to compare using the actual string `'male'`. In general, terminology-valued elements should be compared using terminology operators. For more information, see the Using Terminology topic in the Using CQL With FHIR IG.

#### Patient race and ethnicity

US Core defines extensions for representing the race and ethnicity of a patient using the CDC's race and ethnicity codes. When authoring using USCore, these extensions can be accessed directly on the patient using the "slice name" of the extension:

    define "Patient Race Includes Alaska Native":
      Patient P
        where exists (P.race().ombCategory C where C ~ "American Indian or Alaska Native")
          and exists (P.race().detailed C where C ~ "Alaska Native")

> NOTE: CQL uses the data model (US Core in this case) to understand how to access patient information using the `Patient` definition. This definition is available in `Patient` contexts.

#### Patient deceased

Some elements in USCore profiles allow for values to be represented in different ways. For example, the `deceased` element allows values of `Boolean` and `DateTime`. This means that the value of the `deceased` element for any particular patient may be either a Boolean (`true` or `false`) or a DateTime. In FHIR and CQL, these types of elements are called choice types.

> NOTE: Because the US Core model is using CQL system-defined types (see the FHIR Type Mapping topic in the Using CQL With FHIR IG), the spelling of the types uses the CQL type names (e.g. `Boolean` rather than `boolean`).

When accessing choice types in CQL expressions, authors can typically just treat the element as the type they are interested in accessing. For example:

    define "Patient Is Deceased":
      Patient.deceased is true

    define "Patient Deceased During Measurement Period":
      Patient.deceased during day of "Measurement Period"

In the first expression, the `deceased` element is treated as a Boolean, whereas in the second expression, the `deceased` element is treated as a DateTime.

> NOTE: No value conversions take place when accessing choice types, when using the "Patient Is Deceased" expression above, for example, if the Patient record has a DateTime value for the deceased element, the result of that expression will be `null`.

> NOTE: Content for this page was adapted from the QICore Authoring Patterns - Patient topic.