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

## OperationDefinition: Find Study Metadata

Official URL: http://hl7.org/fhir/uv/genomics-reporting/OperationDefinition/find-study-metadata | Version: 4.0.0-cibuild
Standards status: Trial-use | Maturity Level: 2 | Computable Name: FindStudyMetadata

Retrieve metadata about sequencing studies performed on a subject.

### Description

Retrieve metadata about sequencing studies performed on a subject.

> STU Note: The Clinical Genomics committee is reviewing Jira 35864: Add study-level metadata capabilities into the FHIR Genomics IG. It is expected that the response of this operation will be revised in the future, to align with the Jira resolution.

Test Id and test date are always returned. Additional metadata is server dependent, and specific implementations can indicate their capabilities using a FHIR Capability Statement. Frequently useful metadata includes Specimen Id and Genomic build (reference sequence assembly upon which variants were called, e.g. 'GRCh37', 'GRCh38'). Additionally, it can be useful to indicate the DNA change types or types of variants detectable by the test (e.g. 'SNV', 'InDel', 'CNV'). Servers can choose to return additional metadata.

As described in general guidance, metadata can be used to filter the results of other operations.

In some scenarios, users need to know whether or not a particular genomic region was studied by a given test (studied region), and whether or not there are uncallable subregions within regions studied (uncallable regions). Genomic sequencing tests are designed to study specific portions of a person's genome. For instance, whole genome sequencing (WGS) tests are designed to study the entire genome; whole exome sequencing (WES) tests are designed to study protein-coding exons; targeted sequencing tests are designed to only study selected regions of the genome. In many cases, while a particular region was targeted to be studied by a given test, a portion of the region might be untestable, due to patient-specific factors, reagent-specific factors, etc. Whereas labs report variants found to be present, labs cannot enumerate every variant found to be absent - when you consider that a person has 4 billion base pairs, 99% of which are the same as a reference sequence, you can imagine how big a report would need to be to enumerate every variant found to be absent! Rather, absence of a variant at a particular position can potentially be inferred by knowing the region studied, and whether or not there were uncallable subregions within the studied region.

Users can request this level of detail by including the ranges parameter, in which case each returned test will include intersecting studied and uncallable regions. Studied and uncallable regions can be voluminous - data can be curtailed by specifying appropriately narrow ranges. Range data is returned as a list of non-overlapping regions, each in zero-based RefSeq:Integer-range format (e.g. "['NC_000007.14:55173910-55174053', 'NC_000007.14:55174711-55174830', 'NC_000007.14:55181282-55181488']").

### Parameters

Use | Name | Scope | Cardinality | Type | Binding | Documentation
IN | subject |  | 1..1 | string (reference) |  | The subject of interest.
IN | testIdentifiers |  | 0..* | string (token) |  | List of test identifiers. Metadata for each test is returned.
IN | testDateRange |  | 0..1 | Period |  | Metadata for each test performed during the range is returned.
IN | specimenIdentifiers |  | 0..* | string (token) |  | List of specimen identifiers. Metadata for each test based on a supplied specimen identifier is returned.
IN | ranges |  | 0..* | string (special) |  | List of regions for which additional study information is sought. If ranges are supplied, then each returned test will include studied and uncallable regions. Must be in zero-based RefSeq:Integer-range format (e.g. 'NC_000007.14:55174721-55174820').
OUT | tests |  | 0..* |  |  |
OUT | tests.testId |  | 1..1 | string |  | test identifier
OUT | tests.testDate |  | 1..1 | dateTime |  | test date
OUT | tests.specimenId |  | 0..1 | string |  | specimen identifier
OUT | tests.genomicBuild |  | 0..1 | CodeableConcept |  | preferred codes: https://loinc.org/LL1040-6/
OUT | tests.dnaChangeType |  | 0..1 | CodeableConcept |  | preferred codes: http://www.sequenceontology.org/browser/current_release/term/SO:0002072
OUT | tests.regionStudied |  | 0..1 | string |  | List of non-overlapping regions, each in zero-based RefSeq:Integer-range format; or 'unknown'
OUT | tests.uncallableRegions |  | 0..1 | string |  | List of non-overlapping regions, each in zero-based RefSeq:Integer-range format; or 'unknown'

### Notes:

#### Error Codes

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: Patient not found
422 | ERROR: Failed LiftOver

#### Examples

March 2019, patient HG00403 is found to have lung mass on CXR, and undergoes lung biopsy. WES of a 300 gene panel is performed on the biopsy specimen, and analyzed for simple variants (SNV, MNV, InDel). For technical reasons, PIK3CB was deemed uncallable.

July 2020, patient HG00403 presents with headache, and mass is found on head CT. Biopsy is consistent with metastatic lung cancer. WES of a 420 gene panel is performed on the biopsy specimen, and analyzed for simple variants (SNV, MNV, InDel) and for Copy Number Variants. For technical reasons, PIK3CB, APC, MEN1, and portions of EGFR were deemed uncallable.

To be eligible for a particular clinical trial, patients must have an EGFR exon 19 (NC_000007.14:55174721-55174820) deletion. Patient's oncologist finds no simple or structural variants in the region of EGFR exon 19, and asks staff bioinformaticist to confirm whether EGFR, including exon 19, was studied as part of the July 2020 test. (Results indicate that EGFR was studied, but exon 19 was deemed uncallable).

    GET .../$find-study-metadata?subject=HG00403&testDateRange=ge2020-06-01&testDateRange=le2020-08-01&ranges=NC_000007.14:55019016-55211628

See example output.