opentargets-database

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: opentargets-database
description: >
  Query Open Targets Platform for target-disease associations, drug target
  discovery, tractability/safety data, genetics/omics evidence, known drugs,
  for therapeutic target identification.
---

# Open Targets Database Skill

## Overview

This skill provides access to the Open Targets Platform GraphQL API. It
aggregates multi-modal evidence from genetics (GWAS/eQTL), pathways, animal
models, and clinical trials to rank target-disease associations and identify
druggable genes.

## Prerequisites

1.  **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
    `uv` is installed and on PATH.
2.  **User Notification**: If .licenses/opentargets_database_LICENSE.txt does
    not already exist in the workspace root directory then (1) prominently
    notify the user to check the terms at
    https://platform-docs.opentargets.org/licence, then (2) create the file
    recording the notification text and timestamp.

## Core Rules

-   **Use the Wrapper**: ALWAYS execute the provided helper scripts to query the
    database rather than accessing the database directly. The scripts
    automatically enforce fair use and implement retry logic.
-   **Output Flag**: The `--output` flag is always required as output can be
    very large. Use `jq` or write your own code to process this JSON file.
-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

## Quick Reference

Always use the provided Python script `scripts/query_opentargets.py` to quickly
query the database. It handles API communication, retries, formatting, and
automatically truncates overly large responses. NEVER write your own curl or
similar requests.

**Usage:**

```bash
uv run scripts/query_opentargets.py --output /tmp/opentargets_results.json [OPTIONS] COMMAND [ARGS]...
```

**Common Options:**

-   `--output PATH`: **Required**. Path to write the JSON output file.
-   `--limit N`: Limit the number of items returned in arrays (default is 50).
    Use a smaller number like 10 when doing preliminary exploration.
-   `--page-size N`: Set the API pagination size (default is 200). Increase if
    you need more results (e.g., a study with many credible sets).

**Available Commands:**

-   **`get-gwas-studies`** *`disease_id`*: Fetches all GWAS studies associated
    with a specific disease ID (e.g. `MONDO_0008383` for Rheumatoid Arthritis).
-   **`get-study-credible-sets`** *`study_id`*: Fetches all credible sets for a
    given study ID (e.g. `FINNGEN_R12_RX_CROHN_2NDLINE`). Returns confidence,
    finemapping method, variant, and p-value info.
-   **`get-qtl-credible-sets`** *`variant_id`*: Retrieves QTL credible sets for
    a specific variant ID (e.g. `19_44908822_C_T`).
-   **`get-l2g`** *`variant_id [--study-id ID]`*: Returns Locus-to-Gene (L2G)
    predictions/scores for a locus to identify the most likely causal gene. Only
    `variant_id` is required; use `--study-id` to filter to a specific study.
    Accepts `chr` prefix (e.g. `chr1_113834946_A_G`).
-   **`get-target-druggability`** *`ensembl_id`*: Provides tractability data
    (small molecule, antibody, etc.) and clinical trial safety info for a
    gene/target.
-   **`get-associated-targets`** *`disease_id`*: Find all target genes
    associated with a specific disease ID (EFO or MONDO).
-   **`get-disease-drugs`** *`disease_id [--min-stage STAGE]`*: Find all drugs
    and clinical candidates associated with a disease. Use `--min-stage` to
    filter (e.g., `PHASE_3` for Phase III or Approved).
-   **`get-associated-diseases`** *`ensembl_id`*: Find all diseases associated
    with a specific target Ensembl ID.
-   **`search-disease`** *`query_string`*: Search for a disease by name to find
    its ID and other metadata.
-   **`get-credible-sets-near-target`** *`ensembl_id [--window N]`*: Fetches
    credible sets for a target and filters them to those within a genomic window
    around the target. Useful for finding varian