# Biomarkers: pharma biomarkers

The pharma biomarkers commands, with each dataset's columns, units and source credit.

A gene, protein variant or other biomarker with the evidence recorded for it.

Id: A biomarker route key, the id the web pages use: the gene symbol for a gene (BRAF, ERBB2), f.<feature> for a feature (f.pd-l1), v.<gene>.<change>.<hash> for a protein variant. Every biomarker dataset takes this same key. Evidence, literature, publishing-company and variant-mention datasets are gene-level: enter on the gene's route key. Matching is exact, case included.

## Commands

| Command | Reads |
| --- | --- |
| pharma biomarkers list | Biomarkers |
| pharma biomarkers get <id> | One biomarker and the datasets reachable from it |
| pharma biomarkers get <id> biomarker-bqp-assertions | FDA biomarker qualification projects |
| pharma biomarkers get <id> biomarker-cdx-assertions | FDA companion diagnostic assertions |
| pharma biomarkers get <id> biomarker-evidence | Biomarker evidence |
| pharma biomarkers get <id> biomarker-literature | Trial-cited literature mentions |
| pharma biomarkers get <id> biomarker-publishing-companies | Companies publishing on a biomarker |
| pharma biomarkers get <id> biomarker-relations | Literature-extracted relations |
| pharma biomarkers get <id> biomarker-sample-coverage | Human sample screening coverage (GDC) |
| pharma biomarkers get <id> biomarker-sample-prevalence | Human sample screening reference (GDC cohorts) |
| pharma biomarkers get <id> biomarker-validation | Biomarker validation ladder |
| pharma biomarkers get <id> biomarker-variant-mentions | Protein variant mentions |

Every command takes the paging, sorting and output flags described on the CLI page; the CLI prints the source credit with every result.

- [Pharma Observatory CLI](https://pharmaobservatory.com/cli)

## Biomarkers

**Command**

```sh
pharma biomarkers list
```

The biomarkers object type's primary dataset, with the evidence counts by type.

One row per: biomarker (a gene, protein variant or other feature). Key columns: `biomarker_id`.

Source: Cancer Genome Interpreter, IRB Barcelona/ICREA/UPF (CC BY 4.0); UniProt (CC BY 4.0); ClinicalTrials.gov via AACT, CTTI (CC BY); NCI Genomic Data Commons; Open Targets Platform (CC0); PubMed, NCBI/NLM; US FDA

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| biomarker_id | text |  | The biomarker key. |
| route_key | text |  | The biomarker's route key, the id the web page uses and the one entry key every biomarker dataset takes (the gene symbol for a gene biomarker). |
| biomarker_kind | text |  | gene, protein_variant or another feature kind. |
| identity_status | text |  | Whether the biomarker's identity is confirmed. |
| display_name | text |  | The biomarker's display name. |
| parent_biomarker_id | text |  | The parent biomarker (a variant's gene). |
| gene_symbol | text |  | The gene symbol. |
| amino_acid_change | text |  | The amino-acid change, for a variant. |
| target_id | text |  | The target's Ensembl gene id. |
| hgnc_id | text |  | The HUGO Gene Nomenclature Committee (HGNC) gene id. |
| uniprot_accession | text |  | The UniProt accession. |
| feature_code | text |  | Feature code for a non-gene feature. |
| feature_type | text |  | Feature type for a non-gene feature. |
| evidence_tier | integer |  | Strongest evidence tier: 1 companion diagnostic of the US Food and Drug Administration (FDA) through 6 no evidence. |
| evidence_tier_label | text |  | The tier's name. |
| n_fda_cdx_assertions | integer | assertions | FDA companion diagnostic assertions. |
| n_fda_bqp_assertions | integer | assertions | FDA biomarker qualification project assertions. |
| n_cancer_actionable_cgi | integer | assertions | Cancer Genome Interpreter actionable rows. |
| n_ot_association | integer | associations | Open Targets target-disease associations. |
| n_trial_mention | integer | trial mentions | Trials that name the biomarker. |
| n_publication_variant_mentions | integer | papers | Publication variant mentions. |
| has_clinical_validation_evidence | boolean |  | Whether clinical validation evidence exists. |
| has_analytical_validation_evidence | boolean |  | Whether analytical validation evidence exists. |
| n_assay_provider_papers | integer | papers | Papers naming an assay provider for the biomarker. |
| n_assay_provider_suppliers | integer |  | Assay-provider suppliers named. |
| n_diagnostic_provider_suppliers | integer |  | Of those, diagnostic providers. |

## FDA biomarker qualification projects

**Command**

```sh
pharma biomarkers get <id> biomarker-bqp-assertions
```

Projects in the US Food and Drug Administration (FDA) Biomarker Qualification Program for a biomarker, with the submitter's company and group keys. Only a source status of exactly qualified is FDA-qualified.

One row per: FDA Biomarker Qualification Program assertion for a biomarker. Key columns: `source_assertion_id`.

Source: US FDA

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| source_assertion_id | text |  | The assertion id. |
| route_key | text |  | The biomarker's route key, the entry key for the biomarkers object type. |
| biomarker_id | text |  | The biomarker key. |
| ddt_number | text |  | The drug development tool number the US Food and Drug Administration (FDA) assigns the project. |
| ddt_project_id | text |  | The FDA project id. |
| project_name | text |  | The project's name. |
| bqp_signal | text |  | The source status of the project. Only qualified means FDA-qualified; every other value is a project status. |
| is_fda_qualified | boolean |  | True only when the source status is exactly qualified. |
| submission_status | text |  | The submission status as the source words it. |
| submission_stage | text |  | The submission stage as the source words it. |
| submitter_name | text |  | The submitter as the source names it. |
| submitter_org_id | text |  | Legal-entity level: the organization record the submitter resolved to (null when unresolved). |
| submitter_company_id | text |  | Company level: the company the submitter belongs to (null when unresolved). |
| submitter_company_name | text |  | Display name of the submitter's company. |
| submitter_group_id | text |  | Group level: the submitter's current ultimate parent company; a root company's group is itself. |
| submitter_group_name | text |  | Display name of the submitter's group. |
| submitter_match_tier | text |  | How the submitter name matched an organization record. |
| submitter_role | text |  | The submitter's role on the project. |
| biomarker_role | text |  | The biomarker's role in the project (for example a diagnostic or a surrogate endpoint). |
| biomarker_role_method | text |  | How the biomarker role was assigned. |
| is_surrogate_endpoint_claim | boolean |  | True when the project claims a surrogate endpoint. |
| source_url | text |  | Link to the FDA project page. |
| snapshot_date | date |  | The date the source list was captured. |

## FDA companion diagnostic assertions

**Command**

```sh
pharma biomarkers get <id> biomarker-cdx-assertions
```

Companion diagnostics of the US Food and Drug Administration (FDA) for a biomarker, one row per assertion, with the manufacturer's company and group keys.

One row per: FDA companion diagnostic assertion for a biomarker. Key columns: `source_assertion_id`.

Source: US FDA

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| source_assertion_id | text |  | The assertion id. |
| route_key | text |  | The biomarker's route key, the entry key for the biomarkers object type. |
| biomarker_id | text |  | The biomarker key. |
| biomarker_token | text |  | The biomarker as the FDA list names it. |
| diagnostic_name | text |  | The companion diagnostic's name. |
| indication | text |  | The indication. |
| sample_type | text |  | The sample type. |
| submission_cell | text |  | The submission number cell as listed. |
| latest_stated_decision_date | date |  | Latest decision date the list states. |
| source_url | text |  | Link to the FDA list. |
| manufacturer_name | text |  | The manufacturer as filed. |
| manufacturer_org_id | text |  | Legal-entity level: the organization record the manufacturer resolved to (null when unresolved). |
| manufacturer_company_id | text |  | Company level: the company the manufacturer belongs to (null when unresolved). |
| manufacturer_company_name | text |  | Display name of the manufacturer's company. |
| manufacturer_group_id | text |  | Group level: the manufacturer's current ultimate parent company; a root company's group is itself. |
| manufacturer_group_name | text |  | Display name of the manufacturer's group. |
| manufacturer_match_tier | text |  | How firmly the manufacturer name matched an organization. |

## Biomarker evidence

**Command**

```sh
pharma biomarkers get <id> biomarker-evidence
```

One evidence dataset in place of the cgi, ot_association and trial_mention sections: filter by evidence_type.

One row per: evidence assertion. Key columns: `biomarker_evidence_id`.

Source: Cancer Genome Interpreter, IRB Barcelona/ICREA/UPF (CC BY 4.0); Open Targets Platform (CC0); ClinicalTrials.gov via AACT, CTTI (CC BY)

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| biomarker_evidence_id | text |  | The evidence assertion id. |
| route_key | text |  | The biomarker route key of the gene this evidence is about (the gene symbol); the entry key for the biomarkers object type. |
| gene_symbol | text |  | The gene symbol the evidence is about. |
| target_id | text |  | The target's Ensembl gene id. |
| uniprot_accession | text |  | The UniProt accession. |
| biomarker | text |  | The biomarker as the source names it (the gene or the variant). |
| evidence_type | text |  | cancer_actionable_cgi, ot_association or trial_mention. |
| source | text |  | The source the assertion comes from. |
| condition_id | text |  | The condition key. |
| condition_name | text |  | The condition as the source names it. |
| therapeutic_area | text |  | The therapeutic area. |
| drug_name | text |  | The drug as filed. |
| drug_id | text |  | The drug key. |
| molecule_id | text |  | The molecule key. Null on every row: no evidence row carries a molecule. |
| response | text |  | The reported response (for example Responsive, Resistant). |
| score | double |  | The association score, for an Open Targets row. |
| variant_count | integer | variants | Variants the assertion covers. |
| trial_id | text |  | The trial registry id, for a trial-mention row. |
| sample_type | text |  | The sample type, for a trial-mention row. |

## Trial-cited literature mentions

**Command**

```sh
pharma biomarkers get <id> biomarker-literature
```

Papers in the trial-cited corpus whose annotation names a biomarker gene, with citation metrics where iCite (the National Institutes of Health citation-metrics service) carries them.

One row per: gene and paper. Key columns: `route_key`, `pmid`.

Source: PubMed, NCBI/NLM; iCite, NIH Office of Portfolio Analysis

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| route_key | text |  | The route key of the gene the paper names, the entry key for the biomarkers object type. |
| gene_symbol | text |  | The gene symbol. |
| pmid | text |  | The PubMed id. |
| evidence_type | text |  | The evidence type (a publication mention). |
| title | text |  | The paper's title. |
| journal_nlm_id | text |  | The journal's National Library of Medicine (NLM) id. |
| journal_title | text |  | The journal's title. |
| pub_year | integer | calendar year | The publication year. |
| citation_count | integer | citations | Citations, where iCite carries them (null is not measured, never zero). |
| relative_citation_ratio | numeric |  | The iCite relative citation ratio, where measured. |
| display_order | bigint |  | The page's fixed order: newest year first, then citations. |

## Companies publishing on a biomarker

**Command**

```sh
pharma biomarkers get <id> biomarker-publishing-companies
```

The companies that publish on a biomarker, one row per biomarker gene and company, counted from paper-level evidence.

One row per: biomarker gene and company. Key columns: `gene_symbol`, `publisher_company_id`.

Source: PubMed, NCBI/NLM

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| route_key | text |  | The biomarker route key of the gene the papers name (the gene symbol); the entry key for the biomarkers object type. |
| gene_symbol | text |  | The gene symbol. |
| publisher_company_id | text |  | Company level: the publisher's company. |
| publisher_company_name | text |  | Display name of the publisher's company. |
| publisher_group_id | text |  | Group level: the publisher's current ultimate parent company; a root company's group is itself. |
| publisher_group_name | text |  | Display name of the publisher's group. |
| n_publications | integer | papers | Papers that name the gene from the company's organizations (a consortium paper is excluded). |
| n_member_orgs | integer | organization records | The company's organizations the papers reach. |
| best_match_tier | text |  | Strongest affiliation match tier. |
| first_pub_year | integer | calendar year | Earliest publication year. |
| last_pub_year | integer | calendar year | Latest publication year. |
| supporting_pmids | text[] |  | A sample of the supporting PubMed ids. |
| supporting_pmids_truncated | boolean |  | True when the sample is shorter than the paper count. |
| n_papers_excluded_as_consortium | integer |  | Papers left out because they name too many organizations. |

## Literature-extracted relations

**Command**

```sh
pharma biomarkers get <id> biomarker-relations
```

Automated PubTator relation labels between a biomarker and a related gene, drug or condition, one row per related entity, source relation label and paper.

One row per: biomarker, related entity, source relation label and paper. Key columns: `biomarker_id`, `related_entity_kind`, `related_entity_id`, `relation_type`, `pmid`.

Source: PubMed, NCBI/NLM

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| route_key | text |  | The biomarker's own route key, the entry key for the biomarkers object type (the gene symbol for a gene, the variant key for a protein variant). |
| biomarker_id | text |  | The biomarker's key. |
| biomarker_kind | text |  | Whether the row describes a gene or a protein variant. |
| gene_symbol | text |  | The gene symbol. |
| amino_acid_change | text |  | The protein change, for a variant. |
| related_entity_kind | text |  | The kind of the related entity (gene, drug or condition). |
| related_entity_id | text |  | The related entity's key in its own vocabulary (a gene symbol, a drug id such as unii:..., or a condition key). |
| related_display_name | text |  | The related entity's name. |
| relation_type | text |  | The source's relation label, as the source states it. |
| pmid | text |  | The PubMed id of the paper the relation was extracted from. |
| title | text |  | The paper's title. |
| journal_nlm_id | text |  | The journal's National Library of Medicine (NLM) id. |
| journal_title | text |  | The journal's title. |
| pub_year | integer | calendar year | The paper's publication year. |
| n_source_assertions | bigint | assertions | Source assertions of this relation in the paper. |
| n_relation_papers | bigint | papers | Papers that carry this biomarker, related entity and relation label. |
| evidence_type | text |  | The evidence type (a text-mined relation, never a clinical claim). |
| source | text |  | The source of the evidence. |
| display_order | bigint |  | The order the web page lists the relation in within its kind. |

## Human sample screening coverage (GDC)

**Command**

```sh
pharma biomarkers get <id> biomarker-sample-coverage
```

How each protein variant of a gene matched the somatic-mutation catalogue of the National Cancer Institute Genomic Data Commons (GDC), one row per variant and data release, so a variant with no exact match or several matches is a row with its status.

One row per: protein variant and GDC data release. Key columns: `variant_biomarker_id`, `gdc_data_release`.

Source: NCI Genomic Data Commons

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| route_key | text |  | The route key of the gene the variants belong to, the entry key for the biomarkers object type. |
| gene_symbol | text |  | The gene symbol. |
| variant_biomarker_id | text |  | The variant's own biomarker key. |
| variant_route_key | text |  | The variant's own route key (the id its web page uses). |
| amino_acid_change | text |  | The protein change, for example p.V600E. |
| gdc_data_release | text |  | The Genomic Data Commons data release the match was made against. |
| normalization_status | text |  | How the variant matched: resolved_single_ssm, no_exact_ssm, multiple_exact_ssms or source_error. |
| match_count | integer | mutations | Somatic mutations in the catalogue that encode the same protein change. |
| resolution_reason | text |  | The reason for the status, in words. |
| measured_project_count | bigint | projects | Research projects with an observed frequency for the variant in biomarker_sample_prevalence. |

## Human sample screening reference (GDC cohorts)

**Command**

```sh
pharma biomarkers get <id> biomarker-sample-prevalence
```

Exact protein-variant observations in named research cohorts of the National Cancer Institute Genomic Data Commons (GDC), one row per variant, cohort and data release. A screening reference for named cohorts.

One row per: protein variant, GDC research cohort and data release. Key columns: `variant_biomarker_id`, `gdc_project_id`, `gdc_data_release`.

Source: NCI Genomic Data Commons

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| route_key | text |  | The route key of the gene the variants belong to, the entry key for the biomarkers object type. |
| gene_symbol | text |  | The gene symbol. |
| variant_biomarker_id | text |  | The variant's own biomarker key. |
| variant_route_key | text |  | The variant's own route key (the id its web page uses). |
| amino_acid_change | text |  | The protein change, for example p.V600E. |
| gdc_ssm_id | text |  | The identifier of the somatic mutation in the Genomic Data Commons. |
| gdc_project_id | text |  | The Genomic Data Commons research project (cohort) the counts come from. |
| gdc_project_name | text |  | The name of the research project. |
| condition_id | text |  | The condition key (a MeSH, Medical Subject Headings, descriptor id) the project's disease maps to, where one is mapped. |
| condition_name | text |  | The mapped condition's MeSH heading. |
| source_disease_types | text[] |  | The disease types the source states for the project. |
| source_primary_sites | text[] |  | The primary sites the source states for the project. |
| affected_case_count | bigint | cases | Cases in the cohort with the exact variant. |
| ssm_profiled_case_count | bigint | cases | Cases in the cohort profiled for somatic mutations, the denominator of the observed frequency. |
| all_case_count | bigint | cases | All cases in the project. |
| observed_frequency | numeric | fraction | Affected cases over mutation-profiled cases in this cohort. |
| frequency_ci95_low | numeric | fraction | Lower bound of the 95 percent confidence interval of the observed frequency. |
| frequency_ci95_high | numeric | fraction | Upper bound of the 95 percent confidence interval of the observed frequency. |
| gdc_data_release | text |  | The Genomic Data Commons data release the counts come from. |
| claim_type | text |  | What the figure states; an observed frequency in a named cohort. |

## Biomarker validation ladder

**Command**

```sh
pharma biomarkers get <id> biomarker-validation
```

The validation ladder of a gene: which organizations can supply evidence toward running its assay, in what role, at what tier and citing what, across six kinds of evidence (companion diagnostic authorization, trial endpoint, trial eligibility, trial specimen collection, trial text mention and ClinVar clinical testing).

One row per: evidence assertion on a gene. Key columns: `biomarker_validation_id`.

Source: ClinicalTrials.gov via AACT, CTTI (CC BY); US FDA; ClinVar, NCBI/NLM

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| biomarker_validation_id | text |  | The evidence assertion id. |
| route_key | text |  | The biomarker's route key, the entry key for the biomarkers object type; for a gene it is the gene symbol. |
| gene_symbol | text |  | The gene symbol (HGNC, the HUGO Gene Nomenclature Committee). |
| biomarker_id | text |  | The biomarker key. |
| biomarker_display_name | text |  | The biomarker's display name. |
| biomarker_kind | text |  | The kind of biomarker the evidence is filed against. |
| organization_name | text |  | The organization that can supply the evidence, as the source names it (null when the source names none that resolved). |
| organization_org_id | text |  | Legal-entity level: the organization record (null when unresolved). |
| organization_company_id | text |  | Company level: the organization's company (null when unresolved). |
| organization_company_name | text |  | Display name of the organization's company. |
| organization_group_id | text |  | Group level: the organization's current ultimate parent; a root's group is itself. |
| organization_group_name | text |  | Display name of the organization's group. |
| organization_role | text |  | What the organization is to the evidence: lead_sponsor, collaborator, contract_vendor, assay_manufacturer, qualification_submitter, testing_lab or publishing_org. |
| organization_match_tier | text |  | How the organization name matched an organization record. |
| tier | integer |  | The rung on the validation ladder, 1 to 4. A rung is a kind of evidence, never a score: rows are not ranked across organizations or evidence types. |
| tier_label | text |  | The rung's name, for example fda_authorized_companion_diagnostic or named_in_inclusion_criteria. |
| evidence_type | text |  | The evidence lane: fda_bqp_qualification, fda_cdx_authorization, aact_endpoint_role, aact_eligibility_section, aact_biospecimen, trial_mention or clinvar_clinical_testing. |
| evidence_count | integer |  | Sibling rows sharing this biomarker, organization and role. Not the number of source records behind a ClinVar row (clinvar_scv_count). |
| evidence_ref | text |  | The source reference the row cites. |
| evidence_ref_kind | text |  | What kind of reference evidence_ref is. |
| trial_id | text |  | The trial key (an NCT id) when the evidence is a trial; null otherwise. |
| citation_url | text |  | A link to the cited record. |
| citation_verified | boolean |  | False for the FDA Biomarker Qualification Program arm, whose captured links are known to go stale; true otherwise. A link marked false may not resolve. |
| evidence_snippet | text |  | The text span the evidence rests on, where the source gives one. |
| biomarker_role | text |  | The biomarker's role in the evidence, where the source states it. |
| is_surrogate_endpoint_claim | boolean |  | True when the evidence is a claim that the biomarker is a surrogate endpoint. |
| clinvar_scv_count | integer |  | For a ClinVar row, the number of ClinVar submission records the row collapses; null otherwise. |

## Protein variant mentions

**Command**

```sh
pharma biomarkers get <id> biomarker-variant-mentions
```

Exact protein variants of a gene that papers in the trial-cited corpus name, with the paper counts and sample citations.

One row per: protein variant biomarker with literature mentions. Key columns: `variant_biomarker_id`.

Source: PubMed, NCBI/NLM

| Column | Type | Unit | Description |
| --- | --- | --- | --- |
| route_key | text |  | The route key of the gene the variants belong to, the entry key for the biomarkers object type. |
| gene_symbol | text |  | The gene symbol. |
| variant_biomarker_id | text |  | The variant's own biomarker key. |
| variant_route_key | text |  | The variant's own route key (the id its web page uses). |
| display_name | text |  | The variant's display name. |
| amino_acid_change | text |  | The protein change, for example V600E. |
| biomarker_kind | text |  | The kind of biomarker the row describes (a protein variant). |
| evidence_type | text |  | The evidence type (a literature mention, never an actionability claim). |
| source | text |  | The source of the evidence. |
| n_papers | bigint | papers | Distinct papers that name the variant. |
| first_publication_year | integer | calendar year | Earliest publication year. |
| last_publication_year | integer | calendar year | Latest publication year. |
| sample_pmids | text[] |  | Up to five sample PubMed ids, newest first. |
| sample_citations | text[] |  | Up to five sample citations, newest first. |