@nahisaho/satori 0.14.0 → 0.15.0

package/src/.github/skills/scientific-perturbation-analysis/SKILL.md

@@ -0,0 +1,297 @@
+---
+name: scientific-perturbation-analysis
+description: |
+  シングルセル摂動解析スキル。pertpy による CRISPR スクリーン解析・
+  薬剤応答分析・scGen 摂動予測・Augur 摂動応答性スコアリング・
+  scIB 統合ベンチマーク・差次的摂動応答パイプライン。
+---
+
+# Scientific Perturbation Analysis
+
+pertpy / Augur / scIB を活用したシングルセルレベルの摂動解析
+パイプラインを提供する。CRISPR スクリーン、薬剤処理、
+遺伝子ノックダウンなどの摂動データの統合解析。
+
+## When to Use
+
+- CRISPR スクリーンデータ (Perturb-seq) を解析するとき
+- 薬剤処理前後のシングルセル発現変動を評価するとき
+- 摂動応答の細胞型特異性を定量するとき
+- 複数のバッチ統合手法をベンチマークするとき (scIB)
+- 摂動の効果を in silico で予測するとき (scGen)
+- 差次的優先度 (Augur) で摂動応答性の高い細胞型を特定するとき
+
+---
+
+## Quick Start
+
+## 1. pertpy セットアップ & データ読込み
+
+```python
+import pertpy as pt
+import scanpy as sc
+import anndata as ad
+import pandas as pd
+import numpy as np
+
+
+def load_perturbation_data(adata_path, perturbation_key="perturbation",
+                           control_label="control"):
+    """
+    摂動実験 AnnData 読込み & 前処理。
+
+    Parameters:
+        adata_path: str — AnnData ファイルパス
+        perturbation_key: str — 摂動ラベルカラム
+        control_label: str — コントロールラベル
+
+    K-Dense: pertpy
+    """
+    adata = sc.read_h5ad(adata_path)
+
+    # 基本前処理
+    sc.pp.filter_cells(adata, min_genes=200)
+    sc.pp.filter_genes(adata, min_cells=3)
+    sc.pp.normalize_total(adata, target_sum=1e4)
+    sc.pp.log1p(adata)
+
+    n_perturbations = adata.obs[perturbation_key].nunique()
+    n_control = (adata.obs[perturbation_key] == control_label).sum()
+    n_perturbed = len(adata) - n_control
+
+    print(f"Loaded: {len(adata)} cells, {n_perturbations} perturbations")
+    print(f"Control: {n_control}, Perturbed: {n_perturbed}")
+    return adata
+```
+
+## 2. 差次的遺伝子発現 (摂動 vs コントロール)
+
+```python
+def differential_perturbation(adata, perturbation_key="perturbation",
+                               control="control", target=None):
+    """
+    摂動-コントロール間差次的発現解析。
+
+    Parameters:
+        adata: AnnData — 摂動データ
+        perturbation_key: str — 摂動ラベル
+        control: str — コントロールラベル
+        target: str — 比較対象摂動 (None で全摂動)
+    """
+    if target:
+        mask = adata.obs[perturbation_key].isin([control, target])
+        adata_sub = adata[mask].copy()
+    else:
+        adata_sub = adata.copy()
+
+    sc.tl.rank_genes_groups(
+        adata_sub,
+        groupby=perturbation_key,
+        reference=control,
+        method="wilcoxon",
+    )
+
+    results = {}
+    for group in adata_sub.obs[perturbation_key].unique():
+        if group == control:
+            continue
+        try:
+            degs = sc.get.rank_genes_groups_df(adata_sub, group=group)
+            degs_sig = degs[degs["pvals_adj"] < 0.05]
+            results[group] = {
+                "n_degs": len(degs_sig),
+                "n_up": (degs_sig["logfoldchanges"] > 0).sum(),
+                "n_down": (degs_sig["logfoldchanges"] < 0).sum(),
+                "top_genes": degs_sig.head(10)["names"].tolist(),
+            }
+        except Exception:
+            continue
+
+    print(f"DE results: {len(results)} perturbations analyzed")
+    return results
+```
+
+## 3. Augur 摂動応答性スコアリング
+
+```python
+def augur_prioritization(adata, perturbation_key="perturbation",
+                         cell_type_key="cell_type", control="control"):
+    """
+    Augur で細胞型ごとの摂動応答性をスコアリング。
+
+    Parameters:
+        adata: AnnData — 摂動データ
+        perturbation_key: str — 摂動ラベル
+        cell_type_key: str — 細胞型ラベル
+        control: str — コントロールラベル
+
+    K-Dense: augur (via pertpy)
+    """
+    ag = pt.tl.Augur(estimator="random_forest_classifier")
+
+    # 摂動 vs コントロールで各細胞型のAUC計算
+    adata_augur, results = ag.predict(
+        adata,
+        condition_key=perturbation_key,
+        cell_type_key=cell_type_key,
+        control_label=control,
+    )
+
+    # 結果をDataFrameに
+    auc_df = results["summary_metrics"]
+    auc_df = auc_df.sort_values("auc", ascending=False)
+
+    print(f"Augur prioritization:")
+    for _, row in auc_df.head(5).iterrows():
+        print(f"  {row['cell_type']}: AUC={row['auc']:.3f}")
+
+    return auc_df
+```
+
+## 4. scGen 摂動予測
+
+```python
+def scgen_perturbation_prediction(adata, perturbation_key="perturbation",
+                                   cell_type_key="cell_type",
+                                   control="control", target_perturbation=None,
+                                   target_cell_type=None):
+    """
+    scGen による摂動効果の in silico 予測。
+
+    Parameters:
+        adata: AnnData — 訓練データ
+        target_perturbation: str — 予測対象の摂動
+        target_cell_type: str — 予測対象の細胞型
+    """
+    import scgen
+
+    # モデル訓練
+    scg = scgen.SCGEN(adata)
+    scg.train(max_epochs=100, batch_size=32)
+
+    # 予測
+    pred, delta = scg.predict(
+        ctrl_key=control,
+        stim_key=target_perturbation,
+        celltype_to_predict=target_cell_type,
+    )
+
+    print(f"scGen prediction: {target_cell_type} under {target_perturbation}")
+    print(f"  Predicted cells: {pred.shape[0]}")
+    return pred, delta
+```
+
+## 5. scIB 統合ベンチマーク
+
+```python
+def benchmark_integration(adata, batch_key="batch", label_key="cell_type",
+                           methods=None):
+    """
+    scIB でバッチ統合手法をベンチマーク。
+
+    Parameters:
+        adata: AnnData — バッチ混在データ
+        batch_key: str — バッチラベル
+        label_key: str — 細胞型ラベル
+        methods: list — 評価するメトリクス
+
+    K-Dense: scib
+    """
+    import scib
+
+    if methods is None:
+        methods = ["scib"]
+
+    # 基本メトリクス
+    metrics = {}
+
+    # batch correction metrics
+    metrics["batch_kbet"] = scib.me.kBET(
+        adata, batch_key=batch_key, label_key=label_key
+    )
+    metrics["batch_silhouette"] = scib.me.silhouette_batch(
+        adata, batch_key=batch_key, label_key=label_key, embed="X_pca"
+    )
+
+    # bio conservation metrics
+    metrics["bio_nmi"] = scib.me.nmi(adata, label_key, "leiden")
+    metrics["bio_ari"] = scib.me.ari(adata, label_key, "leiden")
+    metrics["bio_silhouette"] = scib.me.silhouette(
+        adata, label_key=label_key, embed="X_pca"
+    )
+
+    # 総合スコア
+    metrics["overall"] = 0.6 * np.mean([
+        metrics["bio_nmi"], metrics["bio_ari"], metrics["bio_silhouette"]
+    ]) + 0.4 * np.mean([
+        metrics["batch_kbet"], metrics["batch_silhouette"]
+    ])
+
+    print(f"scIB benchmark:")
+    for k, v in metrics.items():
+        print(f"  {k}: {v:.4f}")
+    return metrics
+```
+
+## 6. 摂動シグネチャ解析
+
+```python
+def perturbation_signature(adata, perturbation_key="perturbation",
+                            control="control", n_top_genes=50):
+    """
+    摂動特異的遺伝子シグネチャ抽出。
+
+    Parameters:
+        adata: AnnData — 摂動データ
+        perturbation_key: str — 摂動ラベル
+        control: str — コントロールラベル
+        n_top_genes: int — トップ遺伝子数
+    """
+    perturbations = [p for p in adata.obs[perturbation_key].unique()
+                     if p != control]
+
+    signatures = {}
+    ctrl_mean = adata[adata.obs[perturbation_key] == control].X.mean(axis=0)
+    ctrl_mean = np.asarray(ctrl_mean).flatten()
+
+    for pert in perturbations:
+        pert_mask = adata.obs[perturbation_key] == pert
+        pert_mean = adata[pert_mask].X.mean(axis=0)
+        pert_mean = np.asarray(pert_mean).flatten()
+
+        delta = pert_mean - ctrl_mean
+        gene_indices = np.argsort(np.abs(delta))[::-1][:n_top_genes]
+
+        signatures[pert] = {
+            "top_genes": adata.var_names[gene_indices].tolist(),
+            "deltas": delta[gene_indices].tolist(),
+            "n_cells": int(pert_mask.sum()),
+        }
+
+    print(f"Signatures extracted: {len(signatures)} perturbations, "
+          f"{n_top_genes} genes each")
+    return signatures
+```
+
+---
+
+## パイプライン統合
+
+```
+single-cell-genomics → perturbation-analysis → pathway-enrichment
+  (scRNA-seq QC)        (摂動 DE/Augur/scGen)   (KEGG/Reactome)
+        │                        │                     ↓
+spatial-transcriptomics ──┘      │            disease-research
+  (Visium/MERFISH)               ↓              (GWAS/DisGeNET)
+                       drug-target-profiling
+                       (標的候補評価)
+```
+
+## パイプライン出力
+
+| ファイル | 説明 | 次スキル |
+|---------|------|---------|
+| `results/perturbation_de.json` | 差次的発現結果 | → pathway-enrichment |
+| `results/augur_scores.csv` | Augur 応答性スコア | → single-cell-genomics |
+| `results/perturbation_signatures.json` | 摂動シグネチャ | → drug-target-profiling |
+| `results/scib_benchmark.json` | 統合ベンチマーク | → spatial-transcriptomics |

package/src/.github/skills/scientific-scvi-integration/SKILL.md

@@ -0,0 +1,344 @@
+---
+name: scientific-scvi-integration
+description: |
+  scvi-tools シングルセル統合スキル。scVI 変分オートエンコーダ統合・
+  scANVI 半教師有りアノテーション・totalVI CITE-seq
+  RNA+タンパク質結合解析・SOLO ダブレット検出・潜在空間解析。
+---
+
+# Scientific scVI Integration
+
+scvi-tools を活用したシングルセル確率的モデルベース統合
+パイプラインを提供する。scVI/scANVI/totalVI/SOLO による
+バッチ統合、半教師有りアノテーション、マルチモーダル解析。
+
+## When to Use
+
+- 複数バッチの scRNA-seq データを統合するとき (scVI)
+- 半教師有りで細胞型アノテーションを転移するとき (scANVI)
+- CITE-seq (RNA + ADT) データを結合解析するとき (totalVI)
+- ダブレット (doublet) を検出・除去するとき (SOLO)
+- 差次的発現を確率的にテストするとき
+- 潜在空間を用いたクラスタリングを行うとき
+
+---
+
+## Quick Start
+
+## 1. scVI モデルセットアップ & 訓練
+
+```python
+import scvi
+import scanpy as sc
+import anndata as ad
+import numpy as np
+import pandas as pd
+
+
+def setup_scvi(adata, batch_key="batch", layer=None, n_latent=30,
+               n_hidden=128, n_layers=2):
+    """
+    scVI 変分オートエンコーダのセットアップ & 訓練。
+
+    Parameters:
+        adata: AnnData — 入力データ (raw counts)
+        batch_key: str — バッチキー
+        layer: str — カウント格納レイヤー
+        n_latent: int — 潜在次元数
+        n_hidden: int — 隠れユニット数
+        n_layers: int — ニューラルネットレイヤー数
+
+    K-Dense: scvi-tools
+    """
+    # scVI データ登録
+    scvi.model.SCVI.setup_anndata(
+        adata,
+        batch_key=batch_key,
+        layer=layer,
+    )
+
+    # モデル構築
+    model = scvi.model.SCVI(
+        adata,
+        n_latent=n_latent,
+        n_hidden=n_hidden,
+        n_layers=n_layers,
+        gene_likelihood="zinb",  # zero-inflated negative binomial
+    )
+
+    # 訓練
+    model.train(max_epochs=400, early_stopping=True)
+
+    # 潜在空間取得
+    latent = model.get_latent_representation()
+    adata.obsm["X_scVI"] = latent
+
+    print(f"scVI trained: {len(adata)} cells → {n_latent}D latent space")
+    print(f"  Batches: {adata.obs[batch_key].nunique()}")
+    return model
+```
+
+## 2. scVI バッチ統合 & UMAP
+
+```python
+def scvi_integration(adata, model, resolution=1.0):
+    """
+    scVI 潜在空間でバッチ統合 & クラスタリング。
+
+    Parameters:
+        adata: AnnData — scVI 登録済みデータ
+        model: scvi.model.SCVI — 訓練済みモデル
+        resolution: float — Leiden 解像度
+    """
+    # 潜在空間から近傍グラフ
+    sc.pp.neighbors(adata, use_rep="X_scVI")
+    sc.tl.umap(adata)
+    sc.tl.leiden(adata, resolution=resolution)
+
+    n_clusters = adata.obs["leiden"].nunique()
+    print(f"scVI integration: {n_clusters} clusters (resolution={resolution})")
+    return adata
+```
+
+## 3. scANVI 半教師有りアノテーション
+
+```python
+def scanvi_annotation(adata, scvi_model, labels_key="cell_type",
+                      unlabeled_category="Unknown", n_epochs=20):
+    """
+    scANVI で半教師有り細胞型アノテーション転移。
+
+    Parameters:
+        adata: AnnData — scVI 登録済みデータ
+        scvi_model: scvi.model.SCVI — 訓練済み scVI
+        labels_key: str — 既知ラベルカラム
+        unlabeled_category: str — 未知ラベル値
+        n_epochs: int — 追加訓練エポック
+    """
+    # scANVI = scVI + 半教師有り
+    scanvi_model = scvi.model.SCANVI.from_scvi_model(
+        scvi_model,
+        unlabeled_category=unlabeled_category,
+        labels_key=labels_key,
+    )
+
+    scanvi_model.train(max_epochs=n_epochs)
+
+    # 予測ラベル
+    predictions = scanvi_model.predict()
+    adata.obs["scANVI_prediction"] = predictions
+
+    # 予測確率
+    soft_predictions = scanvi_model.predict(soft=True)
+    adata.obs["scANVI_confidence"] = soft_predictions.max(axis=1)
+
+    n_labeled = (adata.obs[labels_key] != unlabeled_category).sum()
+    n_unlabeled = (adata.obs[labels_key] == unlabeled_category).sum()
+    mean_conf = adata.obs["scANVI_confidence"].mean()
+
+    print(f"scANVI annotation:")
+    print(f"  Labeled: {n_labeled}, Unlabeled: {n_unlabeled}")
+    print(f"  Mean confidence: {mean_conf:.3f}")
+    return scanvi_model
+```
+
+## 4. totalVI CITE-seq 統合
+
+```python
+def totalvi_citeseq(adata, protein_expression_obsm="protein_expression",
+                    batch_key="batch", n_latent=20, n_epochs=400):
+    """
+    totalVI で RNA + ADT (CITE-seq) 結合解析。
+
+    Parameters:
+        adata: AnnData — RNA counts + protein expression
+        protein_expression_obsm: str — ADT 格納 obsm キー
+        batch_key: str — バッチキー
+        n_latent: int — 潜在次元数
+    """
+    scvi.model.TOTALVI.setup_anndata(
+        adata,
+        batch_key=batch_key,
+        protein_expression_obsm_key=protein_expression_obsm,
+    )
+
+    model = scvi.model.TOTALVI(
+        adata,
+        n_latent=n_latent,
+        latent_distribution="normal",
+    )
+
+    model.train(max_epochs=n_epochs, early_stopping=True)
+
+    # 潜在空間
+    latent = model.get_latent_representation()
+    adata.obsm["X_totalVI"] = latent
+
+    # タンパク質前景確率 (denoised)
+    _, protein_fore = model.get_normalized_expression(
+        n_samples=25,
+        return_mean=True,
+    )
+
+    n_proteins = protein_fore.shape[1] if hasattr(protein_fore, 'shape') else 0
+    print(f"totalVI: {len(adata)} cells, {n_proteins} proteins")
+    print(f"  Latent dim: {n_latent}")
+    return model
+```
+
+## 5. SOLO ダブレット検出
+
+```python
+def solo_doublet_detection(adata, scvi_model, threshold=0.5):
+    """
+    SOLO でダブレット検出。
+
+    Parameters:
+        adata: AnnData — scVI 登録済みデータ
+        scvi_model: scvi.model.SCVI — 訓練済み scVI
+        threshold: float — ダブレット判定閾値
+    """
+    solo_model = scvi.external.SOLO.from_scvi_model(scvi_model)
+    solo_model.train()
+
+    # ダブレット予測
+    predictions = solo_model.predict()
+    predictions["label"] = predictions.apply(
+        lambda x: "doublet" if x["doublet"] > threshold else "singlet",
+        axis=1,
+    )
+
+    adata.obs["solo_doublet"] = predictions["label"].values
+    adata.obs["solo_score"] = predictions["doublet"].values
+
+    n_doublets = (adata.obs["solo_doublet"] == "doublet").sum()
+    doublet_rate = n_doublets / len(adata) * 100
+
+    print(f"SOLO doublet detection:")
+    print(f"  Doublets: {n_doublets} ({doublet_rate:.1f}%)")
+    print(f"  Singlets: {len(adata) - n_doublets}")
+    return predictions
+```
+
+## 6. scVI 差次的発現
+
+```python
+def scvi_differential_expression(model, adata, groupby="leiden",
+                                  group1="0", group2="1",
+                                  delta=0.25, batch_size=256):
+    """
+    scVI による確率的差次的発現。
+
+    Parameters:
+        model: scvi.model.SCVI — 訓練済みモデル
+        adata: AnnData — 入力データ
+        groupby: str — グループカラム
+        group1: str — 比較グループ1
+        group2: str — 比較グループ2
+        delta: float — LFC 閾値
+    """
+    de_results = model.differential_expression(
+        groupby=groupby,
+        group1=group1,
+        group2=group2,
+        delta=delta,
+        batch_size=batch_size,
+    )
+
+    # 有意な遺伝子フィルタ
+    sig_genes = de_results[
+        (de_results["is_de_fdr_0.05"])
+        & (de_results["lfc_mean"].abs() > delta)
+    ]
+
+    sig_genes = sig_genes.sort_values("lfc_mean", ascending=False)
+
+    print(f"scVI DE: {group1} vs {group2}")
+    print(f"  Significant genes: {len(sig_genes)}")
+    print(f"  Up in {group1}: {(sig_genes['lfc_mean'] > 0).sum()}")
+    print(f"  Up in {group2}: {(sig_genes['lfc_mean'] < 0).sum()}")
+    return sig_genes
+```
+
+## 7. 統合パイプライン
+
+```python
+def scvi_pipeline(adata_paths, batch_labels=None, labels_key="cell_type",
+                  output_dir="results"):
+    """
+    scVI → scANVI → SOLO 統合パイプライン。
+
+    Parameters:
+        adata_paths: list — AnnData ファイルパスリスト
+        batch_labels: list — バッチラベル
+        labels_key: str — 細胞型ラベルカラム
+        output_dir: str — 出力ディレクトリ
+    """
+    from pathlib import Path
+    output_dir = Path(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    # 1) データ結合
+    adatas = []
+    for i, path in enumerate(adata_paths):
+        a = sc.read_h5ad(path)
+        a.obs["batch"] = batch_labels[i] if batch_labels else f"batch_{i}"
+        adatas.append(a)
+
+    adata = ad.concat(adatas, join="inner")
+    adata.obs_names_make_unique()
+
+    # 2) 前処理
+    sc.pp.highly_variable_genes(
+        adata, n_top_genes=2000, batch_key="batch", flavor="seurat_v3"
+    )
+    adata = adata[:, adata.var["highly_variable"]].copy()
+
+    # 3) scVI 訓練
+    scvi_model = setup_scvi(adata, batch_key="batch")
+
+    # 4) SOLO ダブレット除去
+    solo_results = solo_doublet_detection(adata, scvi_model)
+    adata = adata[adata.obs["solo_doublet"] == "singlet"].copy()
+
+    # 5) 再訓練 (ダブレット除去後)
+    scvi_model = setup_scvi(adata, batch_key="batch")
+
+    # 6) scANVI アノテーション
+    if labels_key in adata.obs.columns:
+        scanvi_model = scanvi_annotation(adata, scvi_model, labels_key=labels_key)
+
+    # 7) UMAP & クラスタリング
+    scvi_integration(adata, scvi_model)
+
+    # 保存
+    adata.write(output_dir / "integrated.h5ad")
+    scvi_model.save(str(output_dir / "scvi_model"))
+
+    print(f"Pipeline complete: {len(adata)} cells integrated")
+    return adata, scvi_model
+```
+
+---
+
+## パイプライン統合
+
+```
+single-cell-genomics → scvi-integration → spatial-transcriptomics
+  (scRNA-seq QC)       (scVI/scANVI/totalVI)   (Visium/MERFISH)
+       │                       │                      ↓
+perturbation-analysis ────────┘               gene-expression
+  (Perturb-seq)          │                    (DEG/マーカー)
+                         ↓
+                  expression-comparison
+                  (Expression Atlas 比較)
+```
+
+## パイプライン出力
+
+| ファイル | 説明 | 次スキル |
+|---------|------|---------|
+| `results/integrated.h5ad` | 統合 AnnData | → spatial-transcriptomics |
+| `results/scvi_model/` | scVI 訓練済みモデル | → perturbation-analysis |
+| `results/de_results.csv` | 差次的発現結果 | → gene-expression |
+| `results/annotations.csv` | scANVI アノテーション | → expression-comparison |