alterlab-monarch

Monarch Initiative 数据库

概述

Monarch Initiative（https://monarchinitiative.org/）是一个跨多个物种的集成知识库，关联人类和模式生物中的基因、疾病和表型。它整合了来自 40 多个数据源的数据，包括 OMIM、ORPHANET、HPO（人类表型本体）、ClinVar、MGI（小鼠基因组信息学）、ZFIN（斑马鱼）、RGD（大鼠）、FlyBase 和 WormBase。

Monarch 支持：

• 跨物种映射表型，以识别候选疾病基因
• 查找与某种疾病或表型相关的所有基因
• 发现人类疾病的模式生物
• 浏览 HPO 层级，以查询表型本体

关键资源：

• Monarch 门户：https://monarchinitiative.org/
• API v3 基础 URL：https://api-v3.monarchinitiative.org/v3/api（所有端点均位于 /v3/api/... 下）
• 交互式 API 文档（Swagger UI）：https://api-v3.monarchinitiative.org/v3/docs
• HPO 浏览器：https://hpo.jax.org/

脚本

scripts/query_monarch.py — 查询 Monarch Initiative API v3（仅使用标准库，将 JSON 输出到标准输出）：

python scripts/query_monarch.py entity HP:0001250        # look up an entity (gene/disease/HPO)
python scripts/query_monarch.py search epilepsy          # text search the knowledge graph
python scripts/query_monarch.py associations HGNC:1100   # associations for an entity

何时使用此技能

以下情况请使用 Monarch：

• 罕见病基因发现：患者的表型（HPO 术语）与哪些基因相关？
• 表型相似性：根据表型特征谱，两种疾病是否相似？
• 跨物种建模：是否有针对我关注的疾病的小鼠或斑马鱼模型？
• HPO 术语查询：获取 HPO 术语名称、定义和本体层级
• 疾病-表型映射：列出与特定疾病相关的所有 HPO 术语
• 基因-表型关联：基因变异会导致哪些表型？
• 直系同源基因-表型映射：利用动物模型的表型推断人类基因功能

不适用的情况

场景	改用
特定变异的临床意义（ACMG、审查星级）	alterlab-clinvar
群体等位基因频率和基因约束（pLI/LOEUF）	alterlab-gnomad
药物发现的靶点-疾病证据评分和可成药性	alterlab-opentargets
常见变异的 GWAS 性状关联	alterlab-gwas
药物基因组学中的基因-药物指导	alterlab-clinpgx

核心功能

1. Monarch API v3

实际端点位于 /v3/api 下（/v3/docs URL 仅用于 Swagger UI，并非请求基础 URL）。关联项以扁平结构返回——读取 item["subject"]、item["subject_label"]、item["predicate"]、item["object"]、item["object_label"]、item["object_category"] 等。不存在嵌套的 item["object"]["id"]。

import requests

BASE_URL = "https://api-v3.monarchinitiative.org/v3/api"

def monarch_get(endpoint, params=None):
    """GET a Monarch API v3 endpoint and return parsed JSON."""
    url = f"{BASE_URL}/{endpoint}"
    response = requests.get(url, params=params, headers={"Accept": "application/json"})
    response.raise_for_status()
    return response.json()

2. 表型到基因的关联（Pheno2Gene）

对于 GeneToPhenotypicFeatureAssociation，基因是主体，表型是客体。要从表型查找其相关基因，请按 object=<HPO> 和 subject_category=biolink:Gene 进行筛选。

def phenotype_to_gene(hpo_ids, limit=100):
    """
    Return genes whose phenotypes match the given HPO terms (flat per-term links).
    Core use case: rare disease differential diagnosis.

    Args:
        hpo_ids: List of HPO term IDs (e.g., ["HP:0001250", "HP:0004322"])
    """
    all_genes = []
    for hpo_id in hpo_ids:
        data = monarch_get("association", {
            "object": hpo_id,
            "subject_category": "biolink:Gene",
            "category": "biolink:GeneToPhenotypicFeatureAssociation",
            "limit": limit,
        })
        for assoc in data.get("items", []):
            all_genes.append({
                "phenotype_id": hpo_id,
                "gene_id": assoc.get("subject"),
                "gene_name": assoc.get("subject_label"),
                "predicate": assoc.get("predicate"),
            })
    return all_genes

# Example: Find genes associated with seizures and short stature
hpo_terms = ["HP:0001250", "HP:0004322"]  # Seizure, Short stature
genes = phenotype_to_gene(hpo_terms)

3. 疾病到基因的关联

因果基因-疾病关联是 CausalGeneToDiseaseAssociation（基因 = 主体， 疾病 = 客体，谓词为 biolink:causes）。要列出某种疾病的基因， 请按 object=<disease> 和该类别进行筛选。

def get_disease_genes(disease_id, limit=100):
    """
    Get genes causally linked to a disease.
    Disease IDs: MONDO:0007739, OMIM:146300, ORPHANET:558, etc.
    """
    data = monarch_get("association", {
        "object": disease_id,
        "category": "biolink:CausalGeneToDiseaseAssociation",
        "limit": limit,
    })
    return data.get("items", [])

# Example: genes causally linked to Huntington disease
for assoc in get_disease_genes("MONDO:0007739"):
    print(f"  {assoc.get('subject_label')} ({assoc.get('subject')})")

# MONDO disease IDs (preferred over OMIM for cross-ontology queries)
# MONDO:0007739 - Huntington disease
# MONDO:0009061 - Cystic fibrosis
# OMIM:104300 - Alzheimer disease, susceptibility to, type 1

4. 基因到表型和疾病

def get_phenotypes_for_gene(gene_id, limit=100):
    """
    Get all phenotypes associated with a gene.
    Gene IDs: HGNC:7884, NCBIGene:4137, etc.
    """
    data = monarch_get("association", {
        "subject": gene_id,
        "category": "biolink:GeneToPhenotypicFeatureAssociation",
        "limit": limit,
    })
    return data.get("items", [])

def get_diseases_for_gene(gene_id, limit=100):
    """Get diseases caused by variants in a gene."""
    data = monarch_get("association", {
        "subject": gene_id,
        "category": "biolink:CausalGeneToDiseaseAssociation",
        "limit": limit,
    })
    return data.get("items", [])

# Example: What diseases does BRCA1 cause? (flat fields: object / object_label)
brca1_diseases = get_diseases_for_gene("HGNC:1100")
for assoc in brca1_diseases:
    print(f"  {assoc.get('object_label')} ({assoc.get('object')})")

5. HPO 术语查询

def get_hpo_term(hpo_id):
    """Fetch information about an HPO term."""
    return monarch_get(f"entity/{hpo_id}")

def search_hpo_terms(query, limit=20):
    """Search for HPO terms by name."""
    params = {
        "q": query,
        "category": "biolink:PhenotypicFeature",
        "limit": limit
    }
    return monarch_get("search", params)

# Example: look up the HPO term for seizures
seizure_term = get_hpo_term("HP:0001250")
print(f"Name: {seizure_term.get('name')}")
print(f"Definition: {seizure_term.get('description')}")

# Search for related terms
epilepsy_terms = search_hpo_terms("epilepsy")
for term in epilepsy_terms.get("items", [])[:5]:
    print(f"  {term['id']}: {term['name']}")

6. 语义相似度（疾病比较）

semsim/compare 是一个 POST 端点，接收包含两组 HPO 术语 （subjects、objects）和可选 metric 的 JSON 请求体。有效指标： ancestor_information_content（默认）、jaccard_similarity、phenodigm_score。 响应包含 average_score 和 best_score。

def compare_phenotype_sets(subject_hpo_ids, object_hpo_ids,
                           metric="ancestor_information_content"):
    """
    Compare two sets of HPO terms by semantic similarity over the HPO hierarchy.
    Pass each disease's HPO profile as a term set (not the disease CURIE itself).
    """
    body = {
        "subjects": subject_hpo_ids,
        "objects": object_hpo_ids,
        "metric": metric,
    }
    resp = requests.post(f"{BASE_URL}/semsim/compare", json=body)
    resp.raise_for_status()
    return resp.json()

# Example: compare two phenotype profiles
similarity = compare_phenotype_sets(
    ["HP:0001250", "HP:0001263"],  # Seizure, Global developmental delay
    ["HP:0001250", "HP:0004322"],  # Seizure, Short stature
)
print(similarity["average_score"], similarity["best_score"])

表型特征集搜索会在一次调用中，将组内的每个基因或疾病与整组 HPO 术语进行比较并排序——这是基于相似度的替代方案，与 §8 中按术语逐项计数不同。GET /semsim/search/{termset}/{group} 接收以逗号分隔的术语集和一个组（Human Genes、Human Diseases、 Mouse Genes、Rat Genes、Zebrafish Genes、C. Elegans Genes）；limit ≤ 50。 返回 {subject: {id, name, ...}, score, similarity} 列表。

from urllib.parse import quote

def semsim_search(hpo_ids, group="Human Diseases", metric="ancestor_information_content", limit=20):
    termset = ",".join(hpo_ids)
    url = f"{BASE_URL}/semsim/search/{termset}/{quote(group)}"
    resp = requests.get(url, params={"metric": metric, "limit": limit}, timeout=60)
    resp.raise_for_status()
    return [(r["subject"]["id"], r["subject"].get("name"), r["score"]) for r in resp.json()]

semsim_search(["HP:0001250", "HP:0004322", "HP:0001252", "HP:0000252", "HP:0001263"], "Human Genes")

7. 跨物种直系同源基因

def get_orthologs(gene_id, taxon=None, limit=50):
    """
    Get orthologs of a human gene in model organisms.
    Useful for finding animal models of human diseases.
    Each item exposes object / object_label / object_taxon_label (e.g. Mus musculus).
    """
    params = {
        "subject": gene_id,
        "predicate": "biolink:orthologous_to",
        "limit": limit,
    }
    if taxon:
        params["object_taxon"] = taxon  # e.g. "NCBITaxon:10090" for mouse
    return monarch_get("association", params).get("items", [])

# NCBI Taxonomy IDs for common model organisms:
# Mouse: 10090 (Mus musculus)
# Zebrafish: 7955 (Danio rerio)
# Fruit fly: 7227 (Drosophila melanogaster)
# C. elegans: 6239
# Rat: 10116 (Rattus norvegicus)

8. 完整工作流：罕见病基因优先级排序

import requests
import pandas as pd

def rare_disease_gene_finder(patient_hpo_terms, candidate_gene_ids=None, top_n=20):
    """
    Find genes that match a patient's HPO phenotype profile.

    Args:
        patient_hpo_terms: List of HPO IDs from clinical assessment
        candidate_gene_ids: Optional list to restrict search
        top_n: Number of top candidates to return
    """
    BASE_URL = "https://api-v3.monarchinitiative.org/v3/api"

    # 1. Find genes associated with each phenotype
    gene_phenotype_counts = {}

    for hpo_id in patient_hpo_terms:
        data = requests.get(
            f"{BASE_URL}/association",
            params={
                "object": hpo_id,
                "subject_category": "biolink:Gene",
                "category": "biolink:GeneToPhenotypicFeatureAssociation",
                "limit": 100,
            }
        ).json()

        for item in data.get("items", []):
            gene_id = item.get("subject")        # flat field, not item["subject"]["id"]
            gene_name = item.get("subject_label")
            if gene_id:
                if gene_id not in gene_phenotype_counts:
                    gene_phenotype_counts[gene_id] = {"name": gene_name, "count": 0, "phenotypes": []}
                gene_phenotype_counts[gene_id]["count"] += 1
                gene_phenotype_counts[gene_id]["phenotypes"].append(hpo_id)

    # 2. Rank by number of matching phenotypes
    ranked = sorted(gene_phenotype_counts.items(),
                    key=lambda x: -x[1]["count"])[:top_n]

    results = []
    for gene_id, info in ranked:
        results.append({
            "gene_id": gene_id,
            "gene_name": info["name"],
            "matching_phenotypes": info["count"],
            "total_patient_phenotypes": len(patient_hpo_terms),
            "phenotype_overlap": info["count"] / len(patient_hpo_terms),
            "matching_hpo_terms": info["phenotypes"]
        })

    return pd.DataFrame(results)

# Example usage
patient_phenotypes = [
    "HP:0001250",  # Seizures
    "HP:0004322",  # Short stature
    "HP:0001252",  # Hypotonia
    "HP:0000252",  # Microcephaly
    "HP:0001263",  # Global developmental delay
]
candidates = rare_disease_gene_finder(patient_phenotypes)
print(candidates[["gene_name", "matching_phenotypes", "phenotype_overlap"]].to_string())

查询工作流

工作流 1：基于 HPO 的鉴别诊断

1. 从临床记录或遗传咨询中提取 HPO 术语
2. 在 Monarch 中运行表型到基因查询
3. 按匹配表型的数量对候选基因排序
4. 与 gnomAD（约束评分）和 ClinVar（变异证据）进行交叉比对
5. 优先考虑 pLI 较高且存在已知致病变异的基因

工作流 2：疾病模型发现

1. 确定感兴趣的基因或疾病
2. 查询 Monarch，查找跨物种直系同源基因
3. 在模式生物数据库中查找表型关联
4. 找出能够重现人类疾病特征的实验模型

工作流 3：新基因的表型注释

1. 对功能未知的基因，查询所有已知表型关联
2. 映射到 HPO 层级结构，了解受影响的身体系统
3. 与 OMIM 和 ORPHANET 交叉比对，查找疾病关联

常见标识符前缀

前缀	命名空间	示例
HP:	人类表型本体	HP:0001250（癫痫发作）
MONDO:	Monarch 疾病本体	MONDO:0007739
OMIM:	OMIM 疾病	OMIM:104300
ORPHANET:	Orphanet 罕见病	ORPHANET:558
HGNC:	HGNC 基因符号	HGNC:7884
NCBIGene:	NCBI 基因 ID	NCBIGene:4137
ENSEMBL:	Ensembl 基因	ENSEMBL:ENSG...
MGI:	小鼠基因	MGI:1338833
ZFIN:	斑马鱼基因	ZFIN:ZDB-GENE...

最佳实践

• 疾病使用 MONDO ID——它们统一了 OMIM/ORPHANET/MESH 标识符
• 表型使用 HPO ID——这是临床表型描述的标准
• 处理分页：大型查询可能需要通过 offset 参数迭代获取结果
• 语义相似度优于精确匹配：祖先 HPO 术语可以捕捉相关表型
• 与 ClinVar 和 OMIM 交叉验证：Monarch 汇总了许多来源；数据质量各不相同
• 基因使用 HGNC ID：与基因符号相比，它在不同数据库版本间更稳定

其他资源

• Monarch 门户：https://monarchinitiative.org/
• API v3 基础地址：https://api-v3.monarchinitiative.org/v3/api — Swagger UI：https://api-v3.monarchinitiative.org/v3/docs
• HPO 浏览器：https://hpo.jax.org/
• MONDO 本体：https://mondo.monarchinitiative.org/
• 引用文献：Putman TE et al. (2024) The Monarch Initiative in 2024: an analytic platform integrating phenotypes, genes and diseases across species. Nucleic Acids Research 52(D1):D938–D949. PMID: 38000386. DOI: 10.1093/nar/gkad1082
• 知识图谱发布版本和来源版本：GET /v3/api/version、/v3/api/releases、/v3/api/sources/versions——为确保结果可复现，请记录所查询的知识图谱版本