@nahisaho/satori 0.16.0 → 0.18.0

package/src/.github/skills/scientific-geo-expression/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: scientific-geo-expression
+description: |
+  GEO (Gene Expression Omnibus) 発現プロファイルスキル。GEO REST
+  API データセット検索・サンプル情報・発現マトリクス取得・バルク
+  RNA-seq/マイクロアレイ差次的発現解析。ToolUniverse 連携: geo。
+tu_tools:
+  - key: geo
+    name: GEO (Gene Expression Omnibus)
+    description: GEO データセット・サンプル情報・発現データ検索
+---
+
+# Scientific GEO Expression
+
+GEO REST API を活用したトランスクリプトーム発現プロファイル
+解析パイプラインを提供する。
+
+## When to Use
+
+- GEO データセット (GDS/GSE) を検索・ダウンロードするとき
+- マイクロアレイ/RNA-seq 発現マトリクスを取得するとき
+- 条件間差次的発現解析 (DEG) を実行するとき
+- 複数 GEO データセットを横断比較するとき
+- GEO メタデータから実験条件を構造化するとき
+- 再解析パイプラインで GEO データを再利用するとき
+
+---
+
+## Quick Start
+
+## 1. GEO データセット検索
+
+```python
+import requests
+import pandas as pd
+import GEOparse
+from io import StringIO
+
+GEO_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+
+
+def geo_search_datasets(query, organism="Homo sapiens",
+                         study_type=None, limit=20):
+    """
+    GEO — データセット検索 (E-utilities)。
+
+    Parameters:
+        query: str — 検索クエリ (例: "breast cancer RNA-seq")
+        organism: str — 生物種
+        study_type: str — 研究タイプ ("Expression profiling by array" etc.)
+        limit: int — 最大結果数
+    """
+    search_term = f"{query} AND {organism}[Organism]"
+    if study_type:
+        search_term += f' AND "{study_type}"[Study Type]'
+
+    # ESearch
+    url = f"{GEO_BASE}/esearch.fcgi"
+    params = {
+        "db": "gds",
+        "term": search_term,
+        "retmax": limit,
+        "retmode": "json",
+    }
+    resp = requests.get(url, params=params, timeout=30)
+    resp.raise_for_status()
+    ids = resp.json().get("esearchresult", {}).get("idlist", [])
+
+    if not ids:
+        print("No GEO datasets found")
+        return pd.DataFrame()
+
+    # ESummary
+    url = f"{GEO_BASE}/esummary.fcgi"
+    params = {"db": "gds", "id": ",".join(ids), "retmode": "json"}
+    resp = requests.get(url, params=params, timeout=30)
+    resp.raise_for_status()
+    summaries = resp.json().get("result", {})
+
+    results = []
+    for gds_id in ids:
+        info = summaries.get(gds_id, {})
+        results.append({
+            "accession": info.get("accession", ""),
+            "title": info.get("title", ""),
+            "summary": info.get("summary", "")[:200],
+            "organism": info.get("taxon", ""),
+            "platform": info.get("gpl", ""),
+            "sample_count": info.get("n_samples", 0),
+            "series_type": info.get("gdstype", ""),
+            "pub_date": info.get("pdat", ""),
+        })
+
+    df = pd.DataFrame(results)
+    print(f"GEO search: {len(df)} datasets")
+    return df
+```
+
+## 2. GEO 発現マトリクス取得
+
+```python
+def geo_get_expression_matrix(gse_id, log2_transform=True):
+    """
+    GEO — GSE 発現マトリクス取得 (GEOparse)。
+
+    Parameters:
+        gse_id: str — GSE アクセッション (例: "GSE12345")
+        log2_transform: bool — log2 変換を適用するか
+    """
+    import numpy as np
+
+    gse = GEOparse.get_GEO(geo=gse_id, destdir="/tmp", silent=True)
+
+    # サンプルメタデータ
+    samples = []
+    for gsm_name, gsm in gse.gsms.items():
+        meta = gsm.metadata
+        samples.append({
+            "sample_id": gsm_name,
+            "title": meta.get("title", [""])[0],
+            "source": meta.get("source_name_ch1", [""])[0],
+            "characteristics": "; ".join(
+                meta.get("characteristics_ch1", [])),
+            "platform": meta.get("platform_id", [""])[0],
+        })
+    sample_df = pd.DataFrame(samples)
+
+    # 発現マトリクス
+    pivoted = gse.pivot_samples("VALUE")
+    if pivoted.empty:
+        print(f"No expression data in {gse_id}")
+        return sample_df, pd.DataFrame()
+
+    if log2_transform:
+        pivoted = np.log2(pivoted.astype(float) + 1)
+
+    print(f"GEO {gse_id}: {pivoted.shape[0]} probes × "
+          f"{pivoted.shape[1]} samples")
+    return sample_df, pivoted
+```
+
+## 3. 差次的発現解析
+
+```python
+from scipy import stats
+import numpy as np
+
+
+def geo_differential_expression(expr_matrix, group_a_samples,
+                                  group_b_samples, method="ttest",
+                                  fdr_threshold=0.05, lfc_threshold=1.0):
+    """
+    GEO — 差次的発現解析。
+
+    Parameters:
+        expr_matrix: pd.DataFrame — 発現マトリクス (genes × samples)
+        group_a_samples: list[str] — グループ A サンプル ID
+        group_b_samples: list[str] — グループ B サンプル ID
+        method: str — "ttest" or "wilcoxon"
+        fdr_threshold: float — FDR 閾値
+        lfc_threshold: float — log2FC 閾値
+    """
+    a_data = expr_matrix[group_a_samples]
+    b_data = expr_matrix[group_b_samples]
+
+    results = []
+    for gene in expr_matrix.index:
+        a_vals = a_data.loc[gene].dropna().values
+        b_vals = b_data.loc[gene].dropna().values
+
+        if len(a_vals) < 2 or len(b_vals) < 2:
+            continue
+
+        lfc = b_vals.mean() - a_vals.mean()
+
+        if method == "ttest":
+            stat, pval = stats.ttest_ind(a_vals, b_vals)
+        else:
+            stat, pval = stats.mannwhitneyu(a_vals, b_vals,
+                                             alternative="two-sided")
+
+        results.append({
+            "gene": gene,
+            "log2fc": lfc,
+            "mean_a": a_vals.mean(),
+            "mean_b": b_vals.mean(),
+            "statistic": stat,
+            "p_value": pval,
+        })
+
+    df = pd.DataFrame(results)
+
+    # FDR correction (Benjamini-Hochberg)
+    from statsmodels.stats.multitest import multipletests
+    _, df["fdr"], _, _ = multipletests(df["p_value"], method="fdr_bh")
+
+    # DEG フィルタ
+    df["is_deg"] = (df["fdr"] < fdr_threshold) & (df["log2fc"].abs() > lfc_threshold)
+    n_deg = df["is_deg"].sum()
+    n_up = ((df["is_deg"]) & (df["log2fc"] > 0)).sum()
+    n_down = ((df["is_deg"]) & (df["log2fc"] < 0)).sum()
+
+    print(f"DEG: {n_deg} genes (↑{n_up} / ↓{n_down}), "
+          f"FDR<{fdr_threshold}, |LFC|>{lfc_threshold}")
+    return df.sort_values("p_value")
+```
+
+## 4. GEO 発現プロファイリングパイプライン
+
+```python
+def geo_expression_pipeline(gse_id, group_col="condition",
+                              group_a="control", group_b="treatment",
+                              output_dir="results"):
+    """
+    GEO 発現プロファイリング統合パイプライン。
+
+    Parameters:
+        gse_id: str — GSE アクセッション
+        group_col: str — グループ化カラム
+        group_a: str — コントロールグループ
+        group_b: str — 処理グループ
+        output_dir: str — 出力ディレクトリ
+    """
+    from pathlib import Path
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1) データ取得
+    sample_df, expr = geo_get_expression_matrix(gse_id)
+    sample_df.to_csv(output_dir / "samples.csv", index=False)
+
+    # 2) グループ分割
+    a_samples = sample_df[
+        sample_df["source"].str.contains(group_a, case=False)
+    ]["sample_id"].tolist()
+    b_samples = sample_df[
+        sample_df["source"].str.contains(group_b, case=False)
+    ]["sample_id"].tolist()
+
+    # 3) 差次的発現
+    deg = geo_differential_expression(expr, a_samples, b_samples)
+    deg.to_csv(output_dir / "deg_results.csv", index=False)
+
+    print(f"GEO pipeline: {output_dir}")
+    return {"samples": sample_df, "expression": expr, "deg": deg}
+```
+
+---
+
+## ToolUniverse 連携
+
+| TU Key | ツール名 | 連携内容 |
+|--------|---------|---------|
+| `geo` | GEO | データセット検索・サンプル情報・発現データ |
+
+## パイプライン統合
+
+```
+ebi-databases → geo-expression → gene-expression-transcriptomics
+  (ENA/EBI Search) (GEO データ)    (DESeq2/GTEx)
+       │                 │                ↓
+  literature-search ────┘         pathway-enrichment
+  (PubMed/OpenAlex)   │          (KEGG/Reactome/GO)
+                       ↓
+                  multi-omics
+                  (統合解析)
+```
+
+## パイプライン出力
+
+| ファイル | 説明 | 次スキル |
+|---------|------|---------|
+| `results/samples.csv` | サンプルメタデータ | → gene-expression-transcriptomics |
+| `results/deg_results.csv` | 差次的発現結果 | → pathway-enrichment |

package/src/.github/skills/scientific-gtex-tissue-expression/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: scientific-gtex-tissue-expression
+description: |
+  GTEx 組織発現スキル。GTEx Portal REST API v2 による
+  組織特異的遺伝子発現パターン解析・eQTL ルックアップ・
+  多組織比較。直接 API (ToolUniverse 非連携)。
+tu_tools: []
+---
+
+# Scientific GTEx Tissue Expression
+
+GTEx (Genotype-Tissue Expression) Portal REST API v2 を活用した
+組織特異的遺伝子発現解析・eQTL 検索・多組織比較パイプライン
+を提供する。
+
+## When to Use
+
+- 遺伝子の組織特異的発現パターンを調べるとき
+- 特定組織における eQTL (発現量的形質遺伝子座) を検索するとき
+- 複数組織間で遺伝子発現レベルを比較するとき
+- TPM (Transcripts Per Million) 発現データを取得するとき
+- バリアントが遺伝子発現に与える影響を評価するとき
+- 組織間の遺伝子共発現パターンを分析するとき
+
+---
+
+## Quick Start
+
+## 1. 組織特異的遺伝子発現取得
+
+```python
+import requests
+import pandas as pd
+
+GTEX_BASE = "https://gtexportal.org/api/v2"
+
+
+def gtex_gene_expression(gene_id, tissue=None):
+    """
+    GTEx — 組織別遺伝子発現 (中央値 TPM) 取得。
+
+    Parameters:
+        gene_id: str — 遺伝子シンボル or Ensembl ID
+            (例: "BRCA1", "ENSG00000012048")
+        tissue: str — 組織 ID (None で全組織)
+            (例: "Breast_Mammary_Tissue")
+    """
+    url = f"{GTEX_BASE}/expression/medianGeneExpression"
+    params = {
+        "gencodeId": gene_id,
+        "datasetId": "gtex_v8",
+    }
+    if tissue:
+        params["tissueSiteDetailId"] = tissue
+
+    resp = requests.get(url, params=params, timeout=30)
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for item in data.get("data", []):
+        results.append({
+            "gene_symbol": item.get("geneSymbol", ""),
+            "gencode_id": item.get("gencodeId", ""),
+            "tissue": item.get("tissueSiteDetailId", ""),
+            "tissue_name": item.get("tissueSiteDetail", ""),
+            "median_tpm": item.get("median", 0),
+            "sample_count": item.get("numSamples", 0),
+        })
+
+    df = pd.DataFrame(results)
+    if not df.empty:
+        df = df.sort_values("median_tpm", ascending=False)
+
+    print(f"GTEx expression: {gene_id} → "
+          f"{len(df)} tissues")
+    return df
+
+
+def gtex_top_tissues(gene_id, top_n=10):
+    """
+    GTEx — 発現量上位組織。
+
+    Parameters:
+        gene_id: str — 遺伝子シンボル or Ensembl ID
+        top_n: int — 上位組織数
+    """
+    df = gtex_gene_expression(gene_id)
+    top = df.head(top_n) if not df.empty else df
+    print(f"GTEx top {top_n} tissues for {gene_id}:")
+    for _, row in top.iterrows():
+        print(f"  {row['tissue_name']}: "
+              f"{row['median_tpm']:.2f} TPM "
+              f"(n={row['sample_count']})")
+    return top
+```
+
+## 2. eQTL 検索
+
+```python
+def gtex_eqtl_lookup(gene_id, tissue, variant_id=None):
+    """
+    GTEx — eQTL ルックアップ。
+
+    Parameters:
+        gene_id: str — 遺伝子シンボル or Ensembl ID
+        tissue: str — 組織 ID
+            (例: "Liver", "Whole_Blood")
+        variant_id: str — バリアント ID (任意)
+            (例: "rs12345")
+    """
+    url = f"{GTEX_BASE}/association/singleTissueEqtl"
+    params = {
+        "gencodeId": gene_id,
+        "tissueSiteDetailId": tissue,
+        "datasetId": "gtex_v8",
+    }
+    if variant_id:
+        params["variantId"] = variant_id
+
+    resp = requests.get(url, params=params, timeout=30)
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for item in data.get("data", []):
+        results.append({
+            "gene_symbol": item.get("geneSymbol", ""),
+            "variant_id": item.get("variantId", ""),
+            "tissue": tissue,
+            "pvalue": item.get("pValue"),
+            "nes": item.get("nes"),  # normalized effect size
+            "maf": item.get("maf"),
+            "ref": item.get("ref", ""),
+            "alt": item.get("alt", ""),
+        })
+
+    df = pd.DataFrame(results)
+    if not df.empty:
+        df = df.sort_values("pvalue")
+
+    print(f"GTEx eQTL: {gene_id} in {tissue} → "
+          f"{len(df)} associations")
+    return df
+```
+
+## 3. 多組織比較
+
+```python
+def gtex_multi_gene_comparison(gene_ids, tissues=None):
+    """
+    GTEx — 複数遺伝子・複数組織の発現比較。
+
+    Parameters:
+        gene_ids: list[str] — 遺伝子リスト
+        tissues: list[str] — 組織リスト (None で全組織)
+    """
+    all_data = []
+    for gid in gene_ids:
+        try:
+            df = gtex_gene_expression(gid)
+            if tissues:
+                df = df[df["tissue"].isin(tissues)]
+            all_data.append(df)
+        except Exception as e:
+            print(f"  Warning: {gid} — {e}")
+            continue
+
+    if not all_data:
+        return pd.DataFrame()
+
+    combined = pd.concat(all_data, ignore_index=True)
+
+    # ピボットテーブル: 行=組織, 列=遺伝子, 値=TPM
+    if not combined.empty:
+        pivot = combined.pivot_table(
+            index="tissue_name",
+            columns="gene_symbol",
+            values="median_tpm",
+            aggfunc="first",
+        )
+        print(f"GTEx comparison: {len(gene_ids)} genes × "
+              f"{len(pivot)} tissues")
+        return pivot
+
+    return combined
+```
+
+## 4. GTEx 統合パイプライン
+
+```python
+def gtex_pipeline(gene_ids, tissues=None,
+                    output_dir="results"):
+    """
+    GTEx 統合パイプライン。
+
+    Parameters:
+        gene_ids: list[str] — 遺伝子リスト
+        tissues: list[str] — 組織リスト (None で全組織)
+        output_dir: str — 出力ディレクトリ
+    """
+    from pathlib import Path
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1) 全遺伝子の組織発現
+    all_expr = []
+    for gid in gene_ids:
+        try:
+            df = gtex_gene_expression(gid)
+            df.to_csv(output_dir / f"expression_{gid}.csv",
+                      index=False)
+            all_expr.append(df)
+        except Exception:
+            continue
+
+    # 2) 多組織比較マトリクス
+    pivot = gtex_multi_gene_comparison(gene_ids, tissues)
+    if isinstance(pivot, pd.DataFrame) and not pivot.empty:
+        pivot.to_csv(output_dir / "expression_matrix.csv")
+
+    # 3) eQTL 検索 (上位組織)
+    eqtl_results = []
+    for gid in gene_ids:
+        if all_expr:
+            top = all_expr[-1].head(3)
+            for _, row in top.iterrows():
+                try:
+                    eqtl = gtex_eqtl_lookup(gid,
+                                              row["tissue"])
+                    eqtl_results.append(eqtl)
+                except Exception:
+                    continue
+    if eqtl_results:
+        eqtl_combined = pd.concat(eqtl_results,
+                                    ignore_index=True)
+        eqtl_combined.to_csv(output_dir / "eqtl_results.csv",
+                              index=False)
+
+    print(f"GTEx pipeline: {output_dir}")
+    return {"expression": all_expr, "matrix": pivot}
+```
+
+---
+
+## ToolUniverse 連携
+
+| TU Key | ツール名 | 連携内容 |
+|--------|---------|---------|
+| (direct) | GTEx Portal API v2 | 直接 REST API — TU 非連携 |
+
+## パイプライン統合
+
+```
+gene-expression-transcriptomics → gtex-tissue-expression → variant-interpretation
+  (DESeq2/edgeR 差分発現)     (組織別 TPM + eQTL)       (臨床変異評価)
+          │                          │                        ↓
+  arrayexpress-expression ──────────┘              gwas-catalog
+  (ArrayExpress データ)          │               (GWAS 関連解析)
+                                 ↓
+                        disease-research
+                        (疾患関連遺伝子)
+```
+
+## パイプライン出力
+
+| ファイル | 説明 | 次スキル |
+|---------|------|---------|
+| `results/expression_*.csv` | 遺伝子別組織発現 | → disease-research |
+| `results/expression_matrix.csv` | 多遺伝子比較 | → pathway-enrichment |
+| `results/eqtl_results.csv` | eQTL 関連 | → variant-interpretation |