@nahisaho/satori 0.13.0 → 0.15.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-cell-line-resources/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: scientific-cell-line-resources
+description: |
+  細胞株リソーススキル。Cellosaurus 細胞株データベース検索、
+  STR プロファイルマッチング、コンタミネーション検出、
+  細胞株メタデータ (由来組織・疾患・種) 取得パイプライン。
+---
+
+# Scientific Cell Line Resources
+
+Cellosaurus を中心とした細胞株リソースデータベースアクセス
+パイプラインを提供する。
+
+## When to Use
+
+- 細胞株の正式名称・アクセッション番号を確認するとき
+- 細胞株の由来 (組織・疾患・種) を調べるとき
+- STR プロファイルで細胞株の同一性を検証するとき
+- 細胞株のコンタミネーション (ミスアイデンティフィケーション) を確認するとき
+- 実験に使用する細胞株の参考文献・データベースリンクを取得するとき
+
+---
+
+## Quick Start
+
+## 1. Cellosaurus 細胞株検索
+
+```python
+import requests
+import pandas as pd
+
+CELLOSAURUS_API = "https://api.cellosaurus.org"
+
+
+def search_cellosaurus(query, limit=25):
+    """
+    Cellosaurus 細胞株検索。
+
+    Parameters:
+        query: str — 細胞株名 (e.g., "HeLa", "MCF-7", "A549")
+        limit: int — 最大取得数
+
+    ToolUniverse:
+        Cellosaurus_search(query=query)
+        Cellosaurus_get_cell_line(accession=accession)
+        Cellosaurus_get_str_profile(accession=accession)
+    """
+    params = {"q": query, "rows": limit, "format": "json"}
+    resp = requests.get(f"{CELLOSAURUS_API}/search/cell-line", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for cell_line in data.get("result", {}).get("cellLineList", []):
+        cl = cell_line.get("cellLine", {})
+        results.append({
+            "accession": cl.get("accession", ""),
+            "name": cl.get("name", ""),
+            "synonyms": [s.get("value", "") for s in cl.get("synonymList", [])],
+            "category": cl.get("category", ""),
+            "sex": cl.get("sex", ""),
+            "species": cl.get("species", {}).get("value", ""),
+            "diseases": [
+                d.get("terminology", {}).get("value", "")
+                for d in cl.get("diseaseList", [])
+            ],
+            "derived_from_site": cl.get("derivedFromSite", {}).get("value", ""),
+            "is_contaminated": cl.get("isContaminated", False),
+            "is_problematic": cl.get("isProblematic", False),
+        })
+
+    df = pd.DataFrame(results)
+    print(f"Cellosaurus search '{query}': {len(df)} cell lines")
+    return df
+```
+
+## 2. 細胞株詳細情報取得
+
+```python
+def get_cellosaurus_entry(accession):
+    """
+    Cellosaurus 細胞株詳細情報取得。
+
+    Parameters:
+        accession: str — Cellosaurus アクセッション (e.g., "CVCL_0030")
+    """
+    resp = requests.get(
+        f"{CELLOSAURUS_API}/cell-line/{accession}",
+        params={"format": "json"}
+    )
+    resp.raise_for_status()
+    data = resp.json()
+
+    cl = data.get("cellLine", {})
+    entry = {
+        "accession": cl.get("accession", ""),
+        "name": cl.get("name", ""),
+        "category": cl.get("category", ""),
+        "sex": cl.get("sex", ""),
+        "age": cl.get("age", ""),
+        "species": cl.get("species", {}).get("value", ""),
+        "diseases": [
+            {
+                "name": d.get("terminology", {}).get("value", ""),
+                "accession": d.get("terminology", {}).get("accession", ""),
+            }
+            for d in cl.get("diseaseList", [])
+        ],
+        "derived_from_site": cl.get("derivedFromSite", {}).get("value", ""),
+        "is_contaminated": cl.get("isContaminated", False),
+        "contamination_comment": cl.get("contaminationComment", ""),
+        "str_profile": cl.get("strList", []),
+        "references": [
+            {
+                "pmid": r.get("pubmedId", ""),
+                "title": r.get("title", ""),
+            }
+            for r in cl.get("referenceList", [])
+        ],
+        "cross_references": [
+            {
+                "database": xr.get("database", ""),
+                "accession": xr.get("accession", ""),
+            }
+            for xr in cl.get("xrefList", [])
+        ],
+    }
+
+    print(f"Cellosaurus {accession}: {entry['name']} "
+          f"({entry['species']}, {entry['category']})")
+    return entry
+```
+
+## 3. STR プロファイル検証
+
+```python
+def check_str_profile(accession, str_data=None):
+    """
+    STR (Short Tandem Repeat) プロファイルによる細胞株同一性検証。
+
+    Parameters:
+        accession: str — Cellosaurus アクセッション
+        str_data: dict — 測定した STR データ {marker: alleles}
+    """
+    entry = get_cellosaurus_entry(accession)
+    ref_str = entry.get("str_profile", [])
+
+    if not ref_str:
+        print(f"WARNING: {accession} has no STR profile in Cellosaurus")
+        return {"match": None, "message": "No reference STR profile available"}
+
+    ref_markers = {}
+    for marker in ref_str:
+        name = marker.get("marker", "")
+        alleles = marker.get("alleles", "")
+        ref_markers[name] = alleles
+
+    if str_data is None:
+        print(f"Reference STR for {accession}: {len(ref_markers)} markers")
+        return {"reference_str": ref_markers, "marker_count": len(ref_markers)}
+
+    # Calculate match percentage
+    matched = 0
+    total = 0
+    details = []
+    for marker, ref_alleles in ref_markers.items():
+        if marker in str_data:
+            total += 1
+            measured = str_data[marker]
+            if set(str(ref_alleles).split(",")) == set(str(measured).split(",")):
+                matched += 1
+                details.append({"marker": marker, "match": True})
+            else:
+                details.append({
+                    "marker": marker, "match": False,
+                    "reference": ref_alleles, "measured": measured,
+                })
+
+    match_pct = (matched / total * 100) if total > 0 else 0
+    result = {
+        "match_percentage": match_pct,
+        "matched": matched,
+        "total_compared": total,
+        "is_authenticated": match_pct >= 80,
+        "details": details,
+    }
+
+    status = "PASS" if result["is_authenticated"] else "FAIL"
+    print(f"STR verification {accession}: {match_pct:.1f}% match → {status}")
+    return result
+```
+
+## 4. コンタミネーション・問題細胞株チェック
+
+```python
+def check_contamination_status(cell_line_names):
+    """
+    細胞株リストのコンタミネーション/ミスアイデンティフィケーション確認。
+
+    Parameters:
+        cell_line_names: list — 細胞株名リスト
+    """
+    results = []
+    for name in cell_line_names:
+        df = search_cellosaurus(name, limit=1)
+        if df.empty:
+            results.append({
+                "name": name, "found": False,
+                "is_contaminated": None, "is_problematic": None,
+            })
+            continue
+
+        row = df.iloc[0]
+        results.append({
+            "name": name,
+            "found": True,
+            "accession": row.get("accession", ""),
+            "official_name": row.get("name", ""),
+            "is_contaminated": row.get("is_contaminated", False),
+            "is_problematic": row.get("is_problematic", False),
+            "species": row.get("species", ""),
+            "diseases": row.get("diseases", []),
+        })
+
+    df = pd.DataFrame(results)
+    contaminated = df["is_contaminated"].sum() if "is_contaminated" in df else 0
+    problematic = df["is_problematic"].sum() if "is_problematic" in df else 0
+    print(f"Cell line check: {len(cell_line_names)} lines, "
+          f"{contaminated} contaminated, {problematic} problematic")
+    return df
+```
+
+---
+
+## 利用可能ツール
+
+| ToolUniverse カテゴリ | 主なツール |
+|---|---|
+| `cellosaurus` | `Cellosaurus_search`, `Cellosaurus_get_cell_line`, `Cellosaurus_get_str_profile` |
+
+## パイプライン出力
+
+| 出力ファイル | 説明 | 連携先スキル |
+|---|---|---|
+| `results/cell_lines.csv` | 細胞株メタデータ | → cancer-genomics, precision-oncology |
+| `results/str_verification.json` | STR 検証結果 | → lab-automation, lab-data-management |
+| `results/contamination_report.json` | コンタミレポート | → research-methodology |
+
+## パイプライン統合
+
+```
+cancer-genomics ──→ cell-line-resources ──→ lab-automation
+  (COSMIC/DepMap)    (Cellosaurus STR)     (プロトコル管理)
+                           │
+                           ├──→ precision-oncology (腫瘍細胞株)
+                           ├──→ disease-research (疾患モデル)
+                           └──→ human-protein-atlas (発現データ)
+```