From ee78ad08a58769f54ca3d63a0a1e5ea51df896a6 Mon Sep 17 00:00:00 2001 From: Phil Darnowsky Date: Mon, 23 Sep 2024 15:04:05 -0400 Subject: [PATCH] Add some API documentation for endusers Here we start adding docs covering the basics of using our GraphQL API, including how to fetch all variant frequencies for a gene. --- ...-a-batch-of-variants-do-you-have-an-api.md | 4 +- .../DataPage.module.css} | 0 .../DataPage.spec.tsx} | 6 +- .../DataPage.tsx} | 60 +- .../ExacDownloads.tsx | 0 .../GnomadV2Downloads.tsx | 0 .../GnomadV2LiftoverDownloads.tsx | 0 .../GnomadV3Downloads.tsx | 0 .../GnomadV4Downloads.tsx | 0 browser/src/DataPage/GraphQLDocs.tsx | 76 + .../TableOfContents.tsx | 4 +- .../__snapshots__/DataPage.spec.tsx.snap} | 4043 +++++++++-------- .../downloadsHooks.ts | 0 .../downloadsPageStyles.tsx | 17 + browser/src/DataPage/exampleJSGraphQLQuery.ts | 37 + .../src/DataPage/examplePythonGraphQLQuery.ts | 38 + .../src/DataPage/exampleRawGraphQLQuery.ts | 126 + browser/src/NavBar.tsx | 6 +- browser/src/Routes.tsx | 6 +- .../src/__snapshots__/NavBar.spec.tsx.snap | 4 +- .../help/__snapshots__/HelpPage.spec.tsx.snap | 4 +- 21 files changed, 2598 insertions(+), 1833 deletions(-) rename browser/src/{DownloadsPage/DownloadsPage.module.css => DataPage/DataPage.module.css} (100%) rename browser/src/{DownloadsPage/DownloadsPage.spec.tsx => DataPage/DataPage.spec.tsx} (71%) rename browser/src/{DownloadsPage/DownloadsPage.tsx => DataPage/DataPage.tsx} (87%) rename browser/src/{DownloadsPage => DataPage}/ExacDownloads.tsx (100%) rename browser/src/{DownloadsPage => DataPage}/GnomadV2Downloads.tsx (100%) rename browser/src/{DownloadsPage => DataPage}/GnomadV2LiftoverDownloads.tsx (100%) rename browser/src/{DownloadsPage => DataPage}/GnomadV3Downloads.tsx (100%) rename browser/src/{DownloadsPage => DataPage}/GnomadV4Downloads.tsx (100%) create mode 100644 browser/src/DataPage/GraphQLDocs.tsx rename browser/src/{DownloadsPage => DataPage}/TableOfContents.tsx (97%) rename browser/src/{DownloadsPage/__snapshots__/DownloadsPage.spec.tsx.snap => DataPage/__snapshots__/DataPage.spec.tsx.snap} (93%) rename browser/src/{DownloadsPage => DataPage}/downloadsHooks.ts (100%) rename browser/src/{DownloadsPage => DataPage}/downloadsPageStyles.tsx (97%) create mode 100644 browser/src/DataPage/exampleJSGraphQLQuery.ts create mode 100644 browser/src/DataPage/examplePythonGraphQLQuery.ts create mode 100644 browser/src/DataPage/exampleRawGraphQLQuery.ts diff --git a/browser/help/faq/technical-details/how-do-i-query-a-batch-of-variants-do-you-have-an-api.md b/browser/help/faq/technical-details/how-do-i-query-a-batch-of-variants-do-you-have-an-api.md index 38f3ff259..44d04518b 100644 --- a/browser/help/faq/technical-details/how-do-i-query-a-batch-of-variants-do-you-have-an-api.md +++ b/browser/help/faq/technical-details/how-do-i-query-a-batch-of-variants-do-you-have-an-api.md @@ -2,6 +2,6 @@ question: 'How do I query a batch of variants? Do you have an API?' --- -We currently do not have a way to submit batch queries on the browser, but we are actively working on developing a public API for gnomAD. We currently maintain a [GraphQL](https://graphql.org) API for internal use and groups can contact us if they want permission to use this API until a more robust public solution is launched. +The [GraphQL](https://graphql.org) API used by the browser is open to the public. Please see our [data page](/data) for details. -You can also obtain information on all variants from the VCFs and Hail Tables available on our [downloads page](/downloads). +You can also obtain information on all variants from the VCFs and Hail Tables available on our [data page](/data). diff --git a/browser/src/DownloadsPage/DownloadsPage.module.css b/browser/src/DataPage/DataPage.module.css similarity index 100% rename from browser/src/DownloadsPage/DownloadsPage.module.css rename to browser/src/DataPage/DataPage.module.css diff --git a/browser/src/DownloadsPage/DownloadsPage.spec.tsx b/browser/src/DataPage/DataPage.spec.tsx similarity index 71% rename from browser/src/DownloadsPage/DownloadsPage.spec.tsx rename to browser/src/DataPage/DataPage.spec.tsx index a6ea9c0a9..92018d5e4 100644 --- a/browser/src/DownloadsPage/DownloadsPage.spec.tsx +++ b/browser/src/DataPage/DataPage.spec.tsx @@ -4,14 +4,14 @@ import 'jest-styled-components' import React from 'react' import renderer from 'react-test-renderer' -import DownloadsPage from './DownloadsPage' +import DataPage from './DataPage' import { BrowserRouter } from 'react-router-dom' -test('Downloads Page has no unexpected changes', () => { +test('Data Page has no unexpected changes', () => { const tree = renderer.create( - + ) expect(tree).toMatchSnapshot() diff --git a/browser/src/DownloadsPage/DownloadsPage.tsx b/browser/src/DataPage/DataPage.tsx similarity index 87% rename from browser/src/DownloadsPage/DownloadsPage.tsx rename to browser/src/DataPage/DataPage.tsx index c1ab70a6d..05226cd89 100644 --- a/browser/src/DownloadsPage/DownloadsPage.tsx +++ b/browser/src/DataPage/DataPage.tsx @@ -8,35 +8,19 @@ import Link from '../Link' import DocumentTitle from '../DocumentTitle' import InfoPage from '../InfoPage' -import { SectionTitle, StyledParagraph } from './downloadsPageStyles' +import { SectionTitle, StyledParagraph, CodeBlock } from './downloadsPageStyles' -import DownloadsPageTableOfContents from './TableOfContents' +import DataPageTableOfContents from './TableOfContents' // @ts-expect-error -import styles from './DownloadsPage.module.css' +import styles from './DataPage.module.css' import GnomadV4Downloads from './GnomadV4Downloads' import GnomadV3Downloads from './GnomadV3Downloads' import GnomadV2Downloads from './GnomadV2Downloads' import GnomadV2LiftoverDownloads from './GnomadV2LiftoverDownloads' import ExacDownloads from './ExacDownloads' - -const CodeBlock = styled.code` - display: inline-block; - box-sizing: border-box; - max-width: 100%; - padding: 0.5em 1em; - border-radius: 0.25em; - background: #333; - color: #fafafa; - font-family: monospace; - line-height: 1.6; - white-space: nowrap; - - &::before { - content: '$ '; - } -` +import GraphQLDocs from './GraphQLDocs' const TextSection = styled.div` width: 70%; @@ -65,17 +49,17 @@ const BottomSpacer = styled.div` margin-bottom: 40rem; ` -const DownloadsPage = () => { +const DataPage = () => { // Load stylesheet to make smooth scroll behavior active const _style = styles.html return ( - - Downloads + + Data - + @@ -83,7 +67,7 @@ const DownloadsPage = () => { Summary -

+ gnomAD data is available for download through{' '} {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */} @@ -99,19 +83,15 @@ const DownloadsPage = () => { Azure Open Datasets - . -

- -

+ . We recommend using {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */} - We recommend using Hail and our{' '} + Hail and our{' '} {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */} Hail utilities for gnomAD {' '} - to work with the data. -

- + to work with this data. + In addition to the files listed below,{' '} {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */} @@ -122,9 +102,15 @@ const DownloadsPage = () => { . - + + The API used by the gnomAD browser is also open to the public. In use cases involving + querying a relatively small number of records with low latency, using the API to request + records as needed may be more suitable than working with downloaded gnomAD data. If + you're unsure which would be better for your use case, please reach out to the browser + team. + +

Download Overview

Google Cloud Public Datasets

-

Files can be browsed and downloaded using{' '} {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */} @@ -233,10 +219,12 @@ const DownloadsPage = () => { + + ) } -export default DownloadsPage +export default DataPage diff --git a/browser/src/DownloadsPage/ExacDownloads.tsx b/browser/src/DataPage/ExacDownloads.tsx similarity index 100% rename from browser/src/DownloadsPage/ExacDownloads.tsx rename to browser/src/DataPage/ExacDownloads.tsx diff --git a/browser/src/DownloadsPage/GnomadV2Downloads.tsx b/browser/src/DataPage/GnomadV2Downloads.tsx similarity index 100% rename from browser/src/DownloadsPage/GnomadV2Downloads.tsx rename to browser/src/DataPage/GnomadV2Downloads.tsx diff --git a/browser/src/DownloadsPage/GnomadV2LiftoverDownloads.tsx b/browser/src/DataPage/GnomadV2LiftoverDownloads.tsx similarity index 100% rename from browser/src/DownloadsPage/GnomadV2LiftoverDownloads.tsx rename to browser/src/DataPage/GnomadV2LiftoverDownloads.tsx diff --git a/browser/src/DownloadsPage/GnomadV3Downloads.tsx b/browser/src/DataPage/GnomadV3Downloads.tsx similarity index 100% rename from browser/src/DownloadsPage/GnomadV3Downloads.tsx rename to browser/src/DataPage/GnomadV3Downloads.tsx diff --git a/browser/src/DownloadsPage/GnomadV4Downloads.tsx b/browser/src/DataPage/GnomadV4Downloads.tsx similarity index 100% rename from browser/src/DownloadsPage/GnomadV4Downloads.tsx rename to browser/src/DataPage/GnomadV4Downloads.tsx diff --git a/browser/src/DataPage/GraphQLDocs.tsx b/browser/src/DataPage/GraphQLDocs.tsx new file mode 100644 index 000000000..8333114ee --- /dev/null +++ b/browser/src/DataPage/GraphQLDocs.tsx @@ -0,0 +1,76 @@ +import React from 'react' + +import { CodeBlock, SectionTitle, StyledParagraph } from './downloadsPageStyles' + +import styled from 'styled-components' + +import { ExternalLink, Tabs } from '@gnomad/ui' +import exampleRawQuery from './exampleRawGraphQLQuery' +import examplePythonQuery from './examplePythonGraphQLQuery' +import exampleJSQuery from './exampleJSGraphQLQuery' + +const GraphQLCodeBlock = styled(CodeBlock)` + white-space: pre-wrap; + + &::before { + content: none; + } +` + +const GraphQLDocs = () => ( + <> + gnomAD API + + The gnomAD browser gets its data through a{' '} + {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */} + GraphQL API which is open to the + public. Access to the API is rate-limited to 10 requests per 60-second period. + + + The API can be queried programatically by making an HTTP request to{' '} + https://gnomad.broadinstitute.org/api. Please see the GraphQL documentation + for details on how to{' '} + {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */} + + construct a query + and{' '} + {/* @ts-expect-error TS(2786) FIXME: 'ExternalLink' cannot be used as a JSX component. */} + + format it to send it over HTTP + + . + + + You can also use the API interactively by visiting the same address in your + browser, which is useful for experimenting with queries. That interface also allows you to + explore the API schema interactively. + + + The following is an annotated GraphQL query, with some small example programs for a subset of + that query in Python and JavaScript. This query gets similar data to the CSV export of all + variants for gene BRCA1. + + {/* @ts-expect-error TS(2741) FIXME: Property 'onChange' is missing in type '{ tabs: { ... Remove this comment to see the full error message */} + {exampleRawQuery}, + }, + { + id: 'pythonQuery', + label: 'Python', + render: () => {examplePythonQuery}, + }, + { + id: 'jsQuery', + label: 'JavaScript', + render: () => {exampleJSQuery}, + }, + ]} + /> + +) + +export default GraphQLDocs diff --git a/browser/src/DownloadsPage/TableOfContents.tsx b/browser/src/DataPage/TableOfContents.tsx similarity index 97% rename from browser/src/DownloadsPage/TableOfContents.tsx rename to browser/src/DataPage/TableOfContents.tsx index 5001b4fe3..3b893d684 100644 --- a/browser/src/DownloadsPage/TableOfContents.tsx +++ b/browser/src/DataPage/TableOfContents.tsx @@ -24,7 +24,7 @@ const TableOfContentsStyledItem = styled.div<{ } ` -const DownloadsPageTableOfContents = () => { +const DataPageTableOfContents = () => { const [headings, setHeadings] = useState([]) const { activeId } = useHeadsObserver() const [activeSection, setActiveSection] = useState('') @@ -118,4 +118,4 @@ const DownloadsPageTableOfContents = () => { ) } -export default DownloadsPageTableOfContents +export default DataPageTableOfContents diff --git a/browser/src/DownloadsPage/__snapshots__/DownloadsPage.spec.tsx.snap b/browser/src/DataPage/__snapshots__/DataPage.spec.tsx.snap similarity index 93% rename from browser/src/DownloadsPage/__snapshots__/DownloadsPage.spec.tsx.snap rename to browser/src/DataPage/__snapshots__/DataPage.spec.tsx.snap index 9122f2fe9..cc1dc2044 100644 --- a/browser/src/DownloadsPage/__snapshots__/DownloadsPage.spec.tsx.snap +++ b/browser/src/DataPage/__snapshots__/DataPage.spec.tsx.snap @@ -1,6 +1,6 @@ // Jest Snapshot v1, https://goo.gl/fbAQLP -exports[`Downloads Page has no unexpected changes 1`] = ` +exports[`Data Page has no unexpected changes 1`] = ` .c21 { padding: 0; border: none; @@ -61,19 +61,19 @@ exports[`Downloads Page has no unexpected changes 1`] = ` text-decoration: underline; } -.c10 { +.c11 { color: #1173bb; -webkit-text-decoration: none; text-decoration: none; } -.c10:visited, -.c10:active { +.c11:visited, +.c11:active { color: #1173bb; } -.c10:focus, -.c10:hover { +.c11:focus, +.c11:hover { -webkit-text-decoration: underline; text-decoration: underline; } @@ -125,6 +125,58 @@ exports[`Downloads Page has no unexpected changes 1`] = ` box-shadow: 0 0 0 0.2em rgba(70,130,180,0.5); } +.c25 { + display: -webkit-inline-box; + display: -webkit-inline-flex; + display: -ms-inline-flexbox; + display: inline-flex; + -webkit-flex-direction: row; + -ms-flex-direction: row; + flex-direction: row; + width: 100%; + padding: 0; + border-bottom: 1px solid #e0e0e0; + margin: 0; + list-style-type: none; +} + +.c26 { + border-top-left-radius: 0.5em; + border-top-right-radius: 0.5em; + outline: none; + cursor: pointer; +} + +.c26:focus { + box-shadow: 0 0 0 0.2em rgba(66,139,202,0.5); +} + +.c27 { + box-sizing: border-box; + padding: 0.375em 0.75em; + border-color: #428bca; + border-style: solid; + border-top-left-radius: 0.5em; + border-top-right-radius: 0.5em; + border-width: 1px 1px 0 1px; + color: #428bca; +} + +.c28 { + box-sizing: border-box; + padding: 0.375em 0.75em; + border-color: #e0e0e0; + border-style: solid; + border-top-left-radius: 0.5em; + border-top-right-radius: 0.5em; + border-width: 1px 1px 0 1px; + color: inherit; +} + +.c29 { + padding: 0.5em; +} + .c13 { color: #1173bb; -webkit-text-decoration: none; @@ -206,7 +258,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` font-size: 1.5rem; } -.c11 { +.c10 { padding-bottom: 1rem; } @@ -238,11 +290,28 @@ exports[`Downloads Page has no unexpected changes 1`] = ` margin-bottom: 5rem; } +.c12 { + display: inline-block; + box-sizing: border-box; + max-width: 100%; + padding: 0.5em 1em; + border-radius: 0.25em; + background: #333; + color: #fafafa; + font-family: monospace; + line-height: 1.6; + white-space: nowrap; +} + +.c12::before { + content: '$ '; +} + .c4 { margin-left: 1rem; } -.c12 { +.c30 { display: inline-block; box-sizing: border-box; max-width: 100%; @@ -253,12 +322,17 @@ exports[`Downloads Page has no unexpected changes 1`] = ` font-family: monospace; line-height: 1.6; white-space: nowrap; + white-space: pre-wrap; } -.c12::before { +.c30::before { content: '$ '; } +.c30::before { + content: none; +} + .c5 { width: 70%; } @@ -274,7 +348,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` border-left: 1px solid lightgrey; } -.c25 { +.c31 { margin-bottom: 40rem; } @@ -339,7 +413,7 @@ exports[`Downloads Page has no unexpected changes 1`] = `

- Downloads + Data

-

+

gnomAD data is available for download through Azure Open Datasets - . -

-

- We recommend using + . We recommend using - to work with the data. + to work with this data.

In addition to the files listed below, .

+

+ The API used by the gnomAD browser is also open to the public. In use cases involving querying a relatively small number of records with low latency, using the API to request records as needed may be more suitable than working with downloaded gnomAD data. If you're unsure which would be better for your use case, please reach out to the browser team. +

+

+ Download Overview +

Google Cloud Public Datasets

@@ -464,7 +545,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` Files can be browsed and downloaded using

Please note, this BigQuery dataset is maintained entirely by Google. The gnomAD team has no ability to provide a consistent experience in BigQuery. @@ -507,7 +588,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` Files can be browsed and downloaded using the

gnomAD variants are also available in Parquet format.

See @@ -596,12 +677,12 @@ exports[`Downloads Page has no unexpected changes 1`] = ` Core Dataset vs Secondary Analyses

Within a versioned release, datasets available for download fall under two categories. The Core Dataset is the gnomAD database and analyses created and maintained by the . Secondary Analyses are additional analyses developed in collaboration with laboratories of the

The gnomAD v4.1.0 data set contains data from 730,947 exomes and 76,215 whole genomes, all mapped to the GRCh38 reference sequence.

@@ -673,7 +754,7 @@ exports[`Downloads Page has no unexpected changes 1`] = `

gnomAD database and features created and maintained by the gnomAD production team.

@@ -707,7 +788,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` For more information, read the

The gnomAD v3.1.2 data set contains 76,156 whole genomes (and no exomes), all mapped to the GRCh38 reference sequence.

@@ -8739,7 +8820,7 @@ exports[`Downloads Page has no unexpected changes 1`] = `

gnomAD database and features created and maintained by the gnomAD production team.

@@ -8778,7 +8859,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` Find out what changed in the latest release in the

Additional research analyses created using the core gnomAD releases in collaboration with members of the gnomAD steering committee.

@@ -14036,7 +14117,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` For more information about these files, see the

The gnomAD v2.1.1 liftover data set contains data from 125,748 exomes and 15,708 whole genomes, lifted over from the GRCh37 to the GRCh38 reference sequence.

@@ -15661,7 +15742,7 @@ exports[`Downloads Page has no unexpected changes 1`] = `

gnomAD database and features created and maintained by the gnomAD production team.

@@ -15760,7 +15841,7 @@ exports[`Downloads Page has no unexpected changes 1`] = `

The gnomAD v2.1.1 data set contains data from 125,748 exomes and 15,708 whole genomes, all mapped to the GRCh37/hg19 reference sequence.

@@ -20110,7 +20191,7 @@ exports[`Downloads Page has no unexpected changes 1`] = `

gnomAD database and features created and maintained by the gnomAD production team.

@@ -20149,7 +20230,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` Find out what changed in the latest release in the

Additional research analyses created using the core gnomAD releases in collaboration with members of the gnomAD steering committee.

@@ -26286,7 +26367,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` For information on constraint, see

The ExAC data set contains data from 60,706 exomes, all mapped to the GRCh37/hg19 reference sequence.

@@ -28387,7 +28468,7 @@ exports[`Downloads Page has no unexpected changes 1`] = `

gnomAD database and features created and maintained by the gnomAD production team.

@@ -28441,7 +28522,7 @@ exports[`Downloads Page has no unexpected changes 1`] = ` + +

+ + gnomAD API +

+ +

+ The gnomAD browser gets its data through a + + + GraphQL + + API which is open to the public. Access to the API is rate-limited to 10 requests per 60-second period. +

+

+ The API can be queried programatically by making an HTTP request to + + + https://gnomad.broadinstitute.org/api + + . Please see the GraphQL documentation for details on how to + + + construct a query + + and + + + format it to send it over HTTP + + . +

+

+ You can also use the API interactively by visiting + + the same address + + in your browser, which is useful for experimenting with queries. That interface also allows you to explore the API schema interactively. +

+

+ The following is an annotated GraphQL query, with some small example programs for a subset of that query in Python and JavaScript. This query gets similar data to the CSV export of all variants for gene + + BRCA1 + + . +

+
+
+
    +
  • + +
    • +
  • + +
    • +
  • + +
    • +
+
+
+
+ + # Lines beginning with a "#" character are comments that are ignored by the API. +# +# "VariantsInGene" is the operation name for the query. This is optional but +# recommended. +# +query VariantsInGene { + # We could alternatively look up the gene by Ensembl ID by using the + # "gene_id" argument rather than "gene_symbol". + # + # The gene symbol is given with quotes, but not the reference genome or + # dataset. This is because the gene symbol is defined in the API schema as a + # string, but the reference genome is an enumerated type that can have only + # the value GRCh37 or GRCh38, and the dataset argument is constrained + # similarly. See + # https://graphql.org/learn/schema/#enumeration-types. + # + gene(gene_symbol: "BRCA1", reference_genome: GRCh38) { + variants(dataset: gnomad_r4) { + variant_id + + # Position + pos + + # dbSNP reference SNP IDs + rsids + + transcript_id + transcript_version + + # HGVS DNA, coding sequence, and protein consequences + hgvs + hgvsc + hgvsp + + # VEP annotation + consequence + + # Flags on the variant generally + flags + + # The API separates the frequency data into exome data, genome data, and + # joint-frequency data. Which of these are available depends on the + # dataset used, and not all variants in a dataset necessarily have all + # of the possible kinds. + # + # Note that the exome and genome data have the same schema, but joint- + # frequency data is slightly different. + # + exome { + # Full allele count, and hemizygote/homozygote allele counts. + ac + ac_hemi + ac_hom + + # Allele number + an + + # Allele frequency + af + + # Allele counts and numbers by population + populations { + id + ac + an + ac_hemi + ac_hom + } + + # Filters and flags for exome data + filters + flags + } + + # Schema for genome data is same for that as exome data + genome { + ac + ac_hemi + ac_hom + an + af + populations { + id + ac + an + ac_hemi + ac_hom + } + filters + flags + } + + joint { + # Full allele count, and hemizygote/homozygote allele counts. + ac + hemizygote_count + homozygote_count + + # Allele number + an + + # Allele counts and numbers by population + populations { + id + ac + an + homozygote_count + hemizygote_count + } + + # Filters for joint-frequency data + filters + } + + # In-silico variant prediction annotations + in_silico_predictors { + id + value + flags + } + } + } +} + + +
+
+ + # GQL is one popular Python GraphQL client library, but there are others. +# See https://graphql.org/community/tools-and-libraries/?tags=python_client + +from gql import gql, Client +from gql.transport.aiohttp import AIOHTTPTransport + +transport = AIOHTTPTransport(url="https://gnomad.broadinstitute.org/api") +client = Client(transport=transport, fetch_schema_from_transport=True) + +# For brevity, and to keep the focus on the Python code, we don't include every +# field from the raw query here. + +query = gql( + """ + query VariantsInGene { + gene(gene_symbol: "BRCA1", reference_genome: GRCh38) { + variants(dataset: gnomad_r4) { + variant_id + pos + exome { + ac + ac_hemi + ac_hom + an + af + } + } + } + } +""" +) + +# Execute the query on the transport +result = client.execute(query) +print(result) + + +
+
+ + // This example uses only the JS standard library, but more sophisticated +// clients are also available. See +// https://graphql.org/community/tools-and-libraries/?tags=javascript_client + +// For brevity, and to keep the focus on the JS code, we don't include every +// field from the raw query here. + +query = \` + query VariantsInGene { + gene(gene_symbol: "BRCA1", reference_genome: GRCh38) { + variants(dataset: gnomad_r4) { + variant_id + pos + exome { + ac + ac_hemi + ac_hom + an + af + } + } + } + }\`; + +fetch("https://gnomad.broadinstitute.org/api", { + method: "POST", + headers: { + "Content-Type": "application/json", + Accept: "application/json", + }, + body: JSON.stringify({ query }), +}) + .then((r) => r.json()) + .then((data) => console.log(JSON.stringify(data))); + + +
+
+
diff --git a/browser/src/DownloadsPage/downloadsHooks.ts b/browser/src/DataPage/downloadsHooks.ts similarity index 100% rename from browser/src/DownloadsPage/downloadsHooks.ts rename to browser/src/DataPage/downloadsHooks.ts diff --git a/browser/src/DownloadsPage/downloadsPageStyles.tsx b/browser/src/DataPage/downloadsPageStyles.tsx similarity index 97% rename from browser/src/DownloadsPage/downloadsPageStyles.tsx rename to browser/src/DataPage/downloadsPageStyles.tsx index 7ac96460a..048b2fe10 100644 --- a/browser/src/DownloadsPage/downloadsPageStyles.tsx +++ b/browser/src/DataPage/downloadsPageStyles.tsx @@ -396,3 +396,20 @@ export const DownloadLinks = ({ ) } + +export const CodeBlock = styled.code` + display: inline-block; + box-sizing: border-box; + max-width: 100%; + padding: 0.5em 1em; + border-radius: 0.25em; + background: #333; + color: #fafafa; + font-family: monospace; + line-height: 1.6; + white-space: nowrap; + + &::before { + content: '$ '; + } +` diff --git a/browser/src/DataPage/exampleJSGraphQLQuery.ts b/browser/src/DataPage/exampleJSGraphQLQuery.ts new file mode 100644 index 000000000..b6291dcf4 --- /dev/null +++ b/browser/src/DataPage/exampleJSGraphQLQuery.ts @@ -0,0 +1,37 @@ +const content = `// This example uses only the JS standard library, but more sophisticated +// clients are also available. See +// https://graphql.org/community/tools-and-libraries/?tags=javascript_client + +// For brevity, and to keep the focus on the JS code, we don't include every +// field from the raw query here. + +query = \` + query VariantsInGene { + gene(gene_symbol: "BRCA1", reference_genome: GRCh38) { + variants(dataset: gnomad_r4) { + variant_id + pos + exome { + ac + ac_hemi + ac_hom + an + af + } + } + } + }\`; + +fetch("https://gnomad.broadinstitute.org/api", { + method: "POST", + headers: { + "Content-Type": "application/json", + Accept: "application/json", + }, + body: JSON.stringify({ query }), +}) + .then((r) => r.json()) + .then((data) => console.log(JSON.stringify(data))); +` + +export default content diff --git a/browser/src/DataPage/examplePythonGraphQLQuery.ts b/browser/src/DataPage/examplePythonGraphQLQuery.ts new file mode 100644 index 000000000..4f401a664 --- /dev/null +++ b/browser/src/DataPage/examplePythonGraphQLQuery.ts @@ -0,0 +1,38 @@ +const content = `# GQL is one popular Python GraphQL client library, but there are others. +# See https://graphql.org/community/tools-and-libraries/?tags=python_client + +from gql import gql, Client +from gql.transport.aiohttp import AIOHTTPTransport + +transport = AIOHTTPTransport(url="https://gnomad.broadinstitute.org/api") +client = Client(transport=transport, fetch_schema_from_transport=True) + +# For brevity, and to keep the focus on the Python code, we don't include every +# field from the raw query here. + +query = gql( + """ + query VariantsInGene { + gene(gene_symbol: "BRCA1", reference_genome: GRCh38) { + variants(dataset: gnomad_r4) { + variant_id + pos + exome { + ac + ac_hemi + ac_hom + an + af + } + } + } + } +""" +) + +# Execute the query on the transport +result = client.execute(query) +print(result) +` + +export default content diff --git a/browser/src/DataPage/exampleRawGraphQLQuery.ts b/browser/src/DataPage/exampleRawGraphQLQuery.ts new file mode 100644 index 000000000..8c3c64a2b --- /dev/null +++ b/browser/src/DataPage/exampleRawGraphQLQuery.ts @@ -0,0 +1,126 @@ +const content = `# Lines beginning with a "#" character are comments that are ignored by the API. +# +# "VariantsInGene" is the operation name for the query. This is optional but +# recommended. +# +query VariantsInGene { + # We could alternatively look up the gene by Ensembl ID by using the + # "gene_id" argument rather than "gene_symbol". + # + # The gene symbol is given with quotes, but not the reference genome or + # dataset. This is because the gene symbol is defined in the API schema as a + # string, but the reference genome is an enumerated type that can have only + # the value GRCh37 or GRCh38, and the dataset argument is constrained + # similarly. See + # https://graphql.org/learn/schema/#enumeration-types. + # + gene(gene_symbol: "BRCA1", reference_genome: GRCh38) { + variants(dataset: gnomad_r4) { + variant_id + + # Position + pos + + # dbSNP reference SNP IDs + rsids + + transcript_id + transcript_version + + # HGVS DNA, coding sequence, and protein consequences + hgvs + hgvsc + hgvsp + + # VEP annotation + consequence + + # Flags on the variant generally + flags + + # The API separates the frequency data into exome data, genome data, and + # joint-frequency data. Which of these are available depends on the + # dataset used, and not all variants in a dataset necessarily have all + # of the possible kinds. + # + # Note that the exome and genome data have the same schema, but joint- + # frequency data is slightly different. + # + exome { + # Full allele count, and hemizygote/homozygote allele counts. + ac + ac_hemi + ac_hom + + # Allele number + an + + # Allele frequency + af + + # Allele counts and numbers by population + populations { + id + ac + an + ac_hemi + ac_hom + } + + # Filters and flags for exome data + filters + flags + } + + # Schema for genome data is same for that as exome data + genome { + ac + ac_hemi + ac_hom + an + af + populations { + id + ac + an + ac_hemi + ac_hom + } + filters + flags + } + + joint { + # Full allele count, and hemizygote/homozygote allele counts. + ac + hemizygote_count + homozygote_count + + # Allele number + an + + # Allele counts and numbers by population + populations { + id + ac + an + homozygote_count + hemizygote_count + } + + # Filters for joint-frequency data + filters + } + + # In-silico variant prediction annotations + in_silico_predictors { + id + value + flags + } + } + } +} +` + +export default content diff --git a/browser/src/NavBar.tsx b/browser/src/NavBar.tsx index b2c31d01d..397ffe7c6 100644 --- a/browser/src/NavBar.tsx +++ b/browser/src/NavBar.tsx @@ -114,7 +114,6 @@ const NavBar = () => { Stats - {/* two tags instead of s because the blog is a separate application */}
  • Policies @@ -125,6 +124,7 @@ const NavBar = () => { Publications
    • + {/* two     tags instead of s because the blog is a separate application */}
  • Blog
    • @@ -132,8 +132,8 @@ const NavBar = () => { Changelog
  • - - Downloads + + Data
  • diff --git a/browser/src/Routes.tsx b/browser/src/Routes.tsx index 18d441ee9..3da7b2f46 100644 --- a/browser/src/Routes.tsx +++ b/browser/src/Routes.tsx @@ -12,7 +12,7 @@ import { DatasetId } from '@gnomad/dataset-metadata/metadata' const AboutPage = lazy(() => import('./AboutPage')) const TeamPage = lazy(() => import('./TeamPage/TeamPage')) const ContactPage = lazy(() => import('./ContactPage')) -const DownloadsPage = lazy(() => import('./DownloadsPage/DownloadsPage')) +const DataPage = lazy(() => import('./DataPage/DataPage')) const HelpPage = lazy(() => import('./help/HelpPage')) const HelpTopicPage = lazy(() => import('./help/HelpTopicPage')) const HomePage = lazy(() => import('./HomePage')) @@ -169,7 +169,9 @@ const Routes = () => { - + + + diff --git a/browser/src/__snapshots__/NavBar.spec.tsx.snap b/browser/src/__snapshots__/NavBar.spec.tsx.snap index f6fba0760..97006914a 100644 --- a/browser/src/__snapshots__/NavBar.spec.tsx.snap +++ b/browser/src/__snapshots__/NavBar.spec.tsx.snap @@ -389,10 +389,10 @@ exports[`NavBar has no unexpected changes 1`] = `
  • - Downloads + Data
  • diff --git a/browser/src/help/__snapshots__/HelpPage.spec.tsx.snap b/browser/src/help/__snapshots__/HelpPage.spec.tsx.snap index 4c27a5cdd..4fb34a0db 100644 --- a/browser/src/help/__snapshots__/HelpPage.spec.tsx.snap +++ b/browser/src/help/__snapshots__/HelpPage.spec.tsx.snap @@ -10030,9 +10030,9 @@ Unfortunately, for many reasons (including consent and data usage restrictions) question: 'How do I query a batch of variants? Do you have an API?' --- -We currently do not have a way to submit batch queries on the browser, but we are actively working on developing a public API for gnomAD. We currently maintain a [GraphQL](https://graphql.org) API for internal use and groups can contact us if they want permission to use this API until a more robust public solution is launched. +The [GraphQL](https://graphql.org) API used by the browser is open to the public. Please see our [data page](/data) for details. -You can also obtain information on all variants from the VCFs and Hail Tables available on our [downloads page](/downloads). +You can also obtain information on all variants from the VCFs and Hail Tables available on our [data page](/data). ", } }