fhir-query man page¶

FHIR-Aggregator is a command line package. The following commands are all shown an ipython notebook.

to run commands in python you will need to use export the fq command to the terminal using the os package:
```
   import os
   os.system('fq --help')
```
to run commands on the command line do not add the !, as in: fq --help

To see help pages while you work type:

!fq <subcommand> --help

example:

!fq ls --help

Install `fhir-query`¶

pip install fhir-aggregator-client

URL for FHIR-Aggregator server¶

%env FHIR_BASE=https://google-fhir.fhir-aggregator.org

Get a tsv of all FHIR-Aggregator vocabulary¶

!fq vocabulary vocabulary.tsv --fhir-base-url $FHIR_BASE

fq options¶

In [1]:

Copied!

!fq --help
!fq --help

Usage: fq [OPTIONS] COMMAND [ARGS]...

  FHIR-Aggregator utilities.

Options:
  --help  Show this message and exit.

Commands:
  ls          List all the installed GraphDefinitions.
  run         Run GraphDefinition queries.
  results     Work with the results of a GraphDefinition query.
  vocabulary  FHIR-Aggregator's key Resources and CodeSystems.

list and run GraphDefinitions¶

In [2]:

Copied!

!fq ls --help
!fq ls --help

Usage: fq ls [OPTIONS]

  List all the installed GraphDefinitions.

Options:
  -f, --format [table|yaml|json]  Output format
  --help                          Show this message and exit.

In [3]:

Copied!

!fq ls --format yaml
!fq ls --format yaml

- description: (dbGAP) Retrieve ResearchStudy and children. Uses HAPI's deep linking.
    fhir-query '/ResearchStudy?_id=phs001232'
  id: research-study-link-iterate
  path: /home/docs/checkouts/readthedocs.org/user_builds/fhir-aggregator/envs/latest/lib/python3.13/site-packages/fhir_aggregator_client/graph-definitions/ResearchStudyLinkIterate.yaml
- description: (FHIR-Aggregator) Retrieve Patient and Observations [NCIT_C156418,NCIT_C156419].
    fhir-query '/ResearchStudy?identifier=TCGA-BRCA'
  id: patient-survival-graph
  path: /home/docs/checkouts/readthedocs.org/user_builds/fhir-aggregator/envs/latest/lib/python3.13/site-packages/fhir_aggregator_client/graph-definitions/PatientSurvivalGraph.yaml
- description: (FHIR-Aggregator) Retrieve a ResearchStudy and children. Uses part-of-study
    extension. fhir-query '/ResearchStudy?identifier=TCGA-BRCA'
  id: research-study-part-of
  path: /home/docs/checkouts/readthedocs.org/user_builds/fhir-aggregator/envs/latest/lib/python3.13/site-packages/fhir_aggregator_client/graph-definitions/ResearchStudyPartOf.yaml
- description: (FHIR-Aggregator) Condition to ResearchStudy and children. fhir-query
    '/Condition?code:text=cholangiocarcinoma'
  id: condition-graph
  path: /home/docs/checkouts/readthedocs.org/user_builds/fhir-aggregator/envs/latest/lib/python3.13/site-packages/fhir_aggregator_client/graph-definitions/ConditionGraph.yaml

Lets run a retrieval of a research study, ex. 1000 Genomes¶

!fq run research-study-part-of '/ResearchStudy?identifier=1KG'

 
research-study-part-of is valid FHIR R5 GraphDefinition
ℹ Fetching https://google-fhir.fhir-aggregator.org/ResearchStudy?identifier=1KG
ℹ Processing ResearchStudy with 1 resources
ℹ Processing 11 links for ResearchStudy in parallel.
ℹ Processing link: ResearchSubject/study={ref} with 1 ResearchStudy(s)
ℹ Processing link: Group/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: Patient/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: Specimen/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: Observation/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: Procedure/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: DocumentReference/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: ServiceRequest/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: ImagingStudy/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: Condition/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
ℹ Processing link: MedicationAdministration/part-of-study={ref}&_count=1000&_total=accurate with 1 ResearchStudy(s)
✔ Processed link: MedicationAdministration/part-of-study={ref}&_count=1000&_total=accurate
✔ Processed link: ImagingStudy/part-of-study={ref}&_count=1000&_total=accurate
✔ Processed link: Group/part-of-study={ref}&_count=1000&_total=accurate
✔ Processed link: Observation/part-of-study={ref}&_count=1000&_total=accurate
✔ Processed link: Condition/part-of-study={ref}&_count=1000&_total=accurate
✔ Processed link: Procedure/part-of-study={ref}&_count=1000&_total=accurate
✔ Processed link: ServiceRequest/part-of-study={ref}&_count=1000&_total=accurate
✔ Processed link: Patient/part-of-study={ref}&_count=1000&_total=accurate
✔ Processed link: Specimen/part-of-study={ref}&_count=1000&_total=accurate
ℹ Fetching ResearchSubject page 10 of 35
✔ Processed link: DocumentReference/part-of-study={ref}&_count=1000&_total=accurate
ℹ Fetching ResearchSubject page 20 of 35
ℹ Fetching ResearchSubject page 30 of 35
✔ Processed link: ResearchSubject/study={ref}
Aggregated Results: {'DocumentReference': 48, 'Observation': 1, 'Patient': 3500, 'ResearchStudy': 1, 'ResearchSubject': 3500, 'ServiceRequest': 1, 'Specimen': 3500}
database available at: ~/.fhir-aggregator/fhir-graph.sqlite

Work with the retrieved FHIR resources¶

fq results¶

fq results
Usage: fq results [OPTIONS] COMMAND [ARGS]...

  Work with the results of a GraphDefinition query.

Options:
  --help  Show this message and exit.

Commands:
  dataframe  Create dataframe from the local db.
  summarize  Summarize the aggregation results.
  visualize  Visualize the FHIR Resources in the database.

fq results summarize

DocumentReference:
  count: 48
  references:
    Patient:
      count: 48
    ResearchStudy:
      count: 48
    ServiceRequest:
      count: 48
    Specimen:
      count: 120192
Observation:
  count: 1
  references:
    ResearchStudy:
      count: 2
Patient:
  count: 3500
  references:
    ResearchStudy:
      count: 3500
ResearchStudy:
  count: 1
  references:
    ResearchStudy:
      count: 1
ResearchSubject:
  count: 3500
  references:
    Patient:
      count: 3500
    ResearchStudy:
      count: 7000
ServiceRequest:
  count: 1
  references:
    Patient:
      count: 1
    ResearchStudy:
      count: 1
    Specimen:
      count: 2504
Specimen:
  count: 3500
  references:
    Patient:
      count: 3500
    ResearchStudy:
      count: 3500

fq results visualize¶

fq results visualize Wrote: fhir-graph.html 1KG visualization

fq results dataframe¶

Create a dataframe of the results

We can create a tsv

fq results dataframe
Saved fhir-graph.tsv

Or launch dtale for review fq results dataframe --dtale

fq vocabulary¶

fq vocabulary --help
Usage: fq vocabulary [OPTIONS] [OUTPUT_PATH]

  FHIR-Aggregator's key Resources and CodeSystems. 

  OUTPUT_PATH: Path to the output file. If not provided, the output will be
  printed to stdout.

Options:
  --fhir-base-url TEXT          Base URL of the FHIR server. default: env
                                $FHIR_BASE  [required]
  -f, --format [tsv|yaml|json]  Output format
  --debug                       Enable debug mode.
  --log-file TEXT               Path to the log file.
                                default=/Users/walsbr/.fhir-aggregator/app.log
  --dtale                       Open the graph in a browser using the dtale
                                package for interactive data exploration.
  --help                        Show this message and exit.

This retrieves a histogram of all codeable concepts and extensions for all projects, rendered as a TSV. Alternatively use the --dtale option to browse and filter results

In [ ]: