Open Targets入門 #3：Python + GraphQL APIでデータを取得する

Open Targets入門 #2：Platform UIで疾患から創薬ターゲットを探すでは、アルツハイマー病から創薬ターゲット候補を画面上で探索しました。APP、APOE、PSEN1などのターゲットをAssociated Targets・Target Prioritisation・Evidenceページで深掘りする流れを見ました。

今回は同じ発想を、Python + GraphQL APIで再現します。UIで見ていたAssociated Targetsの一覧をプログラムから取得し、pandasのDataFrameに整形してCSVとして保存します。

本記事はOpen Targetsシリーズの第3回です。

例として使用する疾患は、前回と同じアルツハイマー病（Alzheimer disease）です。APIクエリでは MONDO_0004975 を指定します。

分析環境を準備する

必要なものはPython本体と、HTTPリクエスト・表形式データ処理用の最小限のライブラリです。

インストールは以下で十分です。

python -m pip install requests pandas

仮想環境を使う場合は、先に以下のように作成してからインストールします。

python -m venv .venv
source .venv/bin/activate
python -m pip install requests pandas

GraphQL APIでデータを取得する仕組み

Open Targets PlatformのGraphQL API endpointは以下です。

https://api.platform.opentargets.org/api/v4/graphql

GraphQLでは、REST APIのようにURLパスを細かく切り替えるのではなく、1つのendpointに対して「どのフィールドが欲しいか」をqueryとして送ります。

本記事で使うqueryは以下です。ページネーションは page: { index, size } 形式で指定します。

query AssociatedTargets($efoId: String!, $index: Int!, $size: Int!) {
  disease(efoId: $efoId) {
    associatedTargets(page: { index: $index, size: $size }) {
      count
      rows {
        target { id approvedSymbol approvedName }
        score
        datatypeScores { id score }
      }
    }
  }
}

変数は以下のように渡します。

{
  "efoId": "MONDO_0004975",
  "index": 0,
  "size": 20
}

curlで最小動作確認をする

Pythonを書く前に、curl で最小限のPOSTリクエストを確認できます。

curl -sS -X POST https://api.platform.opentargets.org/api/v4/graphql \
  -H 'Content-Type: application/json' \
  --data-binary @- <<'JSON'
{
  "query": "query AssociatedTargets($efoId: String!, $index: Int!, $size: Int!) { disease(efoId: $efoId) { associatedTargets(page: { index: $index, size: $size }) { count rows { target { id approvedSymbol approvedName } score datatypeScores { id score } } } } }",
  "variables": {
    "efoId": "MONDO_0004975",
    "index": 0,
    "size": 20
  }
}
JSON

Pythonで全件取得するコード

以下は、アルツハイマー病に関連するターゲット一覧を取得し、datatype別スコアを列に展開してCSV保存する完全なコードです。

import requests
import pandas as pd


ENDPOINT = "https://api.platform.opentargets.org/api/v4/graphql"

QUERY = """
query AssociatedTargets($efoId: String!, $index: Int!, $size: Int!) {
  disease(efoId: $efoId) {
    associatedTargets(page: { index: $index, size: $size }) {
      count
      rows {
        target { id approvedSymbol approvedName }
        score
        datatypeScores { id score }
      }
    }
  }
}
"""


def fetch_associated_targets(efo_id, page_size=500):
    rows = []
    index = 0
    total_count = None

    while True:
        variables = {
            "efoId": efo_id,
            "index": index,
            "size": page_size,
        }
        response = requests.post(
            ENDPOINT,
            json={"query": QUERY, "variables": variables},
            timeout=60,
        )
        response.raise_for_status()
        payload = response.json()

        if "errors" in payload:
            raise RuntimeError(payload["errors"])

        associated_targets = payload["data"]["disease"]["associatedTargets"]
        if total_count is None:
            total_count = associated_targets["count"]

        page_rows = associated_targets["rows"]
        rows.extend(page_rows)

        if not page_rows or len(rows) >= total_count:
            break

        index += 1

    return rows


def rows_to_dataframe(rows):
    records = []

    for row in rows:
        target = row["target"]
        record = {
            "target_id": target["id"],
            "approved_symbol": target["approvedSymbol"],
            "approved_name": target["approvedName"],
            "overall_score": row["score"],
        }

        for datatype_score in row.get("datatypeScores", []):
            column_name = f"score_{datatype_score['id']}"
            record[column_name] = datatype_score["score"]

        records.append(record)

    df = pd.DataFrame(records)
    df = df.sort_values("overall_score", ascending=False).reset_index(drop=True)
    return df


def main():
    EFO_ID = "MONDO_0004975"

    rows = fetch_associated_targets(EFO_ID)
    df = rows_to_dataframe(rows)

    output_path = f"open_targets_associated_targets_{EFO_ID}.csv"
    df.to_csv(output_path, index=False)

    print(f"Saved: {output_path}")
    print(df.head(20))


if __name__ == "__main__":
    main()

APIから返る associatedTargets.count を見ながら index を1ずつ増やしてページを取得します。1ページ目だけを取る場合は page_size=20 でも十分ですが、後で疾患ごとの全候補を比較したい場合に備えて、関数側のデフォルトは page_size=500 にしています。

実行するとどうなるか

python main.py を実行すると、まずAPIへのリクエストが走り（アルツハイマー病では全件取得に数秒かかります）、以下のような出力が得られます。

Saved: open_targets_associated_targets_MONDO_0004975.csv
        target_id approved_symbol  ...  overall_score
0  ENSG00000142192             APP  ...          0.870
1  ENSG00000080815           PSEN1  ...          0.866
2  ENSG00000164458           PSEN2  ...          0.817
3  ENSG00000130203            APOE  ...          0.775
4  ENSG00000176884           GRIN1  ...          0.700
...

保存されるCSVの列構成は以下のとおりです。datatypeのエビデンスがないターゲットでは、対応する score_* 列が NaN になります。

target_id, approved_symbol, approved_name, overall_score,
score_genetic_association, score_genetic_literature, score_clinical,
score_affected_pathway, score_literature, score_animal_model,
score_rna_expression, score_somatic_mutation

結果のDataFrameを読む

rows_to_dataframe() の出力では、ネストしたGraphQLレスポンスを解析しやすい横持ちの表に変換します。

Open Targets入門 #1：概要と仕組みを理解するで説明したように、association scoreは単純な件数カウントではありません。各データソース内のエビデンスを**harmonic sum（調和和）**で統合し、datatypeや全体のassociation scoreへ集約します。

datatypeScoresに出てくる主な id は以下です（v26.03実測値）。

前回のUI探索では、APP、APOE、PSEN1をEvidenceページで深掘りしました。APIから得たDataFrameでも、同じターゲットが上位に現れ、どのdatatypeがスコアを支えているかを列として確認できます。

API出力の上位10ターゲット例（v26.03）

以下は MONDO_0004975（Alzheimer disease）を page: { index: 0, size: 10 } で取得した実測結果です。スコアは小数第3位に丸めています。

（—はそのdatatypeのエビデンスがゼロまたは返却なし。列見出しは列名の略記）

APPやPSEN1/PSEN2は clinical（臨床先行性）・genetic_association・literature など複数のdatatypeから強く支えられています。APOEは genetic_association と literature が特に高く、GWAS由来の遺伝的支持と文献蓄積が順位を押し上げています。

各列の解釈の基準は以下のとおりです。

大量取得にはParquet／BigQueryを使う

GraphQL APIは、1つの疾患・ターゲット・ターゲット-疾患ペアを探索的に調べる用途に向いています。数百〜数千の疾患を横断して全ターゲットを集めるような処理には向きません。

Open TargetsのバルクデータはGoogle Cloud Storageでも公開されています。

gs://open-targets-data-releases/

RユーザーはotargenのAPIを確認する

まとめ：API・UI・Parquetの使い分け

本記事では、Open Targets PlatformのGraphQL APIを使って、アルツハイマー病に関連するターゲット一覧をPythonで取得しました。

Open Targets Platformは、UIで仮説を立て、APIで小規模に検証し、Parquet/BigQueryで大規模解析へ広げるという流れで使うと実務に組み込みやすいツールです。

関連記事

関連記事Open Targets入門 #1：概要と仕組みを理解する →

関連記事Open Targets入門 #2：Platform UIで疾患から創薬ターゲットを探す →

参考： - Open Targets Platform - GraphQL API Documentation - Data and code access - Target–disease associations Documentation