archs4-database

ARCHS4 Database

概要

ARCHS4（All RNA-seq and ChIP-seq Sample and Signature Search）は、NCBI GEO と SRA のヒトおよびマウスの RNA-seq データを一貫した方法でアラインメントおよび処理したリソースで、100 万件を超えるサンプルを収録しています。https://maayanlab.cloud/archs4/api/ の REST API では、遺伝子レベルの発現プロファイル、z スコアで正規化した組織発現、共発現ネットワーク、サンプルメタデータ検索を、認証なしで利用できます。大規模な一括クエリには、ダウンロード可能な HDF5 発現行列も利用できます。

使用する場面

• 対象遺伝子について、数百種類の組織タイプにわたる組織特異的または細胞タイプ特異的な発現 z スコアを取得する
• クエリ遺伝子と共発現する遺伝子を特定する（共発現ネットワークの構築や関連性による推定分析）
• 組織、疾患、メタデータのキーワードで RNA-seq サンプルを検索し、再解析の候補となるデータセットを特定する
• 複数の遺伝子の発現プロファイルを組織間で比較し、ウェットラボでの追試候補を絞り込む
• 大規模な研究間横断分析のために、一貫した方法で処理された遺伝子発現行列（HDF5 形式）にアクセスする
• 遺伝子の発現方向が集団レベルの組織プロファイルと一致するかを確認し、差次的発現の結果を検証する
• クエリ結果から棒グラフや発現ヒートマップを作成するには、omics-plotting SKILL を使用します
• バリアントレベルの集団アレル頻度には gnomad-database を使用します。ARCHS4 が提供するのは発現に関する情報のみです
• 遺伝子リストから Enrichr 経路エンリッチメントを行うには、gget-genomic-databases（gget enrichr）を使用します。ARCHS4 は発現の検索用です

前提条件

• Python パッケージ：requests、pandas、matplotlib、seaborn
• データ要件：遺伝子シンボル（HGNC 形式。例：TP53、BRCA1）、サンプルを直接クエリする場合は GEO/SRA サンプル ID
• 環境：インターネット接続が必要です。API キーやアカウントは不要です
• レート制限：約 10 リクエスト/秒です。連続して遺伝子をクエリする場合は、スロットリングを避けるために time.sleep(0.1) を挿入してください

pip install requests pandas matplotlib seaborn

クイックスタート

import requests

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def archs4_get(endpoint: str, params: dict = None) -> dict:
    """Send a GET request to the ARCHS4 API and return parsed JSON."""
    r = requests.get(f"{ARCHS4_BASE}/{endpoint}", params=params, timeout=30)
    r.raise_for_status()
    return r.json()

# Quick check: top tissues expressing TP53
data = archs4_get("meta/genes/TP53/zscore")
tissues = data.get("values", [])
print(f"TP53 tissue expression entries: {len(tissues)}")
top5 = sorted(tissues, key=lambda x: x.get("zscore", 0), reverse=True)[:5]
for t in top5:
    print(f"  {t['tissue']:<40}  z={t['zscore']:.2f}")
# TP53 tissue expression entries: 200
#   thymus                                   z=2.81
#   testis                                   z=2.44

コア API

クエリ 1：組織間の遺伝子発現 z スコア

利用可能なすべての組織タイプについて、遺伝子の z スコアで正規化した発現を取得します。z スコアは各サンプルについて集団分布を基準に算出され、正の値は平均を上回る発現を示します。

import requests
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def get_gene_tissue_zscore(gene_symbol: str, species: str = "human") -> pd.DataFrame:
    """Return tissue z-score expression profile for a gene.

    Parameters
    ----------
    gene_symbol : str
        HGNC gene symbol (e.g., 'TP53').
    species : str
        'human' or 'mouse' (default: 'human').
    """
    endpoint = f"meta/genes/{gene_symbol}/zscore"
    r = requests.get(
        f"{ARCHS4_BASE}/{endpoint}",
        params={"species": species},
        timeout=30
    )
    r.raise_for_status()
    data = r.json()
    records = data.get("values", [])
    df = pd.DataFrame(records)
    return df.sort_values("zscore", ascending=False).reset_index(drop=True)

df = get_gene_tissue_zscore("MYC")
print(f"MYC tissue z-scores: {len(df)} tissue types")
print(df[["tissue", "zscore"]].head(10).to_string(index=False))
# MYC tissue z-scores: 200
#                     tissue  zscore
#                      colon    3.12
#             small intestine    2.98
#                    placenta    2.74

# Query mouse tissues for a gene
df_mouse = get_gene_tissue_zscore("Myc", species="mouse")
print(f"Mouse Myc: top 5 tissues")
print(df_mouse[["tissue", "zscore"]].head(5).to_string(index=False))

クエリ 2：共発現遺伝子

すべての ARCHS4 サンプルを対象に、クエリ遺伝子と発現が最も強く相関する遺伝子を特定します。経路の関連遺伝子、調節因子、候補標的の特定に役立ちます。

import requests
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def get_coexpressed_genes(gene_symbol: str, top_n: int = 50,
                           species: str = "human") -> pd.DataFrame:
    """Return genes co-expressed with the query gene.

    Parameters
    ----------
    gene_symbol : str
        HGNC gene symbol.
    top_n : int
        Number of correlated genes to return (default: 50).
    species : str
        'human' or 'mouse' (default: 'human').
    """
    r = requests.get(
        f"{ARCHS4_BASE}/meta/genes/{gene_symbol}/correlations",
        params={"species": species, "limit": top_n},
        timeout=30
    )
    r.raise_for_status()
    data = r.json()
    records = data.get("values", [])
    df = pd.DataFrame(records)
    return df.sort_values("correlation", ascending=False).reset_index(drop=True)

coexp = get_coexpressed_genes("PCNA", top_n=20)
print(f"Top co-expressed genes with PCNA (n={len(coexp)}):")
print(coexp[["gene", "correlation"]].head(10).to_string(index=False))
# Top co-expressed genes with PCNA (n=20):
#   gene  correlation
#   RFC4         0.91
#   RFC2         0.89
#   MCM6         0.87

# Extract gene list for downstream enrichment
gene_list = coexp["gene"].tolist()
print(f"Co-expression gene list: {gene_list[:10]}")
# Pass gene_list to Enrichr or pathway analysis tools

クエリ 3：サンプル検索

メタデータのキーワード（組織、疾患の状態、細胞タイプ、処置）で RNA-seq サンプルを検索します。メタデータ項目とともに GEO/SRA サンプル識別子を返します。

import requests
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def search_samples(keyword: str, species: str = "human",
                   limit: int = 100) -> pd.DataFrame:
    """Search ARCHS4 samples by metadata keyword.

    Parameters
    ----------
    keyword : str
        Search term (e.g., 'breast cancer', 'liver', 'HeLa').
    species : str
        'human' or 'mouse'.
    limit : int
        Maximum number of samples to return.
    """
    r = requests.get(
        f"{ARCHS4_BASE}/samples/search",
        params={"query": keyword, "species": species, "limit": limit},
        timeout=30
    )
    r.raise_for_status()
    data = r.json()
    records = data.get("samples", [])
    return pd.DataFrame(records)

samples = search_samples("pancreatic cancer", limit=50)
print(f"Samples matching 'pancreatic cancer': {len(samples)}")
if len(samples) > 0:
    print(samples[["sample_id", "series_id", "title"]].head(5).to_string(index=False))
# Samples matching 'pancreatic cancer': 50
#   sample_id  series_id  title
#   GSM2345678  GSE123456  Pancreatic ductal adenocarcinoma - sample 1

クエリ 4：遺伝子レベルのメタデータ概要

発現サンプル数、発現パーセンタイル、利用可能な注釈など、遺伝子の要約統計とメタデータを取得します。

import requests

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def get_gene_metadata(gene_symbol: str, species: str = "human") -> dict:
    """Return metadata and expression summary for a gene."""
    r = requests.get(
        f"{ARCHS4_BASE}/meta/genes/{gene_symbol}",
        params={"species": species},
        timeout=30
    )
    r.raise_for_status()
    return r.json()

meta = get_gene_metadata("GAPDH")
print(f"Gene: {meta.get('gene_symbol', 'N/A')}")
print(f"Species: {meta.get('species', 'N/A')}")
print(f"Ensembl ID: {meta.get('ensembl_gene_id', 'N/A')}")
print(f"Description: {meta.get('description', 'N/A')[:80]}")

# Compare metadata for a panel of housekeeping genes
import time

housekeeping = ["GAPDH", "ACTB", "B2M", "HPRT1", "RPLP0"]
for gene in housekeeping:
    meta = get_gene_metadata(gene)
    print(f"  {gene:<8}  {meta.get('ensembl_gene_id', 'N/A')}")
    time.sleep(0.1)

クエリ 5：可視化 — 組織発現の棒グラフ

上位組織の z スコアを取得し、エクスポートした CSV に対して**skills/data-visualization/omics-plotting/SKILL.md を読み、「Box / Violin / Bar」のレシピに従います**（→ figures/BRCA1_tissue_expression.png）。

import requests
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def tissue_zscores(gene_symbol: str, top_n: int = 20, species: str = "human") -> pd.DataFrame:
    """Fetch top tissue z-scores for a gene and save for plotting."""
    r = requests.get(
        f"{ARCHS4_BASE}/meta/genes/{gene_symbol}/zscore",
        params={"species": species},
        timeout=30,
    )
    r.raise_for_status()
    df = pd.DataFrame(r.json().get("values", [])).sort_values("zscore", ascending=False).head(top_n)
    df.to_csv(f"{gene_symbol}_tissue_zscores.csv", index=False)
    return df

df = tissue_zscores("BRCA1", top_n=15)
print(f"Top tissues for BRCA1: {len(df)} -> BRCA1_tissue_zscores.csv")
# Render with the omics-plotting SKILL (`skills/data-visualization/omics-plotting/SKILL.md`) "Box / Violin / Bar" recipe (horizontal bar of zscore by tissue).

クエリ 6：HDF5 一括データアクセス

大規模なサンプル間横断分析のため、ARCHS4 の事前計算済み HDF5 発現行列をダウンロードまたはストリーミングします。HDF5 ファイルには、ヒトおよびマウスの遺伝子 × サンプルのカウント行列が含まれています。

import requests

# HDF5 files are available for bulk download from the ARCHS4 data portal
# URL pattern: https://maayanlab.cloud/archs4/download#expression
# Human gene-level: human_gene_v2.6.h5
# Mouse gene-level: mouse_gene_v2.6.h5

def get_h5_download_urls() -> dict:
    """Return download URLs for ARCHS4 HDF5 expression matrices."""
    base = "https://maayanlab.cloud/archs4"
    return {
        "human_gene": f"{base}/files/human_gene_v2.6.h5",
        "mouse_gene": f"{base}/files/mouse_gene_v2.6.h5",
        "human_transcript": f"{base}/files/human_transcript_v2.6.h5",
        "mouse_transcript": f"{base}/files/mouse_transcript_v2.6.h5",
    }

urls = get_h5_download_urls()
for key, url in urls.items():
    print(f"  {key:<22}  {url}")

# To work with a downloaded HDF5 file:
try:
    import h5py
    import numpy as np

    h5_path = "human_gene_v2.6.h5"   # after download

    def extract_gene_from_h5(h5_path: str, gene_symbol: str,
                              n_samples: int = 1000) -> dict:
        """Extract expression values for a gene from the HDF5 matrix."""
        with h5py.File(h5_path, "r") as f:
            genes = [g.decode() for g in f["meta"]["genes"]["gene_symbol"][:]]
            if gene_symbol not in genes:
                raise ValueError(f"{gene_symbol} not found in HDF5")
            idx = genes.index(gene_symbol)
            expr = f["data"]["expression"][idx, :n_samples]
            sample_ids = [s.decode() for s in f["meta"]["samples"]["geo_accession"][:n_samples]]
        return {"gene": gene_symbol, "expression": expr, "sample_ids": sample_ids}

    result = extract_gene_from_h5(h5_path, "TP53", n_samples=500)
    print(f"TP53 expression: mean={result['expression'].mean():.2f},"
          f" max={result['expression'].max():.2f} (n={len(result['expression'])} samples)")
except ImportError:
    print("h5py not installed. Install with: pip install h5py")
except FileNotFoundError:
    print("HDF5 file not downloaded yet. Use the URLs above to download first.")

主要な概念

z スコア正規化

ARCHS4 は、すべてのサンプルにおける対象遺伝子の発現を基準に算出した z スコアとして、遺伝子発現を報告します。z スコアが 0 の場合は集団平均での発現、2.0 の場合は平均より 2 標準偏差高い発現を意味します。研究間で一貫したアラインメントを行う際に生じるライブラリサイズの違いやバッチ効果が考慮されるため、z スコアは生カウントよりもデータセット間で解釈しやすくなります。

# Example: Positive z-score = above-average expression for that gene
# z > 2.0 → top ~2.5% of samples for that gene
# z < -2.0 → bottom ~2.5% of samples for that gene
# Use absolute z-score thresholds consistently when comparing across genes

HDF5 と REST API の比較

アクセス方法	最適な用途	制限事項
REST API（/zscore、/correlations）	単一遺伝子のクエリ、探索をすばやく行う	集約プロファイルのみ。サンプル単位ではアクセスできません
REST API（/samples/search）	関連するデータセットの検索	メタデータを返します。発現値は返しません
HDF5 のダウンロード	一括解析、カスタム共発現解析、ML	30～60 GB のディスク容量が必要です。ダウンロードは一度だけです

種と遺伝子記号の規則

ARCHS4 では、ヒトサンプルに HGNC 遺伝子記号（大文字、例：TP53）、マウスサンプルに MGI 記号（先頭のみ大文字、例：Trp53）を使用してインデックスを作成します。species パラメーターには "human" または "mouse" を指定できます。大文字と小文字が混在した ID やアンサンブル ID を指定すると、結果は空になります。

一般的なワークフロー

ワークフロー 1：複数遺伝子の組織発現ヒートマップ

目的：遺伝子パネルの組織発現プロファイルを比較し、ヒートマップとして可視化することで、組織特異的な発現パターンと遍在的な発現パターンを特定します。

import requests, time
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

gene_panel = ["MYC", "TP53", "BRCA1", "EGFR", "KRAS", "CDK4"]
top_n_tissues = 25

def get_tissue_zscores(gene: str) -> pd.Series:
    r = requests.get(
        f"{ARCHS4_BASE}/meta/genes/{gene}/zscore",
        params={"species": "human"},
        timeout=30
    )
    r.raise_for_status()
    records = r.json().get("values", [])
    df = pd.DataFrame(records).set_index("tissue")["zscore"]
    return df

# Build expression matrix (genes × tissues)
all_data = {}
for gene in gene_panel:
    try:
        all_data[gene] = get_tissue_zscores(gene)
        print(f"  Fetched {gene}")
    except Exception as e:
        print(f"  Warning: {gene} failed — {e}")
    time.sleep(0.1)

matrix = pd.DataFrame(all_data).T   # genes × tissues
# Select top tissues by max absolute z-score
tissue_importance = matrix.abs().max(axis=0).sort_values(ascending=False)
top_tissues = tissue_importance.head(top_n_tissues).index
matrix_subset = matrix[top_tissues]

# Save the gene × tissue matrix; render with the omics-plotting SKILL (`skills/data-visualization/omics-plotting/SKILL.md`) "Expression heatmap"
# recipe (RdBu_r, center=0) -> figures/archs4_panel_heatmap.png
matrix_subset.to_csv("archs4_panel_matrix.csv")
print(f"Panel matrix ready: {matrix_subset.shape} -> archs4_panel_matrix.csv")

ワークフロー 2：共発現ネットワークのシード拡張

目的：シード遺伝子から開始し、共発現パートナーを取得した後、それらの共発現遺伝子を順にクエリして、2段階の共発現近傍を構築します。

import requests, time
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def get_coexp(gene: str, top_n: int = 20, species: str = "human") -> list:
    r = requests.get(
        f"{ARCHS4_BASE}/meta/genes/{gene}/correlations",
        params={"species": species, "limit": top_n},
        timeout=30
    )
    r.raise_for_status()
    return [rec["gene"] for rec in r.json().get("values", [])]

seed_gene = "PCNA"
min_correlation = 0.80

# Hop 1: direct co-expressed partners
hop1_genes = get_coexp(seed_gene, top_n=30)
print(f"Hop 1 partners of {seed_gene}: {len(hop1_genes)}")
time.sleep(0.1)

# Hop 2: co-expressed genes of each partner
edges = set()
for gene in hop1_genes[:10]:   # limit for demonstration
    partners = get_coexp(gene, top_n=20)
    for partner in partners:
        if partner != seed_gene:
            edges.add((gene, partner))
    time.sleep(0.1)

# Summarize the network
network_df = pd.DataFrame(list(edges), columns=["source", "target"])
hub_counts = network_df["source"].value_counts()
print(f"\nTwo-hop network: {len(edges)} edges")
print(f"Top hub genes:")
print(hub_counts.head(5))

network_df.to_csv(f"{seed_gene}_coexp_network.csv", index=False)
print(f"\nSaved {seed_gene}_coexp_network.csv")

ワークフロー 3：サンプルの検索とデータセットの概要

目的：疾患キーワードでサンプルを検索し、利用可能な GEO シリーズの数を集計し、下流の再解析対象を選定するためにサンプルメタデータをエクスポートします。

import requests, time
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def search_and_summarize(keyword: str, species: str = "human",
                          limit: int = 200) -> pd.DataFrame:
    """Search samples and return a tidy metadata DataFrame."""
    r = requests.get(
        f"{ARCHS4_BASE}/samples/search",
        params={"query": keyword, "species": species, "limit": limit},
        timeout=30
    )
    r.raise_for_status()
    records = r.json().get("samples", [])
    return pd.DataFrame(records)

keyword = "colorectal cancer"
df = search_and_summarize(keyword, limit=150)
print(f"Samples matching '{keyword}': {len(df)}")

if len(df) > 0:
    # Summarize by GEO series
    series_counts = df["series_id"].value_counts()
    print(f"\nTop GEO series (by sample count):")
    print(series_counts.head(8).to_string())

    # Export sample list
    df.to_csv(f"{keyword.replace(' ', '_')}_samples.csv", index=False)
    print(f"\nSaved {keyword.replace(' ', '_')}_samples.csv ({len(df)} samples)")
    print(f"Unique GEO series: {df['series_id'].nunique()}")

主なパラメーター

パラメーター	エンドポイント	デフォルト	範囲／オプション	効果
species	すべての遺伝子エンドポイント	"human"	"human"、"mouse"	種ごとのサンプルインデックスを選択します
limit	/correlations、/samples/search	100	1～500	返される結果の数
gene_symbol（パス）	/meta/genes/{gene}/zscore、/correlations	—	HGNC 記号（ヒト）または MGI 記号（マウス）	クエリ対象の遺伝子。大文字と小文字を区別します
query	/samples/search	—	自由記述の文字列	タイトル、組織、ソースのフィールドを対象にしたメタデータのキーワード検索
offset	/samples/search	0	整数	大量の結果をページネーションする際のオフセット
correlation（応答フィールド）	/correlations	—	-1.0～1.0	ピアソン相関係数。共発現が強いものには > 0.7 を指定して絞り込みます
zscore（応答フィールド）	/zscore	—	連続浮動小数点数	発現の z スコア。> 2.0 は高発現を示します
page_size（HDF5）	HDF5 スライス	すべて	任意の整数	HDF5 から読み取る際に抽出するサンプル数

ベストプラクティス

1. z スコアのしきい値を一貫して使用する：z スコアは遺伝子ごとに異なるため、遍在的に発現する遺伝子（GAPDH）と組織限定的に発現する遺伝子（TTR、肝臓）の z スコア 2.0 は、解釈上の意味が異なります。比較する遺伝子と組織の背景を必ず明記してください。

2. バッチクエリの間にスリープを入れる：ARCHS4 では、約 10 リクエスト／秒のソフトレート制限が適用されます。連続して遺伝子をクエリする場合は、429 Too Many Requests エラーを避けるために、クエリの間に time.sleep(0.1) を追加してください。

3. 大規模解析には HDF5 をダウンロードする：50 個以上の遺伝子を対象とするクエリや、サンプル単位の発現値が必要な場合、REST API は実用的ではありません。HDF5 ファイルを一度ダウンロードし、h5py のスライスを使って行列にすばやくアクセスしてください。これによりレート制限を回避でき、一括抽出の速度が 100 倍になります。

4. 種に応じた遺伝子記号の規則を守る：ヒトのクエリには HGNC の大文字記号（例：TP53）、マウスのクエリには MGI 形式の記号（例：Trp53）が必要です。大文字と小文字を誤ると、エラーなしで結果が空になります。

5. 複数のデータセットで共発現の結果を検証する：ARCHS4 の共発現は、すべての組織タイプを対象に集約されています。高い相関は、単一の組織や研究によって生じている可能性があります。組織特異的なクエリで照合するか、寄与度の高い上位の GEO シリーズを手動で確認してください。

よく使うレシピ

レシピ：組織特異性をすばやく確認する

使用する場面：実験を設計する前に、遺伝子が幅広く発現する（ハウスキーピング遺伝子）か、特定の組織に限定して発現するかをすばやく判断します。

import requests

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def tissue_specificity_summary(gene_symbol: str) -> None:
    """Print a summary of high and low expression tissues for a gene."""
    r = requests.get(
        f"{ARCHS4_BASE}/meta/genes/{gene_symbol}/zscore",
        params={"species": "human"},
        timeout=30
    )
    r.raise_for_status()
    records = r.json().get("values", [])
    zscores = [rec["zscore"] for rec in records if rec.get("zscore") is not None]
    top_high = sorted(records, key=lambda x: x.get("zscore", 0), reverse=True)[:5]
    top_low = sorted(records, key=lambda x: x.get("zscore", float("inf")))[:3]
    print(f"\n{gene_symbol} — {len(zscores)} tissues")
    print(f"  Range: [{min(zscores):.2f}, {max(zscores):.2f}]  "
          f"Mean: {sum(zscores)/len(zscores):.2f}")
    print("  High expression:")
    for t in top_high:
        print(f"    {t['tissue']:<35}  z={t['zscore']:.2f}")
    print("  Low expression:")
    for t in top_low:
        print(f"    {t['tissue']:<35}  z={t['zscore']:.2f}")

tissue_specificity_summary("TTR")   # Transthyretin — liver-specific

レシピ：遺伝子共発現の一括テーブル

使用する場面：差次的発現遺伝子のリストから、遺伝子パネルのペアごとの相関テーブルを作成します。

import requests, time
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

def batch_coexpr_table(gene_list: list, top_n: int = 10) -> pd.DataFrame:
    """For each gene in gene_list, return its top co-expressed genes."""
    rows = []
    for gene in gene_list:
        try:
            r = requests.get(
                f"{ARCHS4_BASE}/meta/genes/{gene}/correlations",
                params={"species": "human", "limit": top_n},
                timeout=30
            )
            r.raise_for_status()
            for rec in r.json().get("values", []):
                rows.append({
                    "query_gene": gene,
                    "coexp_gene": rec.get("gene"),
                    "correlation": rec.get("correlation"),
                })
            time.sleep(0.1)
        except Exception as e:
            print(f"Warning: {gene} skipped — {e}")
    return pd.DataFrame(rows)

deg_list = ["MYC", "CCND1", "CDK4", "RB1", "E2F1"]
coexp_table = batch_coexpr_table(deg_list, top_n=10)
print(f"Co-expression entries: {len(coexp_table)}")
print(coexp_table.groupby("query_gene")["coexp_gene"].count())
coexp_table.to_csv("deg_coexpression_table.csv", index=False)
print("Saved deg_coexpression_table.csv")

レシピ：GEO ダウンロード用サンプル ID のエクスポート

使用する場面：メタ解析用に生のカウント行列をダウンロードするため、関連する GEO アクセッション番号を特定します。

import requests
import pandas as pd

ARCHS4_BASE = "https://maayanlab.cloud/archs4/api/v1"

keyword = "glioblastoma"
r = requests.get(
    f"{ARCHS4_BASE}/samples/search",
    params={"query": keyword, "species": "human", "limit": 200},
    timeout=30
)
r.raise_for_status()
samples = pd.DataFrame(r.json().get("samples", []))
if len(samples) > 0:
    # Get unique GEO series accessions
    series = samples["series_id"].dropna().unique()
    print(f"Unique GEO series for '{keyword}': {len(series)}")
    for s in series[:10]:
        n = (samples["series_id"] == s).sum()
        print(f"  {s}  ({n} samples)")
    # Export series list for GEO download script
    pd.Series(series, name="geo_series").to_csv(
        f"{keyword}_geo_series.txt", index=False
    )
    print(f"\nSaved {keyword}_geo_series.txt")

トラブルシューティング

問題	原因	解決策
遺伝子クエリで HTTP 404 が発生する	ARCHS4 インデックスに遺伝子シンボルが見つからない	HGNC シンボルのスペルを確認します。species パラメーターが遺伝子の表記規則と一致しているか確認します（ヒト：すべて大文字、マウス：先頭文字のみ大文字）
HTTP 429 Too Many Requests が発生する	約 10 req/s のレート制限を超過した	リクエストの間に time.sleep(0.1) を追加します。一括クエリでは 0.5 秒の遅延を設定します
Z スコアの応答で values リストが空	インデックス化された組織で遺伝子が発現していない、または種が間違っている	種を切り替えます。遺伝子がタンパク質をコードしており、GEO にデータがあることを確認します
検索結果の samples リストが空	メタデータフィールドにキーワードが一致しない	より広義のキーワードや別のキーワードを試します（例："hepatic" の代わりに "liver"）
HDF5 で遺伝子が見つからない	HDF5 のバージョンとクエリでシンボルが一致しない	f["meta"]["genes"]["gene_symbol"][:] で利用可能な遺伝子を確認します。Ensembl ID または別名を試します
requests.exceptions.Timeout が発生する	高負荷時に API の応答が遅い	timeout=60 に増やします。指数バックオフを使用して再試行します
Z スコアがすべてほぼゼロ	組織全体で遺伝子の発現が非常に低い、または発現していない	生カウントで遺伝子の発現を確認します。遺伝子が非コード遺伝子であるか、発現量が非常に低い可能性があります

関連スキル

• gnomad-database — 集団におけるバリアント頻度。ARCHS4 の後に使用して、発現量の高い遺伝子のバリアントを特定します
• gget-genomic-databases — ARCHS4 の共発現遺伝子リストに対する Enrichr 経路エンリッチメント（gget enrichr）
• pydeseq2-differential-expression — バルク RNA-seq の差次的発現解析。ARCHS4 HDF5 行列を参照コホートとして利用できます

参考資料

• ARCHS4 ウェブポータル — 対話型の発現ブラウザーとデータセットのダウンロード
• ARCHS4 REST API ドキュメント — エンドポイントのリファレンスとパラメーター
• Lachmann et al., Nature Communications 2018 — 均一なアラインメントパイプラインについて説明した ARCHS4 の原著論文
• ARCHS4 GitHub — ソースコードと HDF5 スキーマのドキュメント