R6 Ballot (2nd Draft)

Publish-box (todo)

10.1.12.1 Operation $stats on Observation

Orders and Observations icon Work Group Maturity Level: 3Trial Use Compartments: N/A

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 evaluates Observation resources having valueQuantity elements that have UCUM unit codes. Observations with a status of 'entered-in-error' will be excluded from the calculations.

Alternatively, the measure workflow pattern should be used when defining a quality measure (e.g. a description of how to calculate a particular measurement or set of measurements) as part of a workflow.

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 'durationorperiod`)
  • the set of statistical analyses to return (statistic)

Possible statistical analyses (see StatisticsCode):

  • average ("Average"): The mean icon of N measurements over the stated period.
  • maximum ("Maximum"): The maximum icon value of N measurements over the stated period.
  • minimum ("Minimum"): The minimum icon 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.
  • total-count ("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 icon of N measurements over the stated period.
  • std-dev ("Standard Deviation"): The standard deviation icon of N measurements over the stated period.
  • sum ("Sum"): The sum icon of N measurements over the stated period.
  • variance ("Variance"): The variance icon of N measurements over the stated period.
  • 20-percent ("20th Percentile"): The 20th Percentile icon of N measurements over the stated period.
  • 80-percent ("80th Percentile"): The 80th Percentile icon of N measurements over the stated period.
  • 4-lower ("Lower Quartile"): The lower Quartile icon Boundary of N measurements over the stated period.
  • 4-upper ("Upper Quartile"): The upper Quartile icon Boundary of N measurements over the stated period.
  • 4-dev ("Quartile Deviation"): The difference between the upper and lower Quartiles icon 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 icon.
  • kurtosis ("Kurtosis"): Kurtosis is a measure of the "tailedness" of the probability distribution of a real-valued random variable. Source: Wikipedia icon.
  • 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 icon 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 canonical 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 Scope 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 LOINC code = 2339-0 (Glucose [Mass/​volume] in Blood) will evaluate all relevant Observations with this code in Observation.code and Observation.component.code. For LOINC codes that are panels, e.g., 85354-9(Blood pressure panel with all children optional), the stats operation returns statistics for each of the individual panel measurements. That means it will include and evaluate all values grouped by code for all the individual observations that are: 1) referenced in .related for .related.type = 'has-member' and 2) component observations in Observation.component.

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 Statistics Code (Required)

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 parameter is absent or equal to "false" the limit parameter SHALL be ignored by the server

Out Parameters:
Name Scope Cardinality Type Binding Profile Documentation
statistics 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

If modifier extensions are present in the Observation, they must be accounted for by implementers. A modifier extension may affect the observation.value in a way that it should be excluded from the from the calculations.

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.12.1.1 Examples

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

GET [base]/Observation/$stats?subject=Patient/123&code=85354-9&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 (8462-4)
  and one for the systolic components (8480-6), because the requested LOINC code is a panel code
-->
<Parameters xmlns="http://hl7.org/fhir">
  <parameter>
    <name value="statistics"/>
    <resource>
      <Observation>
        <status value="final"/>
        <code>
          <coding>
            <system value="http://loinc.org"/>
            <code value="8480-6"/>
            <display value="Systolic blood pressure"/>
          </coding>
        </code>
        <subject>
           <reference value="Patient/123"/>
        </subject>
        <effectivePeriod>
           <start value="2016-05-25T19:26:16Z"/>
           <end value="2016-05-25T20: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="https://www.hl7.org/fhir/valueset-observation-statistics"/>
                 <code value="average"/>
                 <display value="Average"/>
              </coding>
           </code>
           <valueQuantity>
              <value value="121.8"/>
              <unit value="mmHg"/>
              <system value="http://unitsofmeasure.org"/>
              <code value="mm[Hg]"/>
           </valueQuantity>
        </component>
        <component>
           <!--  the max parameter code -->
           <code>
              <coding>
                 <system value="https://www.hl7.org/fhir/valueset-observation-statistics"/>
                 <code value="max"/>
                 <display value="Maximum"/>
              </coding>
           </code>
           <valueQuantity>
              <value value="136"/>
              <unit value="mmHg"/>
              <system value="http://unitsofmeasure.org"/>
              <code value="mm[Hg]"/>
           </valueQuantity>
        </component>
        <component>
           <!--  the min parameter code -->
           <code>
              <coding>
                 <system value="https://www.hl7.org/fhir/valueset-observation-statistics"/>
                 <code value="min"/>
                 <display value="Minimum"/>
              </coding>
           </code>
           <valueQuantity>
              <value value="110"/>
              <unit value="mmHg"/>
              <system value="http://unitsofmeasure.org"/>
              <code value="mm[Hg]"/>
           </valueQuantity>
        </component>
        <component>
           <!--  the count parameter code -->
           <code>
              <coding>
                <system value="https://www.hl7.org/fhir/valueset-observation-statistics"/>
                  <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>
  <parameter>
    <name value="statistics"/>
    <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-25T19:26:16Z"/>
           <end value="2016-05-25T20: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="https://www.hl7.org/fhir/valueset-observation-statistics"/>
                 <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="https://www.hl7.org/fhir/valueset-observation-statistics"/>
                 <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="https://www.hl7.org/fhir/valueset-observation-statistics"/>
                 <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="https://www.hl7.org/fhir/valueset-observation-statistics"/>
                 <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>

 

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