What appears below is what I just finished writing as a suggested addition to the HQMF Release DSTU that is being balloted until next Wednesday. It's a more formal definition of what I called
Simple Math previously. But it goes beyond that because it also defines the binding of variables, and defines how classes and attributes are named in the context of HQMF.
I'm not fully satisfied by this solution because it still requires quite a bit of mapping from RIM semantics to implementation detail, but I think it's the best choice to resolve the issues of computation. For those of you who are going to say again that I should be using JavaScript, GELLO or XPath, or your other favorite language PLEASE READ the second paragraph below. I already am.
Appendix B: An expression language for use in HQMF
The HQMF specification does not describe an expression language for use in the <expression> element of values found in MeasureObservationDefinition, nor in the <value> element of the joinCondition. HQMF implementations may be based on a number of different programming languages and execution environments. Several prototype HQMF interpreters have been created. Some use JavaScript, others SQL, and others XQuery. Thus, a single choice for the expression language is not obvious. This presents a challenge for implementers, as the lack of a platform neutral expression language means that there is no single expression of a quality measure that could be implemented on multiple platforms.
The goal of the language described below to offer a solution to this challenge. It provides a way to include computable expressions in HQMF. The language is designed in a way that simple regular expression substitutions might be all that is necessary to turn the expression into executable code in a variety of platforms. This language is not intended to create a new language to supersede C, C++, GELLO, Java, JavaScript, Perl, Ruby or XQuery. In fact, the expressions allowed by this language should all be legal expressions in each of these languages, with identical evaluations given an appropriate binding mechanism. Thus, it becomes a (nearly) common subset for writing expressions that can be translated to a variety of implementation platforms.
While there are many implementations of JavaScript, GELLO, and other programming languages available, it is not always feasible to integrate these implementations into existing execution environments. The feasibility is not just based on technical capability. For example, while JavaScript interpreters are widely available, and many can be used in conjunction with, or have already been integrated into SQL databases, some data centers would object to installations or use of software that has not undergone stringent testing. However, the same data center may allow use of existing SQL language capabilities to achieve similar goals.
This appendix demonstrates the feasibility of defining an expression language that is a subset of many common programming languages. This can be done in such a way as to allow implementations to simply reuse expressions found inside an HQMF instance to execute inside their programming environment.
B.1 Identifiers
Identifiers in the language start with an alphabetic character, and may be followed by alphabetic characters, numeric characters, and the _ symbol. Identifiers are used to reference bound variables, class members and functions.
Implementations are required to recognize the ASCII alphabetic characters (A-Z and a-z), Arabic numerals (0-9), and the _ character. The alphabetic characters A and a must be disctinct (no case folding).
While some SQL implementations may case fold identifiers used in tables and columns, it is possible to quote these identifiers to ensure exact matches.
There is no length limit on identifiers. It is up to an implementation to address implementation language specific length limitations when translating identifiers in an HQMF expression to an appropriate value.
identifier ::= [a-zA-Z][a-zA-Z0-9_]*
B.2 Literal Constants
Numeric constants can be integers or real numbers. There are no string or character constants in this language subset. While strings are useful in a general programming context, they are not needed in use cases where expression evaluation is necessary for HQMF.
literal ::= integer | real | timestamp
B.2.1 Integers
Integers are represented using an optional sign (-), followed by a sequence of digits. The sequence of digits must be either a single 0, or a non-zero digit followed by zero or more additional digits.
integer ::= (-)? (0|[1-9][0-9]*)
Implementations must support at least 32-bit precision for integers.
B.2.2 Real Numbers
Real numbers are expressed using an optional negative sign, an integer component, a decimal point, and a decimal component, followed by an optional exponent.
real ::= [-] (0|[1-9][0-9]*).[0-9]+ [(e|E)(+|-)([1-9][0-9]*)]
Implementations must support at least IEEE double-precision real numbers.
B.2.3 Time Stamps
Time Stamps are represented in ISO 8601 Notation without punctuation (as used in HL7 Version 3 rather than in W3C Schema), and between quotes. Thus, 6:30AM ET, on January 20th, 1965 would appear as "196501200630-0600".
timestamp ::= " [0-9]{1-12}(.[0-9]{1-6})?((+|-)[0-9]{1,4})? "
B.3 Operators
B.3.1 Arithmetic Operators
Arithmetic operators include +, -, * and / supporting addition, subtraction and negation, multiplication and division. Precedence of operators is negation, multiplication, division, addition and substraction. The parentheses characters ( and ) are used to override the order of operations.
Implementations must support these operators, and are permitted to support other arithmetic operators.
add-op => '+' | '-'
mult-op => '*' | '/'
B.3.2 Logical Operators
The logical operators are AND, OR and NOT(). NOT is a unary operator and has higher precedence than the other operators. AND has higher precedence than OR.
B.3.3 Comparison Operators
Comparison operators include <, >, >=, <=, ==, and !=. The precedence of these operators is == and !=, followed by <,>,<= and >=. These operators are of lower precedence than arithmetic operators.
Note: == and != were chosen rather than = and <> to simplify substitution. Replacing = by itself with == is harder to do correctly than replacing == with a =. Given that == is used for equality, != becomes the natural symbol (from C and Java languages) for inequality.
eq-op => == | !=
rel-op => <= | >= | < | >
B.4 Grammar
The intent of the grammar specification below is not to enable implementors to “parse” expressions using this language, but to express the intended effects of evaluations of expressions used in this language.
or-expression => and-expression (OR and-expression)*
and-expression => not-expression (AND not-expression)*
not-expression => NOT(not-expression)
| relational-expression
relational-expression => equivalence-expression (rel-op equivalence-expression)*
equality-expression => addition-expression (eq-op addition-expression)*
addition-expression => multiplication-expression (add-op multiplication-expression)
multiplication-expression => primary-expression (mult-op primary-expression)
primary-expression => literal
| - primary-expression
| ( expression )
| identifier-expression ( arg-list )
| identifier-expression
arg-list => expression (, expression)*
identifier-expression => identifier (. identifier)*
B.5 Language Binding
Variables are bound to data in the implementation model through use of the localVariableName element in data criteria. The scope of the localVariableName values is to the entire document, so that all localVariableName values must be unique.
Each local variable in an HQMF expression represents an object that is structured as based on the RIM class from which it is derived. Thus, the language can provide access to the RIM and navigational capabilities of the RIM. Implementations must map these accesses into appropriate references in their implementation model.
B.5.1 Class Attributes
Attributes of a class are accessed using the . operator. For example, to access the Act effectiveTime attribute of a class using the “myLocalAct” local variable name, you would reference it as myLocalAct.effectiveTime. Data type properties are accessed in a similar fashion. To obtain the low value of the effectiveTime, one would write myLocalAct.effectiveTime.low. An implementation would then map references to myLocalAct.effectiveTime.low to the appropriate language and implementation specific representation.
The use of references to models in the various act criteria enables implementations to provide implementation specific models for different kinds of information references. Thus, an implementation could map encounter.effectiveTime.low into a reference to the admitDate column of a visit table, but would map procedure.effectiveTime.low into the startTime column of the procedure table.
B.5.2 Associations
While RIM attributes and the properties of data types are uniquely named, a further challenge is accessing information from an associated RIM class while another RIM class is in scope. For example, consider the case of computing the average waiting time for a patient during an ED visit. Suppose that two observations are captured in the EHR, one being the patient arrival time, and the other being the time that they were first seen by a healthcare provider. These data of interest could be represented as shown below in the DataCriteriaSection.
<entry>
<localVariableName>Arrival</localVariableName>
<actCriteria>
...
<code code="441968004" codeSystem="2.16.840.1.113883.6.96"
displayName="time of arrival at healthcare facility" />
</actCriteria>
</entry>
<entry>
<localVariableName>Seen</localVariableName>
<actCriteria>
...
<code code="308930007" codeSystem="2.16.840.1.113883.6.96"
displayName="seen by health professional" />
</actCriteria>
</entry>
In order to compute a quality measure which reports the average wait time the measureObservationDefinition could be defined as follows:
<measureObservationDefinition>
...
<code code='AGGREGATE' codeSystem='2.16.840.1.113883.5.4'/>
<value><expression>Seen.effectiveTime - Arrival.effectiveTime</expression></value>
<methodCode code='AVERAGE' codeSystem='2.16.840.1.113883.5.84' />
<precondition>
<joinCondition>
<value>Seen.componentOf.encounter.id = Arrival.componentOf.encounter.id</value>
</joinCondition>
</precondition>
...
</measureObservationDefinition>
The joinCondition ensures that the Seen and Arrival effective times being compared are from the same encounter. To do so, however, they must reference the encounter identifier, found in a different class than the observation. In the XML representation of the RIM classes, these are referenced via the component act relationship. The ActRelationship class in the RIM is has a typeCode attribute, when given the value of “COMP” describes the type of actRelationship being referenced as a component. This typeCode attribute contains one of the values from the ActRelationshipType vocabulary. However, COMP is neither convenient nor memorable as used in an expression.
This issue was resolved in the HL7 R-MIM Designer by creating a set of rules for naming relationships used in an R-MIM diagram. This language proposes to use a subset of those names to access related classes from their parents or children.
There are four associations for which names are needed. Each type of association relates a source class and a target class. The name of the association depends upon the direction in which the association is made. For example, to relate a document to one of its addenda, you would say document.addendum, but to go from the addendum to the parent document, you would say document.addendumOf.
B.5.2.1 Act Relationship Association Members
Table 1 below lists the names to use to reference from one act to another via the Act Relationship association class. The first column of this table provides the ActRelationshipType. The second column provides the name of this association in the usual traversal direction, and the third column, when the association is read in the reverse direction.
The RIM Act Relationship class has members of its own. These are accessed via the name of the relationship. To access components of the associated act class, use the appropriate RIM act class name (act, encounter, observation, procedure, substanceAdministration, or supply). While not strictly necessary to disambiguate between the relationship and the target (or source act), use of the RIM class helps to clarify relationships enabling appropriate mapping in the implementation environment.
Table 1 Act Relationship Member Names
ActRelationshipType
|
Source->Target
|
Target->Source
|
APND
|
addendum
|
addendumOf
|
ARR
|
arrivedBy
|
arrivalFor
|
AUTH
|
authorization
|
authorizationOf
|
CAUS
|
causeOf
|
cause
|
CHRG
|
charge
|
chargeFor
|
CIND
|
contraindication
|
contraindicationFor
|
COMP
|
component
|
componentOf
|
COST
|
cost
|
costOf
|
COVBY
|
coverage
|
coverageOf
|
CREDIT
|
credit
|
creditTo
|
CTRLV
|
controlVariable
|
controlVariableFor
|
DEBIT
|
debit
|
debitTo
|
DEP
|
departedBy
|
departureFor
|
DOC
|
documentationOf
|
documentation
|
DRIV
|
derivedFrom
|
derivation
|
ELNK
|
links
|
linkedBy
|
EXPL
|
explanation
|
explanationFor
|
FLFS
|
inFulfillmentOf
|
fulfillment
|
GEN
|
generalization
|
specialization
|
GEVL
|
evaluationOf
|
evaluation
|
GOAL
|
goal
|
goalOf
|
INST
|
definition
|
instantiation
|
ITEMSLOC
|
itemStorage
|
itemStorageFor
|
LIMIT
|
limitation
|
limitationOf
|
MFST
|
manifestationOf
|
manifestation
|
MITGT
|
mitigates
|
mitigatedBy
|
MTCH
|
matchOf
|
match
|
NAME
|
conditionNamed
|
assignedConditionName
|
OBJC
|
maintenanceGoal
|
maintenanceGoalOf
|
OBJF
|
finalGoal
|
finalGoalOf
|
OCCR
|
occurrenceOf
|
occurrence
|
OPTN
|
option
|
optionFor
|
OREF
|
referencedOrder
|
referencedBy
|
OUTC
|
outcome
|
outcomeOf
|
PERT
|
pertinentInformation
|
pertainsTo
|
PRCN
|
precondition
|
preconditionFor
|
PREV
|
predecessor
|
successor
|
REFR
|
reference
|
referencedBy
|
REFV
|
referenceRange
|
referenceRangeFor
|
REV
|
reversalOf
|
reversal
|
RISK
|
risk
|
riskOf
|
RPLC
|
replacementOf
|
replacement
|
RSON
|
reason
|
reasonOf
|
SAS
|
startsAfterStartOf
|
startsBeforeStartOf
|
SCH
|
scheduleRequest
|
requestedBy
|
SEQL
|
sequelTo
|
sequel
|
SPRT
|
support
|
supportOf
|
SPRTBND
|
boundedSupport
|
boundedSupportOf
|
SUBJ
|
subject
|
subjectOf
|
SUCC
|
predecessor
|
successor
|
SUMM
|
summary
|
summaryOf
|
TRIG
|
trigger
|
triggerFor
|
UPDT
|
updateOf
|
update
|
VRXCRPT
|
verbatimExcerptFrom
|
verbatimExcerpt
|
XCRPT
|
excerptFrom
|
excerpt
|
XFRM
|
transformationOf
|
transformation
|
B.5.2.2 Participation Association Members
Participations are associations between and Act and a Role. Using the wait time example, suppose that instead of capturing the “time seen by a provider” in an observation, this information was (more correctly) modeled using the participation time of the encounter performer and the participation time of the service delivery location. In this case, the expression being computed would be:
<value>
<expression>EDVisit.performer.time.low - EDVisit.location.time.low</expression>
</value>
Table 2 below shows the names used to reference the participation class from the act in the second column, or from the role in the third column based on the participation type in the first column.
Unlike Act Relationships, participations are typically traversed in the direction from act to participation.
Table 2 Participation Type
ParticipationType
|
Act->Participant
|
Role->Participation
|
ADM
|
admitter
|
admission
|
ATND
|
attender
|
attenderOf
|
AUT
|
author
|
origination
|
AUTHEN
|
authenticator
|
authenticated
|
BBY
|
baby
|
babyOf
|
BEN
|
beneficiary
|
beneficiaryOf
|
CALLBCK
|
callBackContact
|
callBackAvailability
|
CON
|
consultant
|
consultation
|
COV
|
coveredParty
|
coveredPartyOf
|
CSM
|
consumable
|
consumedIn
|
CST
|
custodian
|
custodianship
|
DEV
|
device
|
deviceOf
|
DIR
|
directTarget
|
directTargetOf
|
DIS
|
discharger
|
discharge
|
DIST
|
distributer
|
distributed
|
DON
|
organDonor
|
organDonation
|
DST
|
destination
|
destinationOf
|
ELOC
|
dataEntryLocation
|
dataEntryLocationOf
|
ENT
|
dataEnterer
|
dataEntry
|
ESC
|
escort
|
escort
|
HLD
|
holder
|
contractHeld
|
IND
|
indirectTarget
|
indirectTargetOf
|
INF
|
informant
|
informationGiven
|
IRCP
|
informationRecipient
|
informationReceived
|
LA
|
legalAuthenticator
|
legallyAuthenticated
|
LOC
|
location
|
locationOf
|
NOT
|
notificationContact
|
contactFor
|
NRD
|
nonReusableDevice
|
nonReusableDeviceOf
|
ORG
|
origin
|
originOf
|
PPRF
|
primaryPerformer
|
performance
|
PRCP
|
primaryInformationRecipient
|
informationReceived
|
PRD
|
product
|
productOf
|
PRF
|
performer
|
performance
|
RCT
|
recordTarget
|
recordTargetOf
|
RCV
|
receiver
|
receiverOf
|
RDV
|
reusableDevice
|
reusableDeviceOf
|
REF
|
referrer
|
referral
|
REFB
|
subjectReferrer
|
subjectReferral
|
REFT
|
subjectReferredTo
|
referral
|
RESP
|
responsibleParty
|
responsibleFor
|
RML
|
remoteLocation
|
remoteLocationOf
|
SBJ
|
subject
|
subjectOf
|
SPC
|
specimen
|
specimenOf
|
SPRF
|
secondaryPerformer
|
performance
|
TRANS
|
transcriber
|
transcription
|
TRC
|
tracker
|
tracking
|
VIA
|
via
|
viaOf
|
VRF
|
verifier
|
verification
|
WIT
|
witness
|
witness
|
B.5.2.3 Role Link Association Members
Like Act Relationships, Role links are associations between two classes of the same type. They appear infrequently in HL7 Version 3 models. Table 3 below provides the names of role links from source to target in the second column, and from target to source in the third column, based on the role link type found in the first column.
Table 3 Role Link Assocation Names
Role Link Type
|
Source->Target
|
Target->Source
|
BACKUP
|
backupFor
|
backup
|
DIRAUTH
|
directAuthorityOver
|
directAuthority
|
INDAUTH
|
indirectAuthorithyOver
|
indirectAuthority
|
PART
|
part
|
partOf
|
REL
|
relatedTo
|
related
|
REPL
|
replacementOf
|
replacedBy
|
B.5.2.4 Player and Scoper Associations
A role is associated with two entities. The first entity, known as the “player” of the role, is a person, place, organization or thing which performed or participates in the act. The second entity, known as the “scoper” defines the scope in which the player acts. The Role Class and whether the entity is playing the role, or scoping the role determines the name of the association.
Table 4 below provides the names of role relationships to the playing entity in the second column, or the scoping entity in the third column, based on the role class found in the first column.
Table 4 Player and Scoper Associations
Role Class
|
Playing Entity
|
Scoping Entity
|
ACCESS
|
access
|
accessed
|
ACTI
|
activeIngredient
|
activeIngredientOf
|
ACTM
|
activeMoiety
|
moietyOf
|
ADMM
|
product
|
administeringParty
|
ADTV
|
additive
|
additiveOf
|
AFFL
|
affiliate
|
affiliator
|
AGNT
|
agent
|
representedEntity
|
ALQT
|
aliquot
|
aliquotSource
|
ASSIGNED
|
assignedPerson
|
representedOrganization
|
BASE
|
base
|
baseOf
|
BIRTHPL
|
birthplace
|
birthplaceFor
|
CAREGIVER
|
careGiver
|
careGiverOf
|
CASEBJ
|
caseSubject
|
caseMonitor
|
CASESBJ
|
caseSubject
|
caseReporter
|
CERT
|
certifiedParty
|
certifyingParty
|
CHILD
|
child
|
parent
|
CIT
|
citizenPerson
|
politicalEntity
|
COLR
|
color
|
colorAdditiveOf
|
COMPAR
|
commissioningParty
|
commissionedParty
|
CON
|
contactParty
|
representedParty
|
CONT
|
content
|
container
|
COVPTY
|
coveredParty
|
underwriter
|
CRED
|
credentialedPerson
|
credentialIssuer
|
CRINV
|
investigator
|
sponsoringOrganization
|
CRSPNSR
|
researchSponsor
|
researchAuthorizer
|
DEPO
|
deposited
|
location
|
DST
|
distributedProduct
|
distributor
|
ECON
|
emergencyContact
|
representedParty
|
EMP
|
employee
|
employer
|
EXPR
|
exposedParty
|
exposingParty
|
FLVR
|
flavor
|
flavorAdditiveOf
|
GEN
|
specializedKind
|
generalizedKind
|
GRIC
|
specializedKind
|
genericKind
|
GUAR
|
guarantor
|
promisor
|
GUARD
|
guardian
|
ward
|
HCFAC
|
healthcareFacility
|
identifyingAuthority
|
HLD
|
held
|
holder
|
HLTHCHRT
|
healthChart
|
subjectPerson
|
IACT
|
inactiveIngredient
|
inactiveIngredientOf
|
IDENT
|
identifiedEntity
|
identifyingAuthority
|
INGR
|
ingredient
|
ingredientOf
|
INST
|
instance
|
kindOf
|
INVSBJ
|
investigativeSubject
|
investigatorSponsor
|
ISLT
|
isolate
|
source
|
LIC
|
licensedPerson
|
licenseIssuer
|
LOCE
|
locatedEntity
|
location
|
MANU
|
manufacturedProduct
|
manufacturer
|
MBR
|
member
|
group
|
MIL
|
militaryPerson
|
militaryServiceOrganization
|
MNT
|
maintainedEntity
|
maintainer
|
NOK
|
nextOfKinContact
|
representedParty
|
NOT
|
notaryPublic
|
politicalEntity
|
OWN
|
ownedEntity
|
owner
|
PART
|
part
|
whole
|
PAT
|
patient
|
provider
|
PAYEE
|
payee
|
invoicingParty
|
PAYOR
|
invoicePayor
|
underwriter
|
POLHOLD
|
policyHolder
|
underwriter
|
PROV
|
healthcareProvider
|
identifyingAuthority
|
PRS
|
relationshipHolder
|
personalRelationshipWith
|
PRSN
|
presentingPerson
|
location
|
PRSV
|
preservative
|
preservativeOf
|
QUAL
|
qualifiedEntity
|
qualificationGrantingEntity
|
RESBJ
|
researchSubject
|
researchSponsor
|
RET
|
relailedProduct
|
retailer
|
RGPR
|
regulatedProduct
|
regulator
|
ROL
|
player
|
scoper
|
SCHED
|
schedulabeEntity
|
schedulingEntity
|
SCHOOL
|
educationalFacility
|
identifyingAuthority
|
SDLOC
|
location
|
serviceProvider
|
SGNOFF
|
signingAuthority
|
representedParty
|
SPEC
|
specimen
|
specimenSource
|
SPNSR
|
sponsor
|
underwriter
|
STAK
|
stakeholder
|
entityInWhichStakeIsHeld
|
STBL
|
stabilizer
|
stabilizerOf
|
STD
|
student
|
school
|
STOR
|
storedEntity
|
storageLocation
|
SUBS
|
prevailingEntity
|
subsumedEntity
|
SUBY
|
subsumingEntity
|
subsumedEntity
|
TERR
|
territory
|
governingEntity
|
THER
|
manufacturedProduct
|
manufacturer
|
UNDWRT
|
underwriter
|
underwrittenParty
|
WRTE
|
warranteedProduct
|
warrantingEntity
|
B.6 Language Runtime
TBD
See Simple Math for a proposal. Basically, steal JavaScript's Math package, and support a few constants (e.g., PI, E).
B.7 Extensibility
This language is intended to be extended to support implementation capabilities not specified in this appendix. Implementations are free to provide additional runtime capabilities (e.g., specialized functions), or language syntax (e.g., octal representation of numeric constants), or semantic constructs (e.g., a ternary conditional operator, such as the C/Java ?: operator). However, such extensions should not be expected to be interoperable across implementation platforms.
B.8 Notes on Syntax
- Whitespace is allowed where you would expect it to be (e.g., between operators and operands).
- There are no multi-step expressions. Line breaks have no syntactic meaning since each expression is expected to result in one value in the context of HQMF where these expressions are used.
- There are no comments because comments can be included in the XML where the expressions appear using existing XML commenting capabilities.
- Extra syntactic sugar (such as an optional + sign before a numeric literal to indicate that it is positive) have been eliminated to ensure compatibility across the widest variety of implementation platforms.
- There are no bit-wise operators because these were not necessary in the HQMF use cases expressed in developing this specification.
- There are no strings because these were similarly not necessary.
- There are no unsigned integers because integers sufficed for the computations in the HQMF use cases explored.
- There was no need to distinguish between float and double, so only one "real" type is specified.
- Float, unsigned, short and similar variations on numeric types are language optimizations which only further complicate things, so they were dropped.