Observation - FHIR v3.0.2

FHIR Release 3 (STU)

This page is part of the FHIR Specification (v3.0.2: STU 3). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3

10.1.20 Resource Observation - Operations

Orders and Observations Work Group Maturity Level: 5 Trial Use Compartments: Device, Encounter, Patient, Practitioner, RelatedPerson

This resource has 2 operations associated with it:

$stats Observation Statistics

$lastn Last N Observations Query

For more information about operations, including how they are invoked, see Operations.

10.1.20.1 Observation Statistics

The Statistics operation performs a set of statistical calculations on a set of clinical measurements such as a blood pressure as stored on the server. This operation is focused on Observation resources with valueQuantity elements that have UCUM unit codes.

The set of Observations is defined by 4 parameters:

the subject of the observations for which the statistics are being generated (subject)
which observations to generate statistics for (code and system, or coding)
the time period over which to generate statistics 'duration or period)
the set of statistical analyses to return (statistic)

Possible statistical analyses (see StatisticsCode):

average ("Average"): The mean of N measurements over the stated period
maximum ("Maximum"): The maximum value of N measurements over the stated period
minimum ("Minimum"): The minimum value of N measurements over the stated period
count ("Count"): The [number] of valid measurements over the stated period that contributed to the other statistical outputs
totalcount ("Total Count"): The total [number] of valid measurements over the stated period, including observations that were ignored because they did not contain valid result values
median ("Median"): The median of N measurements over the stated period
std-dev ("Standard Deviation"): The standard deviation of N measurements over the stated period
sum ("Sum"): The sum of N measurements over the stated period
variance ("Variance"): The variance of N measurements over the stated period
20-percent ("20th Percentile"): The 20th Percentile of N measurements over the stated period
80-percent ("80th Percentile"): The 80th Percentile of N measurements over the stated period
4-lower ("Lower Quartile"): The lower Quartile Boundary of N measurements over the stated period
4-upper ("Upper Quartile"): The upper Quartile Boundary of N measurements over the stated period
4-dev ("Quartile Deviation"): The difference between the upper and lower Quartiles is called the Interquartile range. (IQR = Q3-Q1) Quartile deviation or Semi-interquartile range is one-half the difference between the first and the third quartiles.
5-1 ("1st Quintile"): The lowest of four values that divide the N measurements into a frequency distribution of five classes with each containing one fifth of the total population
5-2 ("2nd Quintile"): The second of four values that divide the N measurements into a frequency distribution of five classes with each containing one fifth of the total population
5-3 ("3rd Quintile"): The third of four values that divide the N measurements into a frequency distribution of five classes with each containing one fifth of the total population
5-4 ("4th Quintile"): The fourth of four values that divide the N measurements into a frequency distribution of five classes with each containing one fifth of the total population
skew ("Skew"): Skewness is a measure of the asymmetry of the probability distribution of a real-valued random variable about its mean. The skewness value can be positive or negative, or even undefined. Source: Wikipedia
kurtosis ("Kurtosis"): Kurtosis is a measure of the "tailedness" of the probability distribution of a real-valued random variable. Source: Wikipedia
regression ("Regression"): Linear regression is an approach for modeling two-dimensional sample points with one independent variable and one dependent variable (conventionally, the x and y coordinates in a Cartesian coordinate system) and finds a linear function (a non-vertical straight line) that, as accurately as possible, predicts the dependent variable values as a function of the independent variables. Source: Wikipedia This Statistic code will return both a gradient and an intercept value.

If successful, the operation returns an Observation resource for each code with the results of the statistical calculations as component value pairs where the component code = the statistical code. The Observation also contains the input parameters patient,code and duration parameters. If unsuccessful, an OperationOutcome with an error message will be returned.

The client can request that all the observations on which the statistics are based be returned as well, using the include parameter. If an include parameter is specified, a limit may also be specified; the sources observations are subsetted at the server's discretion if count > limit. This functionality is included with the intent of supporting graphical presentation

The official URL for this operation definition is

 http://hl7.org/fhir/OperationDefinition/Observation-stats

Formal Definition (as a OperationDefinition).

URL: [base]/Observation/$stats

This is an idempotent operation

In Parameters:

Name Cardinality Type Binding Profile Documentation

subject 1..1 uri

The subject of the relevant Observations, which has the value of the Observation.subject.reference. E.g. 'Patient/123'. Reference can be to an absolute URL, but servers only perform stats on their own observations

code 0..* string

The test code(s) upon which the statistics are being performed. Provide along with a system, or as a coding. For example, the code = "45667-2" will evaluate all relevant Observations with this code in Observation.code. For LOINC codes that are panels, (e.g. 55284-4) this means to include all the individual codes that are part of a panel

system 0..1 uri

The system for the code(s). Or provide a coding instead

coding 0..* Coding

The test code upon which the statistics are being performed, as a Coding

duration 0..1 decimal

The time period of interest given as hours. For example, the duration = "1" represents the last hour - the time period from on hour ago to now

period 0..1 Period

The time period over which the calculations to be performed, if a duration is not provided

statistic 1..* code

average|max|min|count The statistical operations to be performed on the relevant operations. Multiple statistics operations can be specified. These codes are defined here

include 0..1 boolean

Whether to return the observations on which the statistics are based

limit 0..1 positiveInt

If an include parameter is specified, a limit may also be specified to limit the number of source Observations returned. If the include paramter is absent or equal to "false" the limit parameter SHALL be ignored by the server

Out Parameters:

Name Cardinality Type Binding Profile Documentation

return 1..* Observation

A set of observations, one observation for each code, each containing one component for each statistic. The Observation.component.code contains the statistic, and is relative to the Observation.code and cannot be interpreted independently. The Observation will also contain a subject, effectivePeriod, and code reflecting the input parameters. The status is fixed to final.

source 0..* Observation

Source observations on which the statistics are based

This operation cannot be performed on observations that the user is not authorized to see. It is assumed that the server has identified and secured the context appropriately, and can either associate the authorization context with a single patient, or determine whether the context has the rights to the nominated patient, if there is one. If there is no nominated patient (e.g. the operation is invoked at the system level) and the context is not associated with a single patient record, then the server should return an error. Specifying the relationship between the context, a user and patient records is outside the scope of this specification.

10.1.20.1.1 Examples

Get the average, min, max and count of a series of BP measurements for a patient (Request):

GET [base]/Observation/$stats?subject=Patient/123&code=55284-4&system=http://loinc.org&duration=1&statistic=average&statistic=min&statistic=max&statistic=count

Response:

<?xml version="1.0" encoding="UTF-8"?>
<!--
 The outcome for this particular operation is 2 Observation resources - one for the diastolic 
 and one for the systolic components, because the requested LOINC code is a panel code 
-->
<Parameters xmlns="http://hl7.org/fhir">
 <parameter>
 <name value="return"/>
 <resource>
 <Observation>
 <status value="final"/>
 <code>
 <coding>
 <system value="http://loinc.org"/>
 <code value="8462-4"/>
 <display value="Diastolic blood pressure"/>
 </coding>
 </code>
 <subject>
 <reference value="Patient/123"/>
 </subject>
 <effectivePeriod>
 <start value="2016年05月25日T19:26:16Z"/>
 <end value="2016年05月25日T20:26:16Z"/>
 </effectivePeriod>
 <!--The Observation.component.code is relative to the Observation.code and cannot be interpreted independently.-->
 <component>
 <code>
 <!-- the average parameter code -->
 <coding>
 <system value="http://hl7.org/fhir/observation-paramcode"/>
 <code value="average"/>
 <display value="Average"/>
 </coding>
 </code>
 <valueQuantity>
 <value value="79.7"/>
 <unit value="mmHg"/>
 <system value="http://unitsofmeasure.org"/>
 <code value="mm[Hg]"/>
 </valueQuantity>
 </component>
 <component>
 <!-- the max parameter code -->
 <code>
 <coding>
 <system value="http://hl7.org/fhir/observation-paramcode"/>
 <code value="max"/>
 <display value="Maximum"/>
 </coding>
 </code>
 <valueQuantity>
 <value value="110"/>
 <unit value="mmHg"/>
 <system value="http://unitsofmeasure.org"/>
 <code value="mm[Hg]"/>
 </valueQuantity>
 </component>
 <component>
 <!-- the min parameter code -->
 <code>
 <coding>
 <system value="http://hl7.org/fhir/observation-paramcode"/>
 <code value="min"/>
 <display value="Minimum"/>
 </coding>
 </code>
 <valueQuantity>
 <value value="56"/>
 <unit value="mmHg"/>
 <system value="http://unitsofmeasure.org"/>
 <code value="mm[Hg]"/>
 </valueQuantity>
 </component>
 <component>
 <!-- the count parameter code -->
 <code>
 <coding>
 <system value="http://hl7.org/fhir/observation-paramcode"/>
 <code value="min"/>
 <display value="Minimum"/>
 </coding>
 </code>
 <valueQuantity>
 <value value="7"/>
 <system value="http://unitsofmeasure.org"/>
 <code value="{observations}"/>
 </valueQuantity>
 </component>
 </Observation>
 </resource>
 </parameter>
 <parameter>
 <name value="return"/>
 <resource>
 <Observation>
 <status value="final"/>
 <code>
 <coding>
 <system value="http://loinc.org"/>
 <code value="8462-4"/>
 <display value="Diastolic blood pressure"/>
 </coding>
 </code>
 <subject>
 <reference value="Patient/123"/>
 </subject>
 <effectivePeriod>
 <start value="2016年05月25日T19:26:16Z"/>
 <end value="2016年05月25日T20:26:16Z"/>
 </effectivePeriod>
 <!--The Observation.component.code is relative to the Observation.code and cannot be interpreted independently.-->
 <component>
 <code>
 <!-- the average parameter code -->
 <coding>
 <system value="http://hl7.org/fhir/observation-paramcode"/>
 <code value="average"/>
 <display value="Average"/>
 </coding>
 </code>
 <valueQuantity>
 <value value="79.7"/>
 <unit value="mmHg"/>
 <system value="http://unitsofmeasure.org"/>
 <code value="mm[Hg]"/>
 </valueQuantity>
 </component>
 <component>
 <!-- the max parameter code -->
 <code>
 <coding>
 <system value="http://hl7.org/fhir/observation-paramcode"/>
 <code value="max"/>
 <display value="Maximum"/>
 </coding>
 </code>
 <valueQuantity>
 <value value="110"/>
 <unit value="mmHg"/>
 <system value="http://unitsofmeasure.org"/>
 <code value="mm[Hg]"/>
 </valueQuantity>
 </component>
 <component>
 <!-- the min parameter code -->
 <code>
 <coding>
 <system value="http://hl7.org/fhir/observation-paramcode"/>
 <code value="min"/>
 <display value="Minimum"/>
 </coding>
 </code>
 <valueQuantity>
 <value value="56"/>
 <unit value="mmHg"/>
 <system value="http://unitsofmeasure.org"/>
 <code value="mm[Hg]"/>
 </valueQuantity>
 </component>
 <component>
 <!-- the count parameter code -->
 <code>
 <coding>
 <system value="http://hl7.org/fhir/observation-paramcode"/>
 <code value="count"/>
 <display value="Count"/>
 </coding>
 </code>
 <valueQuantity>
 <value value="7"/>
 <system value="http://unitsofmeasure.org"/>
 <code value="{observations}"/>
 </valueQuantity>
 </component>
 </Observation>
 </resource>
 </parameter> 
</Parameters>

10.1.20.2 Last N Observations Query

The lastn query meets the common need for searching for the most recent or last n=number of observations for a subject. For example, retrieving the last 5 temperatures for a patient to view trends or fetching the most recent laboratory results or vitals signs. To ask a server to return the last n=number of observations, the lastn queryuses the normal search parameters defined for the Observation resource. However, rather than their normal use, they are interpreted as inputs - i.e.. instead of requiring that the resources literally contain the search parameters, they are passed to a server algorithm of some kind that uses them to determine the most appropriate matches.

The response from an lastn query is a set of observations:

filtered by additional parameters
'GROUP BY' Observation.code
sorted from most recent to the oldest
limited to the number of requested responses per group specified by the optional max query parameter
If no maximum number is given then only the most recent Observation in each group is returned.

The set of returned observations should represent distinct real world observations and not the same observation with changes in status or versions. If there are no matches, the lastn query SHALL return an empty search set with no error, but may include an operation outcome with further advice.

The official URL for this operation definition is

 http://hl7.org/fhir/OperationDefinition/Observation-lastn

Formal Definition (as a OperationDefinition).

URL: [base]/Observation/$lastn

This is an idempotent operation

In Parameters:

Name Cardinality Type Binding Profile Documentation

max 0..1 positiveInt

max is an optional input parameter to the lastn query operation. It is used to specify the maximum number of Observations to return from each group. For example for the query "Fetch the last 3 results for all vitals for a patient" max = 3.

Out Parameters:

Name Cardinality Type Binding Profile Documentation

return 1..1 Bundle

The set of most recent N Observations that match the lastn query search criteria.

Note: as this the only out parameter, it is a resource, and it has the name 'return', the result of this operation is returned directly as a resource

The key differences between this query operation and simply searching Observation using the combination of _count and _sort parameters are:

The lastn query returns only the last N resource grouped by code. Using the _count query method doesn't restrict the total mathches so you may need to page through several "A" Observations before getting to Observation "B".
The server is responsible for grouping the observations by codes. This frees the client from needing to determine which codes she should ask for.

10.1.20.2.1 Examples

1): Fetch the last 3 results for all vitals for a patient 2): Fetch the last lab results for a patient 3): Fetch the last 3 blood pressures, respiratory rate and heart rates for a patient (Request):

1) GET [base]/Observation$lastn?max=3&patient=Patient/123&category=vital-signs
--------------------------------------------
2) GET [base]/Observation$lastn?patient=Patient/123&category=laboratory
--------------------------------------------
3) GET [base]/Observation$lastn?max=3&patient=Patient/123&category=vital-signs&code=9279-1,8867-4,85354-9

1): A Server returns from an imaginary Last N algorithm the last 3 of 9 different vital signs observations on a patient. e.g. body temperature, body weight, body height... (truncated for readability) 2): A Server returns from an imaginary Last N algorithm the last laboratory observations for a patient. e.g. CBC Panel, UA, Chem Panel, Lipid Panel components and HbA1c, (truncated for readability) 3): A Server returns from an imaginary Last N algorithm the last 3 blood pressures, respiratory rate and heart rates for a patient as specified by code from the request. (truncated for readability) (Response):

=========================== Example 1 ============================
HTTP/1.1 200 OK
[other headers]
{
 "resourceType": "Bundle",
 "id": "26419249-18b3-45de-b10e-dca0b2e72b",
 "meta": {
 "lastUpdated": "2017年02月18日T03:28:49Z"
 },
 "type": "searchset",
 "total": 27,
 // the patient temperature was being taken several times a day
 "entry": [{
 "fullUrl": "http://server/path/Observation/20170219-06temp",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219temp",
 .. snip ...
 ,{
 "fullUrl": "http://server/path/Observation/20170219-05temp",
 "resource": {
 "resourceType": "Observation",
 "id": "20170218temp",
 .. snip ...
 }
 ,{
 "fullUrl": "http://server/path/Observation/20170219-04temp",
 "resource": {
 "resourceType": "Observation",
 "id": "20170217temp",
 .. snip ...
 },
 // the patient was being weighed daily
 {
 "fullUrl": "http://server/path/Observation/20170219weight",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219weight",
 .. snip ...
 ,{
 "fullUrl": "http://server/path/Observation/20170218weight",
 "resource": {
 "resourceType": "Observation",
 "id": "20170218weight",
 .. snip ...
 }
 ,{
 "fullUrl": "http://server/path/Observation/20170217weight",
 "resource": {
 "resourceType": "Observation",
 "id": "20170217weight",
 .. snip ...
 },
 // height was recorded occasionally over the years
 {
 "fullUrl": "http://server/path/Observation/20170101height",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219height",
 .. snip ...
 ,{
 "fullUrl": "http://server/path/Observation/20160101height",
 "resource": {
 "resourceType": "Observation",
 "id": "20160101height",
 .. snip ...
 }
 ,{
 "fullUrl": "http://server/path/Observation/20131001height",
 "resource": {
 "resourceType": "Observation",
 "id": "20131001height",
 .. snip ...
 }
 ]
}
----------------------------------
=========================== Example 2 ============================
HTTP/1.1 200 OK
[other headers]
{
 "resourceType": "Bundle",
 "id": "26419249-18b3-45de-b10e-dca0b2e72b",
 "meta": {
 "lastUpdated": "2017年02月18日T03:28:49Z"
 },
 "type": "searchset",
 "total": 45,
 // the patient's last CBC Panel component observations
 "entry": [{
 "fullUrl": "http://server/path/Observation/20170219-CBCPanel-RBCs",
 "resource": {
 "resourceType": "Observation",
 "id": "0170219-CBCPanel-RBCs",
 ... snip ...
 "code" : {
 "coding" : [
 {
 "system" : "http://loinc.org",
 "code" : "789-8",
 "display" : "RBC # Bld Auto"
 }
 ],
 "text" : "RBC # Bld Auto"
 },
 ...snip....
 },
 // the rest of the patient CBC Panel components observations
 { ...snip...
 },
 // the patient's last UA Panel component observations
 {
 "fullUrl": "http://server/path/Observation/20160610-UA-Color",
 "resource": {
 "resourceType": "Observation",
 "id": "20160610-UA-Color",
 .. snip ...
 "code" : {
 "coding" : [
 {
 "system" : "http://loinc.org",
 "code" : "5778-6",
 "display" : "Color of Urine"
 }
 ],
 "text" : "COLOR"
 },
 ...snip....
 },
 // the rest of the patient UA Panel component observations
 { ...snip...
 },
 // the patient's last Metabolic Panel component observations
 {
 "fullUrl": "http://server/path/Observation/20170219MetPanel-Sodium",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219MetPanel-Sodium",
 ... snip ...
 "code" : {
 "coding" : [
 {
 "system" : "http://loinc.org",
 "code" : "2951-2",
 "display" : "Sodium SerPl-sCnc"
 }
 ],
 "text" : "Sodium SerPl-sCnc"
 },
 ...snip....
 },
 // the rest of the patient Metabolic Panel component observations
 { ...snip...
 },
 // the patient Lipase Panel components observations
 {
 "fullUrl": "http://server/path/Observation/20170219LipidPanel-Chol",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219LipidPanel-Chol",
 ... snip ...
 "code": {
 "coding": [
 {
 "system": "http://loinc.org",
 "code": "14647-2",
 "display": "Cholesterol [Moles/volume] in Serum or Plasma"
 }
 ],
 "text": "Cholesterol"
 },
 ...snip....
 },
 // the patient HbA1c observation
 {
 "fullUrl": "http://server/path/Observation/20170219HbA1c",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219HbA1c",
 ... snip ...
 "code": {
 "coding": [
 {
 "system": "http://loinc.org",
 "code": "4548-4",
 "display": "Hemoglobin A1c/Hemoglobin.total in Blood"
 }
 ],
 "text": "HbA1c"
 },
 ...snip....
 }
 ]
}
----------------------------------
=========================== Example 3 ============================
HTTP/1.1 200 OK
[other headers]
{
 "resourceType": "Bundle",
 "id": "26419249-18b3-45de-b10e-dca0b2e72b",
 "meta": {
 "lastUpdated": "2017年02月18日T03:28:49Z"
 },
 "type": "searchset",
 "total": 9,
 // Returns the patient's last 3 code = 9279-1 Respiratory Rate observations All from 20170219
 "entry": [{
 "fullUrl": "http://server/path/Observation/20170219-06RespRate",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219-06RespRate",
 .. snip ...
 "code": {
 "coding": [
 {
 "system": "http://loinc.org",
 "code": "9279-1",
 "display": "Respiratory rate"
 }
 ],
 "text": "Respiratory rate"
 },
 .. snip ...
 ,{
 "fullUrl": "http://server/path/Observation/20170219-05RespRate",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219-05RespRate",
 .. snip ...
 }
 ,{
 "fullUrl": "http://server/path/Observation/20170219-04RespRate",
 "resource": {
 "resourceType": "Observation",
 "id": "20170217-04RespRate",
 .. snip ...
 },
 // Returns the patient's last 3 code = 8867-4 Heart Rate observations All from 20170219
 // the patient was being weighed daily
 {
 "fullUrl": "http://server/path/Observation/20170219-06HeartRate",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219-06HeartRate",
 .. snip ...
 ],
 "code": {
 "coding": [
 {
 "system": "http://loinc.org",
 "code": "8867-4",
 "display": "Heart rate"
 }
 ],
 "text": "Heart rate"
 ...snip...
 ,{
 "fullUrl": "http://server/path/Observation/20170219-05HeartRate",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219-05HeartRate",
 .. snip ...
 }
 ,{
 "fullUrl": "http://server/path/Observation/20170219-04HeartRate",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219-04HeartRate",
 .. snip ...
 },
 // Returns the patient's last 3 code = 85354-9 Blood pressure systolic and diastolic All from 20170219
 {
 "fullUrl": "http://server/path/Observation/20170219-06BloodPressure",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219-06BloodPressure",
 .. snip ...
 "code": {
 "coding": [
 {
 "system": "http://loinc.org",
 "code": "85354-9",
 "display": "Bood pressure panel with all children optional"
 }
 ],
 "text": "Blood pressure systolic & diastolic"
 },
 ...snip...
 "component": [
 {
 "code": {
 "coding": [
 {
 "system": "http://loinc.org",
 "code": "8480-6",
 "display": "Systolic blood pressure"
 },
 {
 ...snip...
 {
 "code": {
 "coding": [
 {
 "system": "http://loinc.org",
 "code": "8462-4",
 "display": "Diastolic blood pressure"
 }
 ]
 },
 ...snip....
 ,{
 "fullUrl": "http://server/path/Observation/20170219-05BloodPressure",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219-05BloodPressure",
 .. snip ...
 }
 ,{
 "fullUrl": "http://server/path/Observation/20170219-04BloodPressure",
 "resource": {
 "resourceType": "Observation",
 "id": "20170219-04BloodPressure",
 .. snip ...
 }
 ]
}