@nahisaho/satori 0.12.0 → 0.14.0

package/src/.github/skills/scientific-biomedical-pubtator/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: scientific-biomedical-pubtator
+description: |
+  バイオメディカルテキストマイニングスキル。PubTator3 API による
+  遺伝子・疾患・化合物・変異・種のエンティティ認識、関係抽出、
+  バイオメディカル文献アノテーション自動化パイプライン。
+---
+
+# Scientific Biomedical PubTator
+
+PubTator3 API を活用したバイオメディカル文献エンティティ認識・
+関係抽出パイプラインを提供する。
+
+## When to Use
+
+- PubMed 論文から遺伝子・疾患・化合物のエンティティを自動抽出するとき
+- バイオメディカル NER (Named Entity Recognition) を実行するとき
+- 遺伝子-疾患・薬物-標的の関係を文献から抽出するとき
+- 大規模文献コーパスのバイオアノテーションを行うとき
+- テキストマイニング結果を知識グラフに統合するとき
+
+---
+
+## Quick Start
+
+## 1. PubTator3 エンティティアノテーション
+
+```python
+import requests
+import pandas as pd
+import json
+import time
+
+PUBTATOR_API = "https://www.ncbi.nlm.nih.gov/research/pubtator3-api"
+
+
+def annotate_pmids(pmids, concepts=None):
+    """
+    PubTator3 — PMID リストのバイオメディカルエンティティアノテーション。
+
+    Parameters:
+        pmids: list — PMID リスト (e.g., [12345678, 23456789])
+        concepts: list — エンティティタイプ
+            "gene", "disease", "chemical", "mutation", "species", "cellline"
+
+    ToolUniverse:
+        PubTator_annotate(pmids=pmids, concepts=concepts)
+        PubTator_search(query=query)
+    """
+    if concepts is None:
+        concepts = ["gene", "disease", "chemical", "mutation", "species"]
+
+    pmid_str = ",".join(str(p) for p in pmids)
+    params = {
+        "pmids": pmid_str,
+        "concepts": ",".join(concepts),
+        "format": "biocjson",
+    }
+
+    resp = requests.get(f"{PUBTATOR_API}/publications/export/biocjson", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    # Parse annotations
+    all_annotations = []
+    for doc in data.get("PubTator3", []) if isinstance(data, dict) else [data]:
+        pmid = doc.get("pmid", doc.get("id", ""))
+        for passage in doc.get("passages", []):
+            for annotation in passage.get("annotations", []):
+                infons = annotation.get("infons", {})
+                all_annotations.append({
+                    "pmid": pmid,
+                    "text": annotation.get("text", ""),
+                    "type": infons.get("type", ""),
+                    "identifier": infons.get("identifier", ""),
+                    "offset": annotation.get("locations", [{}])[0].get("offset", ""),
+                    "length": annotation.get("locations", [{}])[0].get("length", ""),
+                    "passage_type": passage.get("infons", {}).get("type", ""),
+                })
+
+    df = pd.DataFrame(all_annotations)
+    type_counts = df["type"].value_counts().to_dict() if not df.empty else {}
+    print(f"PubTator annotation: {len(pmids)} PMIDs → "
+          f"{len(df)} entities {type_counts}")
+    return df
+```
+
+## 2. PubTator3 テキスト検索
+
+```python
+def search_pubtator(query, max_results=100):
+    """
+    PubTator3 テキスト検索 — バイオメディカルエンティティ付き論文検索。
+
+    Parameters:
+        query: str — 検索クエリ (遺伝子名、疾患名、化合物名)
+        max_results: int — 最大取得数
+    """
+    params = {
+        "text": query,
+        "sort": "score",
+        "page_size": min(max_results, 100),
+    }
+    resp = requests.get(f"{PUBTATOR_API}/search/", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for hit in data.get("results", []):
+        results.append({
+            "pmid": hit.get("pmid", ""),
+            "title": hit.get("title", ""),
+            "journal": hit.get("journal", ""),
+            "year": hit.get("year", ""),
+            "score": hit.get("score", 0),
+            "genes": hit.get("genes", []),
+            "diseases": hit.get("diseases", []),
+            "chemicals": hit.get("chemicals", []),
+            "mutations": hit.get("mutations", []),
+        })
+
+    df = pd.DataFrame(results)
+    total = data.get("count", 0)
+    print(f"PubTator search '{query}': {total} total, {len(df)} returned")
+    return df
+```
+
+## 3. エンティティ関係抽出
+
+```python
+def extract_entity_relations(pmids, relation_types=None):
+    """
+    PubTator3 — エンティティ間関係 (gene-disease, drug-target 等) 抽出。
+
+    Parameters:
+        pmids: list — PMID リスト
+        relation_types: list — 関係タイプフィルタ
+            "GDA" (gene-disease), "CDA" (chemical-disease),
+            "CGA" (chemical-gene), "PPI" (protein-protein)
+    """
+    # Get annotations with relations
+    df_annotations = annotate_pmids(pmids)
+
+    # Extract co-occurrences within same passage
+    relations = []
+    for pmid in df_annotations["pmid"].unique():
+        pmid_df = df_annotations[df_annotations["pmid"] == pmid]
+
+        # Gene-Disease relations
+        genes = pmid_df[pmid_df["type"] == "Gene"]
+        diseases = pmid_df[pmid_df["type"] == "Disease"]
+        chemicals = pmid_df[pmid_df["type"] == "Chemical"]
+
+        if not relation_types or "GDA" in relation_types:
+            for _, gene in genes.iterrows():
+                for _, disease in diseases.iterrows():
+                    relations.append({
+                        "pmid": pmid,
+                        "relation_type": "GDA",
+                        "entity1_type": "Gene",
+                        "entity1_text": gene["text"],
+                        "entity1_id": gene["identifier"],
+                        "entity2_type": "Disease",
+                        "entity2_text": disease["text"],
+                        "entity2_id": disease["identifier"],
+                    })
+
+        if not relation_types or "CGA" in relation_types:
+            for _, chem in chemicals.iterrows():
+                for _, gene in genes.iterrows():
+                    relations.append({
+                        "pmid": pmid,
+                        "relation_type": "CGA",
+                        "entity1_type": "Chemical",
+                        "entity1_text": chem["text"],
+                        "entity1_id": chem["identifier"],
+                        "entity2_type": "Gene",
+                        "entity2_text": gene["text"],
+                        "entity2_id": gene["identifier"],
+                    })
+
+        if not relation_types or "CDA" in relation_types:
+            for _, chem in chemicals.iterrows():
+                for _, disease in diseases.iterrows():
+                    relations.append({
+                        "pmid": pmid,
+                        "relation_type": "CDA",
+                        "entity1_type": "Chemical",
+                        "entity1_text": chem["text"],
+                        "entity1_id": chem["identifier"],
+                        "entity2_type": "Disease",
+                        "entity2_text": disease["text"],
+                        "entity2_id": disease["identifier"],
+                    })
+
+    rel_df = pd.DataFrame(relations)
+    rel_counts = rel_df["relation_type"].value_counts().to_dict() if not rel_df.empty else {}
+    print(f"Entity relations: {len(rel_df)} total {rel_counts}")
+    return rel_df
+```
+
+## 4. バイオアノテーション集計ダッシュボード
+
+```python
+def annotation_summary_dashboard(pmids, output_prefix="pubtator"):
+    """
+    PubTator アノテーション集計・可視化。
+
+    Parameters:
+        pmids: list — PMID リスト
+        output_prefix: str — 出力ファイルプレフィックス
+    """
+    import matplotlib.pyplot as plt
+
+    # Get annotations
+    df = annotate_pmids(pmids)
+    if df.empty:
+        print("No annotations found")
+        return {}
+
+    # Entity type distribution
+    fig, axes = plt.subplots(1, 3, figsize=(15, 5))
+
+    # 1. Entity type counts
+    type_counts = df["type"].value_counts()
+    type_counts.plot(kind="bar", ax=axes[0], color="#2196F3")
+    axes[0].set_title("Entity Type Distribution")
+    axes[0].set_ylabel("Count")
+
+    # 2. Top entities per type
+    for entity_type in ["Gene", "Disease", "Chemical"]:
+        sub = df[df["type"] == entity_type]
+        top = sub["text"].value_counts().head(10)
+        if not top.empty:
+            print(f"\nTop {entity_type}s: {top.to_dict()}")
+
+    # 3. Articles per entity count
+    per_article = df.groupby("pmid")["type"].count()
+    per_article.hist(ax=axes[1], bins=20, color="#4CAF50")
+    axes[1].set_title("Entities per Article")
+    axes[1].set_xlabel("Number of entities")
+
+    # Entity type per article
+    pivot = df.groupby(["pmid", "type"]).size().unstack(fill_value=0)
+    pivot.plot(kind="box", ax=axes[2])
+    axes[2].set_title("Entity Types per Article")
+
+    plt.tight_layout()
+    fig_path = f"figures/{output_prefix}_dashboard.png"
+    plt.savefig(fig_path, dpi=150, bbox_inches="tight")
+    plt.close()
+
+    # Save results
+    df.to_csv(f"results/{output_prefix}_annotations.csv", index=False)
+
+    summary = {
+        "total_pmids": df["pmid"].nunique(),
+        "total_annotations": len(df),
+        "entity_types": type_counts.to_dict(),
+        "unique_entities": df.groupby("type")["text"].nunique().to_dict(),
+    }
+    print(f"\nSummary: {summary}")
+    return summary
+```
+
+## 5. 知識グラフ構築用エンティティネットワーク
+
+```python
+def build_entity_network(pmids, min_cooccurrence=2):
+    """
+    PubTator エンティティ共起ネットワーク構築。
+
+    Parameters:
+        pmids: list — PMID リスト
+        min_cooccurrence: int — 最小共起回数
+    """
+    import networkx as nx
+    from collections import Counter
+
+    rel_df = extract_entity_relations(pmids)
+    if rel_df.empty:
+        return nx.Graph()
+
+    # Count co-occurrences
+    edge_counter = Counter()
+    for _, row in rel_df.iterrows():
+        key = tuple(sorted([
+            f"{row['entity1_type']}:{row['entity1_text']}",
+            f"{row['entity2_type']}:{row['entity2_text']}",
+        ]))
+        edge_counter[key] += 1
+
+    # Build network
+    G = nx.Graph()
+    for (node1, node2), count in edge_counter.items():
+        if count >= min_cooccurrence:
+            G.add_edge(node1, node2, weight=count)
+
+    print(f"Entity network: {G.number_of_nodes()} nodes, "
+          f"{G.number_of_edges()} edges "
+          f"(min cooccurrence = {min_cooccurrence})")
+    return G
+```
+
+---
+
+## 利用可能ツール
+
+| ToolUniverse カテゴリ | 主なツール |
+|---|---|
+| `pubtator` | `PubTator_annotate`, `PubTator_search` |
+
+## パイプライン出力
+
+| 出力ファイル | 説明 | 連携先スキル |
+|---|---|---|
+| `results/pubtator_annotations.csv` | エンティティアノテーション | → text-mining-nlp, knowledge-graph |
+| `results/entity_relations.csv` | エンティティ間関係 | → network-analysis, disease-research |
+| `results/entity_network.graphml` | エンティティ共起ネットワーク | → graph-neural-networks |
+| `figures/pubtator_dashboard.png` | アノテーション集計 | → publication-figures |
+
+## パイプライン統合
+
+```
+literature-search ──→ biomedical-pubtator ──→ text-mining-nlp
+  (PubMed/OpenAlex)   (PubTator NER)         (KG 構築)
+                            │
+                            ├──→ disease-research (GDA 関係)
+                            ├──→ drug-target-profiling (CGA 関係)
+                            └──→ preprint-archive (プレプリント NER)
+```

package/src/.github/skills/scientific-biothings-idmapping/SKILL.md

@@ -0,0 +1,298 @@
+---
+name: scientific-biothings-idmapping
+description: |
+  BioThings API (MyGene.info, MyVariant.info, MyChem.info) を活用した
+  遺伝子・変異・化合物の横断的 ID マッピングおよびアノテーション統合スキル。
+---
+
+# Scientific BioThings ID Mapping
+
+BioThings API スイート (MyGene, MyVariant, MyChem) を活用した
+多データベース横断の ID 変換・アノテーション取得パイプラインを提供する。
+
+## When to Use
+
+- 遺伝子 ID 間の変換 (Entrez ↔ Ensembl ↔ Symbol ↔ UniProt) を行うとき
+- 変異 ID のアノテーション (ClinVar, dbSNP, CADD 等) を取得するとき
+- 化合物 ID の変換 (DrugBank ↔ ChEMBL ↔ InChIKey ↔ PubChem) を行うとき
+- バッチクエリで多数の ID を一括アノテーションするとき
+- 複数データベースのメタ情報を統合するとき
+
+---
+
+## Quick Start
+
+## 1. MyGene.info 遺伝子アノテーション
+
+```python
+import requests
+import pandas as pd
+
+MYGENE_API = "https://mygene.info/v3"
+
+
+def mygene_query(query, fields=None, species="human", size=10):
+    """
+    MyGene.info で遺伝子検索。
+
+    Parameters:
+        query: str — gene symbol, Entrez ID, or keyword
+        fields: str | None — comma-separated fields
+        species: str — "human", "mouse", etc.
+
+    ToolUniverse:
+        MyGene_query_genes(q=query, fields=fields, species=species)
+    """
+    params = {
+        "q": query,
+        "species": species,
+        "size": size,
+    }
+    if fields:
+        params["fields"] = fields
+
+    resp = requests.get(f"{MYGENE_API}/query", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    hits = data.get("hits", [])
+    print(f"MyGene query '{query}': {data.get('total', 0)} total, "
+          f"{len(hits)} returned")
+    return hits
+
+
+def mygene_get_gene(gene_id, fields=None):
+    """
+    MyGene.info 遺伝子詳細アノテーション取得。
+
+    ToolUniverse:
+        MyGene_get_gene_annotation(gene_id=gene_id, fields=fields)
+    """
+    params = {}
+    if fields:
+        params["fields"] = fields
+
+    resp = requests.get(f"{MYGENE_API}/gene/{gene_id}", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    print(f"MyGene gene {gene_id}: {data.get('symbol', '?')} "
+          f"({data.get('name', '')})")
+    return data
+
+
+def mygene_batch_query(gene_ids, fields=None, species="human"):
+    """
+    MyGene.info バッチ遺伝子アノテーション。
+
+    ToolUniverse:
+        MyGene_batch_query(ids=gene_ids, fields=fields, species=species)
+    """
+    payload = {
+        "ids": ",".join(str(g) for g in gene_ids),
+        "species": species,
+    }
+    if fields:
+        payload["fields"] = fields
+
+    resp = requests.post(f"{MYGENE_API}/gene", json=payload)
+    resp.raise_for_status()
+    data = resp.json()
+
+    print(f"MyGene batch: {len(gene_ids)} queried → {len(data)} results")
+    return data
+```
+
+## 2. MyVariant.info 変異アノテーション
+
+```python
+MYVARIANT_API = "https://myvariant.info/v1"
+
+
+def myvariant_get(variant_id, fields=None):
+    """
+    MyVariant.info 変異アノテーション取得。
+
+    Parameters:
+        variant_id: str — HGVS notation (e.g., "chr17:g.7674220C>T")
+
+    ToolUniverse:
+        MyVariant_get_variant_annotation(variant_id=variant_id, fields=fields)
+    """
+    params = {}
+    if fields:
+        params["fields"] = fields
+
+    resp = requests.get(f"{MYVARIANT_API}/variant/{variant_id}", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    clinvar = data.get("clinvar", {})
+    cadd = data.get("cadd", {})
+    print(f"MyVariant {variant_id}: "
+          f"ClinVar={clinvar.get('clinical_significance', 'N/A')}, "
+          f"CADD={cadd.get('phred', 'N/A')}")
+    return data
+
+
+def myvariant_query(query, fields=None, size=10):
+    """
+    MyVariant.info 変異検索。
+
+    ToolUniverse:
+        MyVariant_query_variants(q=query, fields=fields, size=size)
+    """
+    params = {"q": query, "size": size}
+    if fields:
+        params["fields"] = fields
+
+    resp = requests.get(f"{MYVARIANT_API}/query", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    hits = data.get("hits", [])
+    print(f"MyVariant query '{query}': {data.get('total', 0)} total")
+    return hits
+```
+
+## 3. MyChem.info 化合物アノテーション
+
+```python
+MYCHEM_API = "https://mychem.info/v1"
+
+
+def mychem_get(chem_id, fields=None):
+    """
+    MyChem.info 化合物アノテーション取得。
+
+    Parameters:
+        chem_id: str — InChIKey, DrugBank ID, ChEMBL ID, etc.
+
+    ToolUniverse:
+        MyChem_get_chemical_annotation(chem_id=chem_id, fields=fields)
+    """
+    params = {}
+    if fields:
+        params["fields"] = fields
+
+    resp = requests.get(f"{MYCHEM_API}/chem/{chem_id}", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    drugbank = data.get("drugbank", {})
+    print(f"MyChem {chem_id}: {drugbank.get('name', 'N/A')}")
+    return data
+
+
+def mychem_query(query, fields=None, size=10):
+    """
+    MyChem.info 化合物検索。
+
+    ToolUniverse:
+        MyChem_query_chemicals(q=query, fields=fields, size=size)
+    """
+    params = {"q": query, "size": size}
+    if fields:
+        params["fields"] = fields
+
+    resp = requests.get(f"{MYCHEM_API}/query", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    hits = data.get("hits", [])
+    print(f"MyChem query '{query}': {data.get('total', 0)} total")
+    return hits
+```
+
+## 4. クロスデータベース ID マッピング
+
+```python
+def cross_db_id_mapping(gene_symbol):
+    """
+    遺伝子シンボルから Entrez, Ensembl, UniProt, RefSeq を一括取得。
+
+    ToolUniverse (横断):
+        MyGene_query_genes(q=gene_symbol, fields="entrezgene,ensembl.gene,uniprot,refseq")
+    """
+    fields = "entrezgene,ensembl.gene,uniprot.Swiss-Prot,refseq.rna,symbol,name"
+    hits = mygene_query(gene_symbol, fields=fields)
+
+    results = []
+    for hit in hits:
+        ensembl = hit.get("ensembl", {})
+        if isinstance(ensembl, list):
+            ensembl = ensembl[0] if ensembl else {}
+        uniprot = hit.get("uniprot", {})
+
+        results.append({
+            "symbol": hit.get("symbol", ""),
+            "name": hit.get("name", ""),
+            "entrez_id": hit.get("entrezgene", ""),
+            "ensembl_gene": ensembl.get("gene", ""),
+            "uniprot_swissprot": uniprot.get("Swiss-Prot", ""),
+            "refseq_rna": hit.get("refseq", {}).get("rna", []),
+        })
+
+    df = pd.DataFrame(results)
+    print(f"ID mapping '{gene_symbol}': {len(df)} entries")
+    return df
+```
+
+## 5. バッチ統合アノテーション
+
+```python
+def batch_integrated_annotation(gene_symbols, include_variants=False):
+    """
+    複数遺伝子のバッチ統合アノテーション。
+
+    ToolUniverse (横断):
+        MyGene_batch_query(ids=entrez_ids, fields=fields)
+        MyVariant_query_variants(q=gene_query) [optional]
+    """
+    # Step 1: Batch gene annotation
+    all_hits = []
+    for symbol in gene_symbols:
+        hits = mygene_query(symbol, fields="entrezgene,symbol,name,summary")
+        all_hits.extend(hits[:1])  # top hit per symbol
+
+    df = pd.DataFrame(all_hits)
+    print(f"Batch annotation: {len(gene_symbols)} genes → {len(df)} results")
+    return df
+```
+
+## References
+
+### Output Files
+
+| ファイル | 形式 |
+|---|---|
+| `results/mygene_annotation.json` | JSON |
+| `results/myvariant_annotation.json` | JSON |
+| `results/mychem_annotation.json` | JSON |
+| `results/id_mapping.csv` | CSV |
+
+### 利用可能ツール
+
+| カテゴリ | 主要ツール | 用途 |
+|---|---|---|
+| BioThings | `MyGene_query_genes` | 遺伝子検索 |
+| BioThings | `MyGene_get_gene_annotation` | 遺伝子詳細 |
+| BioThings | `MyGene_batch_query` | バッチアノテーション |
+| BioThings | `MyVariant_get_variant_annotation` | 変異アノテーション |
+| BioThings | `MyVariant_query_variants` | 変異検索 |
+| BioThings | `MyChem_get_chemical_annotation` | 化合物アノテーション |
+| BioThings | `MyChem_query_chemicals` | 化合物検索 |
+
+### 参照スキル
+
+| スキル | 関連 |
+|---|---|
+| `scientific-variant-interpretation` | 変異アノテーション |
+| `scientific-gene-expression-transcriptomics` | 遺伝子発現 |
+| `scientific-drug-target-interaction` | DTI 解析 |
+| `scientific-rare-disease-genetics` | 希少疾患 |
+| `scientific-pathway-enrichment` | パスウェイ解析 |
+
+### 依存パッケージ
+
+`requests`, `pandas`