Genomics Reporting Implementation Guide
4.0.0-cibuild - CI Build
Genomics Reporting Implementation Guide
4.0.0-cibuild - CI Build
Genomics Reporting Implementation Guide, published by HL7 International / Clinical Genomics. This guide is not an authorized publication; it is the continuous build for version 4.0.0-cibuild built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/HL7/genomics-reporting/ and changes regularly. See the Directory of published versions
| Official URL: http://hl7.org/fhir/uv/genomics-reporting/OperationDefinition/find-population-specific-variants | Version: 4.0.0-cibuild | |||
| Standards status: Trial-use | Maturity Level: 2 | Computable Name: FindPopulationSpecificVariants | ||
Retrieve count or list of patients having specified variants.
Retrieve count or list of patients having specified variants.
Population queries are designed to return a count of patients that match each item sought, with or without a list of patients matching the item(s) sought. As described in general guidance, the population denominator can be limited by referencing a FHIR Group instance.
As described in general guidance, FHIR Genomics Operations do not support 'AND' logic unless stated otherwise. This particular operation supports a logical 'AND' of the 'variants' parameter, specified by repeating the parameter. 'AND' logic is useful when searching for other subjects sharing a specific constellation of variants, as in the following example that seeks patients having variant 'a' or 'b' or 'c', and variant 'd' or 'e' or 'f', and variant 'i' or 'j' or 'k':
...&variants=a,b,c&variants=d,e,f&variants=i,j,k
| Use | Name | Scope | Cardinality | Type | Binding | Documentation |
| IN | variants | 1..* | string (string) | List of variants being sought. Must be in HGVS or SPDI format. | ||
| IN | genomicSourceClass | 0..1 | string (token) | Enables an App to limit results to those that are 'germline' or 'somatic'. Default is to include variants irrespective of genomic source class. | ||
| IN | group | 0..1 | string (reference) | Identifier of a FHIR Group. If supplied, the search is restricted to members of the group: numerator counts only group members, denominator is the number of members in the group, and the subject list (if includePatientList=true) contains only group members. If omitted, all patients in the repository are searched. An unknown group identifier results in an error. | ||
| IN | includePatientList | 0..1 | boolean | Include list of matching patients if set to true. Default=false. | ||
| OUT | variants | 1..* | ||||
| OUT | variants.variantItem | 1..1 | string | variant from variantList | ||
| OUT | variants.numerator | 1..1 | Quantity | Count of patients having this variant (limited to members of group, if supplied) | ||
| OUT | variants.denominator | 0..1 | Quantity | Count of patients in the cohort searched (the number of members in group, if supplied; otherwise all patients in the repository) | ||
| OUT | variants.subject | 0..* | string | Patient ID. Include if includePatientList=true. Limited to members of group, if supplied |
Valid response codes are shown in the following table. Additional response codes (e.g. 5xx server error) may also be encountered.
| Response Code | Description |
|---|---|
| 200 | Successfully executed request |
| 400 | ERROR: Invalid query parameters |
| 404 | ERROR: Group not found |
| 422 | ERROR: Failed LiftOver |
An oncologist treating a patient with metastatic breast cancer determines the patient has the following somatic oncogenic mutations [NC_000010.10:g.121551307G>A, NC_000011.10:g.8263343T>C, NC_000001.10:g.198742263G>A], and wants to see if there are other patients that have ALL of these variants.
GET .../$find-population-specific-variants?variants=NC_000010.10:g.121551307G>A&variants=NC_000011.10:g.8263343T>C&variants=NC_000001.10:g.198742263G>A
See example output.
In the same scenario, the oncologist now wants to see if there are other patients that have ANY of these variants.
GET .../$find-population-specific-variants?variants=NC_000010.10:g.121551307G>A,NC_000011.10:g.8263343T>C,NC_000001.10:g.198742263G>A
See example output.
The oncologist is also screening for a clinical trial, and wants to know how many patients enrolled in the trial cohort (represented as FHIR Group 'breast-cancer-trial-cohort') have ANY of these variants, along with the list of those patients. The returned denominator is the number of members in the group, and only group members are counted and listed.
GET .../$find-population-specific-variants?variants=NC_000010.10:g.121551307G>A,NC_000011.10:g.8263343T>C,NC_000001.10:g.198742263G>A&group=breast-cancer-trial-cohort&includePatientList=true
See example output.
IG © 2025+ HL7 International / Clinical Genomics. Package hl7.fhir.uv.genomics-reporting#4.0.0-cibuild based on FHIR 4.0.1. Generated 2026-11-02
Links: Table of Contents |
QA Report
| Version History |
|
Propose a change