Laboratory Results
Back to Argonaut Implementation Guide
**********************PLEASE NOTE******************************** This guide is no longer being actively maintained and updated. On January 1st 2017, This guide is being superseded by the online version of the Argonaut-DSTU2 Implemenation Guide. hosted at: http://fhir.org/guides/argonaut The working CI build is avaible now at : http://build.fhir.org/ig/Healthedata1/Argo-DSTU2/
Contents
Introduction
The Argonaut Laboratory Results guide provides the API documentation for searching and fetching Laboratory Results. This IG covers two resources - Observation and DiagnosticReport - because labaratory results are grouped and summarized using reports. This IG is based on the Data Access Framework (DAF) Laboratory Results. The search criteria provided in the Quick Start are intended to support the 2015 Edition ONC Certification criterion Data Category Request 170.315(g)(8).
Minimum Requirements
Clients
DiagnosticReport
- A client has connected to a server and fetched all of a patient's laboratory diagnostic reports by searching by category using GET [base]/DiagnosticReport?patient=[id]&category=LAB.
- A client has connected to a server and fetched all of a patient's laboratory diagnostic reports searching by category code and date range using GET [base]/DiagnosticReport?patient=[id]&category=LAB&date=[date]{&date=[date]}.
- A client has connected to a server and fetched all of all of a patient's laboratory diagnostic reports searching by category and code using GET [base]/DiagnosticReport?patient=[id]&category=LAB&code=[LOINC].
- A client SHOULD be capable of connecting to a server and fetching any of a patient's laboratory diagnostic reports searching by category and one or more codes and date range using GET [base]/DiagnosticReport?patient=[id]&category=LAB&code=[LOINC1{,LOINC2,LOINC3,...}]&date=[date]{&date=[date]}.
Observation
- A client has connected to a server and fetched all of a patient's laboratory results by searching by category using GET [base]/Observation?patient=[id]&category=laboratory.
- A client has connected to a server and fetched all of a patient's laboratory results searching by category code and date range using GET [base]/Observation?patient=[id]&category=laboratory&date=[date]{&date=[date]}.
- A client has connected to a server and fetched all of all of a patient's laboratory results searching by category and code using GET [base]/Observation?patient=[id]&category=laboratory&code=[LOINC].
- A client SHOULD be capable of connecting to a server and fetching any of a patient's laboratory results searching by category and one or more codes and date range using GET [base]/Observation?patient=[id]&category=laboratory&code=[LOINC1{,LOINC2,LOINC3,...}]&date=[date]{&date=[date]}.
Servers
DiagnosticReport
- A server is capable of returning all of a patient's laboratory diagnostic reports queried by category using GET [base]/DiagnosticReport?patient=[id]&category=LAB.
- A server is capable of returning all of a patient's laboratory diagnostic reports queried by category code and date range using GET [base]/DiagnosticReport?patient=[id]&category=LAB&date=[date]{&date=[date]}.
- A server is capable of returning all of a patient's laboratory diagnostic reports queried by category and code using GET [base]/DiagnosticReport?patient=[id]&category=LAB&code=[LOINC].
- A server SHOULD be capable of returning all of a patient's laboratory diagnostic reports queried by category and one or more codes and date range using GET [base]/DiagnosticReport?patient=[id]&category=LAB&code=[LOINC1{,LOINC2,LOINC3,...}]&date=[date]{&date=[date]}.
Observation
- A server is capable of returning all of a patient's laboratory results queried by category using GET [base]/Observation?patient=[id]&category=laboratory.
- A server is capable of returning all of a patient's laboratory results queried by category code and date range using GET [base]/Observation?patient=[id]&category=laboratory&date=[date]{&date=[date]}.
- A server is capable of returning all of a patient's laboratory results queried by category and code using GET [base]/Observation?patient=[id]&category=laboratory&code=[LOINC].
- A server SHOULD be capable of returning all of a patient's laboratory results queried by category and one or more codes and date range using GET [base]/Observation?patient=[id]&category=laboratory&code=[LOINC1{,LOINC2,LOINC3,...}]&date=[date]{&date=[date]}.
Mandatory Data Elements
The following data-elements in the DiagnosticReport and Observation resources are mandatory (i.e data MUST be present). These are presented below in simple human-readable explanation and a more thorough summary of the requirements. Refer to the tables for additional quidance and examples for the various laboratory tests. Both DiagnosticReport and Observation contain structures to group panels of Observations and both options are presented below. Both approaches are currently supported in this guide.
DiagnosticReport
When lab test or lab panel, such as CBC, is ordered, a DiagnosticReport represents the order fulfillment and references each of the resulting discrete Observations within that panel.
Each DiagnosticReport must have:
- a patient
- a code (preferably a LOINC code) which tells you what is being measured
- note: additional codes that translate or map to these are allowed - e.g. system specific codes
- at least one result (an Observation reference)
- a status
- a category code of 'LAB'
- note: additional category codes that translate or map to these are allowed - e.g. more specific category codes such as "CH" (chemistry)
- a time indicating when the measurement was taken
- a time indicating when the measurement was reported
- who issues the report
Example DiagnosticReports
The attached table lists LOINC panels for chemistry, hematology(cbc) and urinalysis results. This Argonaut profile does not make the presence or absence of any of these mandatory and is provided for guidance only.
LOINC # | Long Common Name | Comment | Example |
---|---|---|---|
24323-8 | Comprehensive metabolic 2000 panel - Serum or Plasma | Panel of Common Blood Chemistries | Example |
58410-2 | Complete blood count (hemogram) panel - Blood by Automated count | Panel of Common Hematology Tests | Example |
24356-8 | Urinalysis complete panel - Urine | Panel of Common Urine Tests | Example |
Complete Summary of the Mandatory Requirements
- One patient in DiagnosticReport.subject
- One status in DiagnosticReport.status
- One category in DiagnosticReport.category which must have:
- a fixed DiagnosticReport.category.coding.system="http://hl7.org/fhir/valueset-diagnostic-service-sections.html"
- a fixed DiagnosticReport.category.coding.code="LAB"
- One code in DiagnosticReport.code which must have if available:
- a fixed DiagnosticReport.code.coding.system="http://loinc.org"
- a LOINC code in DiagnosticReport.code.coding.code
- Other additional codes are allowed - e.g. system specific codes. All codes SHALL have an system value
- One or more DiagnosticReport.result
- DiagnosticReport.result.reference reference the Observations that are part of this diagnostic report.
- A date and time in DiagnosticReport.effectiveDateTime or DiagnosticReport.effectivePeriod
- A date and time in DiagnosticReport.issued
- A practitioner or organization DiagnosticReport.performer
Observation
Each Observation represents an individual laboratory test and result value, a "nested" panel (such as a microbial susceptibility panel) which references other observations, or rarely a laboratory test with component result values.
Each Observation must have:
- a patient
- a LOINC code, if available, which tells you what is being measured
- note: additional codes that translate or map to these are allowed - e.g. system specific codes
- a result value and if the result value is a numeric quantity, a standard UCUM unit
- note: if there is no result then you have to supply a reason unless Observation is being used to group a panel then there is no value. Instead, it just includes composite values or related links
- a status
- a category code of 'laboratory'
- note: additional category codes that translate or map to these are allowed - e.g. more specific category codes such as "chemistry', SNOMED CT concepts, system specific codes
Each Observation should have:
- a time indicating when the measurement was taken
- a reference range if available
Example Laboratory tests and results
The attached table is derived from the LOINC Top 2000+ Lab Observations and lists LOINC panel and observation codes for quantitative and qualitative tests for chemistry, hematology(cbc) and urinalysis results. It also lists the corresponding UCUM units of measure codes for quantitative tests. The qualitative results include both 'ordinal' and 'nominal' scale. This Argonaut profile does not make the presence or absence of any of these mandatory and is provided for guidance only.
LOINC # | Long Common Name | UCUM | Comment | Example | |
---|---|---|---|---|---|
2160-0 | Creatinine [Mass/volume] in Serum or Plasma | mg/dL | Quantitative Test | Example | |
718-7 | Hemoglobin [Mass/volume] in Blood | g/dL | Quantitative Test, This is the the code included in the CBC auto. It is NOT obtained via the automated counting but uses a chemistry method just like most other hemoglobins | Example | |
2823-3 | Potassium [Moles/volume] in Serum or Plasma | mmol/L | Quantitative Test | Example | |
2951-2 | Sodium [Moles/volume] in Serum or Plasma | mmol/L | Quantitative Test | Example | |
3094-0 | Urea nitrogen [Mass/volume] in Serum or Plasma | mg/dL | Quantitative Test, Usually called BUN | Example | |
2028-9 | Carbon dioxide, total [Moles/volume] in Serum or Plasma | mmol/L | Quantitative Test | Example | |
2075-0 | Chloride [Moles/volume] in Serum or Plasma | mmol/L | Quantitative Test | Example | |
789-8 | Erythrocytes [#/volume] in Blood by Automated count | 10*6/uL | Quantitative Test | Example | |
786-4 | Erythrocyte mean corpuscular hemoglobin concentration [Mass/volume] by Automated count | g/dL | Quantitative Test | Example | |
785-6 | Erythrocyte mean corpuscular hemoglobin [Entitic mass] by Automated count | pg | Quantitative Test | Example | |
17861-6 | Calcium [Mass/volume] in Serum or Plasma | mg/dL | Quantitative Test | Example | |
2339-0 | Glucose [Mass/volume] in Blood | mg/dL | Quantitative Test | Example | |
1975-2 | Bilirubin.total [Mass/volume] in Serum or Plasma | mg/dL | Quantitative Test, Total bilirubin = direct + indirect. | Example | |
770-8 | Neutrophils/100 leukocytes in Blood by Automated count | % | Quantitative Test, This cell type is counted by all modern automated differential machines; so most results will be reported under the LOINC code with method of automated count. | Example | |
5778-6 | Color of Urine | Qualitative Test (Nominal) | Example | ||
32167-9 | Clarity of Urine | Qualitative Test (Nominal) | Example | ||
25428-4 | Glucose [Presence] in Urine by Test strip | Qualitative Test (Ordinal) | Example | ||
5770-3 | Bilirubin.total [Presence] in Urine by Test strip | Qualitative Test (Ordinal) | Example | ||
2514-8 | Ketones [Presence] in Urine by Test strip | Qualitative Test (Ordinal) | Example | ||
5811-5 | Specific gravity of Urine by Test strip | Quantitative Test | Example | ||
5803-2 | pH of Urine by Test strip | [pH] | Quantitative Test | Example | |
20454-5 | Protein [Presence] in Urine by Test strip | Qualitative Test (Ordinal) | Example | ||
20405-7 | Urobilinogen [Mass/volume] in Urine by Test strip | mg/dL | Quantitative Test | Example | |
5802-4 | Nitrite [Presence] in Urine by Test strip | Qualitative Test (Ordinal) | Example | ||
5794-3 | Hemoglobin [Presence] in Urine by Test strip | Qualitative Test (Ordinal) | Example | ||
5799-2 | Leukocyte esterase [Presence] in Urine by Test strip | Qualitative Test (Ordinal) | Example | ||
11279-7 | Urine sediment comments by Light microscopy Narrative | Narrative Test | Example | ||
25145-4 | Bacteria [Presence] in Urine sediment by Light microscopy | Qualitative Test (Ordinal) | Example | ||
5787-7 | Epithelial cells [#/area] in Urine sediment by Microscopy high power field | /[HPF] | Semi-Quantitative Test. Although reported as a range this is probably an ordinal list ( e.g. 1-10, 10-40, 40+) | Example | |
5821-4 | Leukocytes [#/area] in Urine sediment by Microscopy high power field | /[HPF] | Semi-Quantitative Test Although reported as a range this is probably an ordinal list ( e.g. 1-10, 10-40, 40+) | Example | |
13945-1 | Erythrocytes [#/area] in Urine sediment by Microscopy high power field | /[HPF] | Semi-Quantitative Test Although reported as a range this is probably an ordinal list ( e.g. 1-10, 10-40, 40+) | Example | |
... | ... | ... | ... | ... |
Complete Summary of the Mandatory Requirements
- One status in Observation.status
- One category in Observation.category which must have:
- a fixed Observation.category.coding.system="http://hl7.org/fhir/observation-category"
- a fixed Observation.category.coding.code="laboratory"
- One code in Observation.code which must have if available:
- a fixed Observation.code.coding.system="http://loinc.org"
- a LOINC code in Observation.code.coding.code
- Other additional codes are allowed - e.g. system specific codes. All codes SHALL have an system value
- Either one Observation.value[x] or one code in Observation.DataAbsentReason (unless the Observation.code is a panel code)
- Each Observation.valueQuantity must have:
- One numeric value in Observation.valueQuantity.value
- a fixed Observation.valueQuantity.system="http://unitsofmeasure.org"
- a UCUM unit code in Observation.valueQuantity.code taken from the "Units" column in the table
- Each Observation.valueCodeableConcept must have either:
- a code in Observation.valueCodeableConcept.coding.code and code system in Observation.valueCodeableConcept.coding.sytem
- SNOMED CT is preferred binding
- OR text in Observation.valueCodeableConcept.text
- a code in Observation.valueCodeableConcept.coding.code and code system in Observation.valueCodeableConcept.coding.sytem
- Observation.DataAbsentReason is bound to Observation Value Absent Reason Value set (Code set)
- Each Observation.valueQuantity must have:
- One patient in Observation.subject
Each Observation should have:
- A date and time in effectiveDateTime or effectivePeriod
- A reference range if applicable in Observation.referenceRange
Quick Start
Below is a quick overview of the required search and read operations
DiagnosticReport
GET [base]/DiagnosticReport?patient=[id]&category=LAB
Support: Mandatory to support search by category code = LAB.
Implementation Notes: Search based on diagnostic report category code = 'LAB'. This fetches a bundle of all lab related DiagnosticReport resources for the specified patient (how to search by reference) and (how to search by token).
Response Class:
- (Status 200): successful operation
- (Status 400): invalid parameter
- (Status 401/4xx): unauthorized request
- (Status 403): insufficient scope
Example:
[GET http://spark.furore.com/fhir/DiagnosticReport?patient=f201&category=LAB]
GET [base]/DiagnosticReport?patient=[id]&code=[LOINC{,LOINC2,LOINC3,...}]
Support: Mandatory support search by a laboratory order code. SHOULD support search by multiple order codes.
Implementation Notes: Search based on DiagnosticReport code. This fetches a bundle of all DiagnosticReport resources for a specific diagnostic order code for the specified patient (how to search by reference) and (how to search by token).
Response Class:
- (Status 200): successful operation
- (Status 400): invalid parameter
- (Status 401/4xx): unauthorized request
- (Status 403): insufficient scope
Example:)
Search for all metabolic panel reports for a patient:
[GET https://fhir-open-api-dstu2.smarthealthit.org/DiagnosticReport?patient=1032702&code=24323-8]
Example:
Search for all cbc, metabolic panel, and urinalysis panels for a patient
[GET https://fhir-open-api-dstu2.smarthealthit.org/DiagnosticReport?patient=1032702&code=24323-8,58410-2,24356-8]
GET [base]/DiagnosticReport?patient=[id]&category=LAB&date=[date]{&date=[date]}
Support: Mandatory support search by category code and date or period
Implementation Notes: Search based on laboratory category code and date. This fetches a bundle of all DiagnosticReport resources with category 'LAB' for the specified patient for a specified time period (how to search by reference)and (how to search by token) and (how to search by date).
Response Class:
- (Status 200): successful operation
- (Status 400): invalid parameter
- (Status 401/4xx): unauthorized request
- (Status 403): insufficient scope
Example:
Find all the lab reports issued after 2010-01-14
[GET http://spark.furore.com/fhir/DiagnosticReport?patient=f201&category=LAB&date=ge2010-01-14]
Observation
GET [base]/Observation?patient=[id]&category=laboratory
Support: Mandatory to support search by category code = laboratory
Implementation Notes: Search based on laboratory category code = "laboratory". This fetches a bundle of all Observation resources with laboratory categories for the specified patient (how to search by reference) and (how to search by token).
Response Class:
- (Status 200): successful operation
- (Status 400): invalid parameter
- (Status 401/4xx): unauthorized request
- (Status 403): insufficient scope
Example:
[GET https://fhir-open-api-dstu2.smarthealthit.org/Observation?patient=1134281&category=laboratory]
GET [base]/Observation?patient=[id]&code=[LOINC{,LOINC2,LOINC3,...}]
Support: Mandatory support search by a laboratory LOINC code. SHOULD support search by multiple LOINC codes.
Implementation Notes: 1) Search based on laboratory LOINC code(s). This fetches a bundle of all Observation resources for a specific observation LOINC code(s) for the specified patient (how to search by reference) and (how to search by token). 2) The Argonaut Observation "code" parameter has been defined to search both in both Observation.code and Observation.component.code.
Response Class:
- (Status 200): successful operation
- (Status 400): invalid parameter
- (Status 401/4xx): unauthorized request
- (Status 403): insufficient scope
Example:)
Search for all blood glucose lab results for a patient:
[GET https://fhir-open-api-dstu2.smarthealthit.org/Observation?patient=1134281&code=2339-0]
Search for all blood glucose, urine glucose and urine ketones for a patient
[GET https://fhir-open-api-dstu2.smarthealthit.org/Observation?patient=1134281&code=2339-0,25428-4,2514-8]
GET [base]/Observation?patient=[id]&category=laboratory&date=[date]{&date=[date]}
Support: Mandatory support search by category code and date or period
Implementation Notes: Search based on laboratory category code and date. This fetches a bundle of all Observation resources with category 'laboratory' for the specified patient for a specified time period (how to search by reference)and (how to search by token) and (how to search by date).
Response Class:
- (Status 200): successful operation
- (Status 400): invalid parameter
- (Status 401/4xx): unauthorized request
- (Status 403): insufficient scope
Example:
Find all the laboratory results after 2013-03-14
[GET http://fhir2.healthintersections.com.au/open/Observation?patient=555580&category=laboratory&date=ge2015-01-14]
Open Issues
Issues for this IG have been identified and tracked HERE
Resources
Formalized testing with test scripts and objective results reporting is available through the participation of AEGIS and MITRE (Crucible). The testscript provided can be used to test servers: [todo]
References