@nahisaho/satori 0.12.0 → 0.14.0

package/src/.github/skills/scientific-regulatory-genomics/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: scientific-regulatory-genomics
+description: |
+  レギュラトリーゲノミクススキル。RegulomeDB バリアント制御機能スコア、
+  ReMap 転写因子結合マッピング、4D Nucleome (4DN) 三次元ゲノム構造
+  解析の統合パイプライン。
+---
+
+# Scientific Regulatory Genomics
+
+RegulomeDB / ReMap / 4D Nucleome を統合した
+レギュラトリーゲノミクス (制御領域バリアント解析) パイプラインを提供する。
+
+## When to Use
+
+- 非コード領域バリアントの制御機能を評価するとき
+- RegulomeDB で SNP の調節的影響をスコアリングするとき
+- ReMap で転写因子結合部位のマッピングを確認するとき
+- 4DN データから三次元ゲノム構造 (TAD/ループ) を解析するとき
+- GWAS ヒットの制御メカニズムを解明するとき
+
+---
+
+## Quick Start
+
+## 1. RegulomeDB バリアント制御スコア
+
+```python
+import requests
+import pandas as pd
+
+REGULOMEDB_API = "https://regulomedb.org/regulome-search"
+
+
+def score_regulome_variants(variants):
+    """
+    RegulomeDB — 非コード領域バリアントの制御機能スコアリング。
+
+    Parameters:
+        variants: list — バリアントリスト (rsID or chr:pos 形式)
+            e.g., ["rs12345", "chr1:109274570"]
+
+    ToolUniverse:
+        RegulomeDB_score_variant(variant=variant)
+    """
+    results = []
+    for variant in variants:
+        params = {"regions": variant, "genome": "GRCh38", "format": "json"}
+        resp = requests.get(REGULOMEDB_API, params=params)
+        if resp.status_code != 200:
+            results.append({"variant": variant, "score": None, "error": True})
+            continue
+
+        data = resp.json()
+        for hit in data.get("@graph", []):
+            results.append({
+                "variant": variant,
+                "regulome_score": hit.get("regulome_score", {}).get("ranking", ""),
+                "probability": hit.get("regulome_score", {}).get("probability", ""),
+                "chrom": hit.get("chrom", ""),
+                "start": hit.get("start", ""),
+                "end": hit.get("end", ""),
+                "dnase": hit.get("dnase", ""),
+                "proteins_binding": hit.get("proteins_binding", []),
+                "motifs": hit.get("motifs", []),
+                "eqtls": hit.get("eqtls", []),
+                "chromatin_state": hit.get("chromatin_state", {}),
+            })
+
+    df = pd.DataFrame(results)
+    if not df.empty and "regulome_score" in df.columns:
+        high_func = (df["regulome_score"].astype(str).str.match(r"^[12]")).sum()
+        print(f"RegulomeDB: {len(variants)} variants scored, "
+              f"{high_func} with high regulatory function (score 1-2)")
+    return df
+```
+
+## 2. ReMap 転写因子結合マッピング
+
+```python
+REMAP_API = "https://remap.univ-amu.fr/api/v1"
+
+
+def search_remap_binding(chrom, start, end, genome="hg38"):
+    """
+    ReMap — ゲノム領域の転写因子/コレギュレーター結合マッピング。
+
+    Parameters:
+        chrom: str — 染色体 (e.g., "chr1")
+        start: int — 開始座標
+        end: int — 終了座標
+        genome: str — ゲノムアセンブリ ("hg38", "hg19", "mm10")
+
+    ToolUniverse:
+        ReMap_search_peaks(chrom=chrom, start=start, end=end)
+        ReMap_get_tf_targets(tf_name=tf_name)
+    """
+    params = {
+        "chrom": chrom,
+        "start": start,
+        "end": end,
+        "genome": genome,
+    }
+    resp = requests.get(f"{REMAP_API}/peaks/search", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for peak in data.get("peaks", []):
+        results.append({
+            "tf_name": peak.get("tf_name", ""),
+            "biotype": peak.get("biotype", ""),
+            "cell_type": peak.get("cell_type", ""),
+            "experiment": peak.get("experiment_accession", ""),
+            "peak_start": peak.get("start", ""),
+            "peak_end": peak.get("end", ""),
+            "score": peak.get("score", ""),
+        })
+
+    df = pd.DataFrame(results)
+    unique_tfs = df["tf_name"].nunique() if not df.empty else 0
+    print(f"ReMap {chrom}:{start}-{end}: {len(df)} peaks, {unique_tfs} unique TFs")
+    return df
+
+
+def get_remap_tf_targets(tf_name, genome="hg38"):
+    """
+    ReMap — 特定転写因子の全結合部位取得。
+
+    Parameters:
+        tf_name: str — 転写因子名 (e.g., "TP53", "CTCF", "STAT3")
+    """
+    params = {"tf": tf_name, "genome": genome}
+    resp = requests.get(f"{REMAP_API}/peaks/tf", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for peak in data.get("peaks", [])[:1000]:  # Limit for large TFs
+        results.append({
+            "chrom": peak.get("chrom", ""),
+            "start": peak.get("start", ""),
+            "end": peak.get("end", ""),
+            "cell_type": peak.get("cell_type", ""),
+            "score": peak.get("score", ""),
+        })
+
+    df = pd.DataFrame(results)
+    print(f"ReMap TF '{tf_name}': {len(df)} binding sites")
+    return df
+```
+
+## 3. 4D Nucleome (4DN) 三次元ゲノム構造
+
+```python
+FOURDN_API = "https://data.4dnucleome.org"
+
+
+def search_4dn_experiments(query, experiment_type=None):
+    """
+    4D Nucleome ポータル — 三次元ゲノム実験データ検索。
+
+    Parameters:
+        query: str — 検索クエリ (細胞株名、タンパク質名等)
+        experiment_type: str — 実験タイプ ("in situ Hi-C", "SPRITE", "GAM")
+
+    ToolUniverse:
+        FourDN_search_experiments(query=query)
+    """
+    params = {
+        "searchTerm": query,
+        "type": "ExperimentSetReplicate",
+        "format": "json",
+    }
+    if experiment_type:
+        params["experiment_type.display_title"] = experiment_type
+
+    resp = requests.get(f"{FOURDN_API}/search/", params=params)
+    resp.raise_for_status()
+    data = resp.json()
+
+    results = []
+    for item in data.get("@graph", []):
+        results.append({
+            "accession": item.get("accession", ""),
+            "title": item.get("display_title", ""),
+            "experiment_type": item.get("experiment_type", {}).get("display_title", ""),
+            "biosource": item.get("biosource_summary", ""),
+            "lab": item.get("lab", {}).get("display_title", ""),
+            "status": item.get("status", ""),
+        })
+
+    df = pd.DataFrame(results)
+    print(f"4DN search '{query}': {len(df)} experiment sets")
+    return df
+```
+
+## 4. 制御バリアント統合解析パイプライン
+
+```python
+def regulatory_variant_pipeline(variants, genome="hg38"):
+    """
+    制御領域バリアント統合解析。
+
+    Parameters:
+        variants: list — バリアントリスト (rsID or chr:pos)
+    """
+    print("=" * 60)
+    print("Regulatory Variant Analysis Pipeline")
+    print("=" * 60)
+
+    # Step 1: RegulomeDB scoring
+    print("\n[1/3] RegulomeDB scoring...")
+    regulome_df = score_regulome_variants(variants)
+
+    # Step 2: ReMap TF binding for high-scoring variants
+    print("\n[2/3] ReMap TF binding analysis...")
+    remap_results = {}
+    for _, row in regulome_df.iterrows():
+        if row.get("chrom") and row.get("start"):
+            chrom = row["chrom"]
+            start = int(row["start"]) - 500
+            end = int(row["end"]) + 500
+            try:
+                remap_df = search_remap_binding(chrom, start, end, genome)
+                remap_results[row["variant"]] = remap_df
+            except Exception as e:
+                print(f"  ReMap error for {row['variant']}: {e}")
+
+    # Step 3: Summary
+    print("\n[3/3] Summary")
+    summary = {
+        "total_variants": len(variants),
+        "regulome_scored": len(regulome_df),
+        "high_regulatory": (
+            regulome_df["regulome_score"].astype(str).str.match(r"^[12]")
+        ).sum() if "regulome_score" in regulome_df.columns else 0,
+        "remap_annotated": len(remap_results),
+    }
+    print(f"  Total: {summary['total_variants']}, "
+          f"High regulatory: {summary['high_regulatory']}, "
+          f"ReMap annotated: {summary['remap_annotated']}")
+
+    return {"regulome": regulome_df, "remap": remap_results, "summary": summary}
+```
+
+---
+
+## 利用可能ツール
+
+| ToolUniverse カテゴリ | 主なツール |
+|---|---|
+| `regulomedb` | `RegulomeDB_score_variant` |
+| `remap` | `ReMap_search_peaks`, `ReMap_get_tf_targets` |
+| `fourdn_portal` | `FourDN_search_experiments` |
+
+## パイプライン出力
+
+| 出力ファイル | 説明 | 連携先スキル |
+|---|---|---|
+| `results/regulome_scores.csv` | バリアント制御スコア | → variant-interpretation, variant-effect-prediction |
+| `results/remap_binding.csv` | TF 結合マッピング | → epigenomics-chromatin, disease-research |
+| `results/4dn_contacts.json` | 3D ゲノム構造データ | → single-cell-genomics, epigenomics-chromatin |
+
+## パイプライン統合
+
+```
+variant-interpretation ──→ regulatory-genomics ──→ epigenomics-chromatin
+  (ACMG/AMP)               (RegulomeDB/ReMap/4DN)  (ChIP-seq/ATAC)
+                                    │
+                                    ├──→ disease-research (GWAS enhancer)
+                                    ├──→ gene-expression (eQTL/制御)
+                                    └──→ noncoding-rna (ncRNA 制御)
+```

package/src/.github/skills/scientific-reinforcement-learning/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: scientific-reinforcement-learning
+description: |
+  強化学習スキル。Stable-Baselines3 による RL エージェント訓練、
+  Gymnasium 環境構築、PufferLib 大規模マルチエージェント、
+  科学応用 (分子生成・実験最適化・ロボット制御) パイプライン。
+---
+
+# Scientific Reinforcement Learning
+
+Stable-Baselines3 / PufferLib / Gymnasium を活用した
+強化学習パイプラインを提供する。
+
+## When to Use
+
+- RL エージェントを訓練・評価するとき
+- カスタム Gymnasium 環境を構築するとき
+- 分子設計・創薬に RL を適用するとき
+- 実験パラメータの逐次最適化に RL を使うとき
+- マルチエージェント強化学習を実行するとき
+- ロボティクス・ラボオートメーションの制御方策を学習するとき
+
+---
+
+## Quick Start
+
+## 1. Stable-Baselines3 基本訓練
+
+```python
+import numpy as np
+import gymnasium as gym
+from stable_baselines3 import PPO, SAC, A2C, DQN
+from stable_baselines3.common.evaluation import evaluate_policy
+from stable_baselines3.common.vec_env import DummyVecEnv, SubprocVecEnv
+from stable_baselines3.common.callbacks import EvalCallback, CheckpointCallback
+
+
+def train_rl_agent(env_id, algorithm="PPO", total_timesteps=100_000,
+                   n_envs=4, hyperparams=None):
+    """
+    Stable-Baselines3 RL エージェント訓練。
+
+    Parameters:
+        env_id: str — Gymnasium 環境 ID (e.g., "CartPole-v1", "LunarLander-v3")
+        algorithm: str — "PPO", "SAC", "A2C", "DQN"
+        total_timesteps: int — 総訓練ステップ数
+        n_envs: int — 並列環境数
+        hyperparams: dict — ハイパーパラメータ override
+
+    K-Dense: stable-baselines3 — RL training framework
+    """
+    algo_map = {"PPO": PPO, "SAC": SAC, "A2C": A2C, "DQN": DQN}
+    AlgoClass = algo_map.get(algorithm, PPO)
+
+    # Vectorized environments
+    env = DummyVecEnv([lambda: gym.make(env_id) for _ in range(n_envs)])
+
+    # Default hyperparams per algorithm
+    default_params = {
+        "PPO": {"learning_rate": 3e-4, "n_steps": 2048, "batch_size": 64},
+        "SAC": {"learning_rate": 3e-4, "buffer_size": 1_000_000},
+        "A2C": {"learning_rate": 7e-4, "n_steps": 5},
+        "DQN": {"learning_rate": 1e-4, "buffer_size": 100_000},
+    }
+    params = default_params.get(algorithm, {})
+    if hyperparams:
+        params.update(hyperparams)
+
+    model = AlgoClass("MlpPolicy", env, verbose=1, **params)
+
+    # Callbacks
+    eval_env = gym.make(env_id)
+    eval_callback = EvalCallback(
+        eval_env, best_model_save_path="./models/best/",
+        log_path="./logs/", eval_freq=10_000,
+    )
+    checkpoint_callback = CheckpointCallback(
+        save_freq=25_000, save_path="./models/checkpoints/",
+    )
+
+    model.learn(
+        total_timesteps=total_timesteps,
+        callback=[eval_callback, checkpoint_callback],
+    )
+
+    # Evaluation
+    mean_reward, std_reward = evaluate_policy(model, eval_env, n_eval_episodes=20)
+    print(f"RL Training ({algorithm} on {env_id}): "
+          f"reward = {mean_reward:.2f} ± {std_reward:.2f}")
+
+    return model, {"mean_reward": mean_reward, "std_reward": std_reward}
+```
+
+## 2. カスタム Gymnasium 環境
+
+```python
+class MoleculeDesignEnv(gym.Env):
+    """
+    分子設計用カスタム RL 環境。
+
+    状態: 分子フィンガープリント (Morgan FP)
+    行動: 原子/結合の追加・削除・変更
+    報酬: 薬物らしさスコア (QED) + 結合親和性予測
+    """
+    metadata = {"render_modes": ["human"]}
+
+    def __init__(self, max_atoms=50, target_property="qed"):
+        super().__init__()
+        self.max_atoms = max_atoms
+        self.target_property = target_property
+
+        # Action space: discrete (add atom types, add bonds, remove)
+        self.action_space = gym.spaces.Discrete(10)
+
+        # Observation space: molecular fingerprint
+        self.observation_space = gym.spaces.Box(
+            low=0, high=1, shape=(2048,), dtype=np.float32,
+        )
+
+        self.current_mol = None
+        self.step_count = 0
+
+    def reset(self, seed=None, options=None):
+        super().reset(seed=seed)
+        self.current_mol = None  # Start from scratch
+        self.step_count = 0
+        obs = np.zeros(2048, dtype=np.float32)
+        return obs, {}
+
+    def step(self, action):
+        self.step_count += 1
+
+        # Apply action to modify molecule
+        reward = self._calculate_reward()
+        terminated = self.step_count >= self.max_atoms
+        truncated = False
+        obs = self._get_observation()
+
+        return obs, reward, terminated, truncated, {}
+
+    def _calculate_reward(self):
+        """Calculate reward based on molecular properties."""
+        if self.current_mol is None:
+            return 0.0
+        # Placeholder: QED score
+        return np.random.uniform(0, 1)
+
+    def _get_observation(self):
+        return np.zeros(2048, dtype=np.float32)
+
+
+def train_molecule_designer(total_timesteps=50_000):
+    """分子設計 RL エージェント訓練。"""
+    env = MoleculeDesignEnv()
+    model = PPO("MlpPolicy", env, verbose=1, learning_rate=1e-4)
+    model.learn(total_timesteps=total_timesteps)
+
+    mean_reward, std_reward = evaluate_policy(model, env, n_eval_episodes=10)
+    print(f"Molecule Designer: reward = {mean_reward:.2f} ± {std_reward:.2f}")
+    return model
+```
+
+## 3. PufferLib 大規模マルチエージェント
+
+```python
+def setup_pufferlib_training(env_name, num_agents=8, algorithm="PPO"):
+    """
+    PufferLib マルチエージェント RL 設定。
+
+    Parameters:
+        env_name: str — PufferLib 対応環境
+        num_agents: int — エージェント数
+        algorithm: str — "PPO", "IMPALA"
+
+    K-Dense: pufferlib — Scalable multi-agent RL
+    """
+    try:
+        import pufferlib
+        import pufferlib.environments
+
+        config = {
+            "env": env_name,
+            "num_agents": num_agents,
+            "algorithm": algorithm,
+            "total_timesteps": 1_000_000,
+            "batch_size": 256,
+            "learning_rate": 2.5e-4,
+            "num_envs": 16,
+            "num_steps": 128,
+        }
+        print(f"PufferLib config: {config}")
+        return config
+
+    except ImportError:
+        print("PufferLib not installed. Install with: pip install pufferlib")
+        return None
+```
+
+## 4. 実験パラメータ逐次最適化
+
+```python
+def rl_experiment_optimizer(parameter_ranges, objective_fn,
+                            total_episodes=100, algorithm="PPO"):
+    """
+    RL による実験パラメータ逐次最適化。
+
+    Parameters:
+        parameter_ranges: dict — {param_name: (min, max)}
+        objective_fn: callable — 目的関数 (params → score)
+        total_episodes: int — 最適化エピソード数
+    """
+    n_params = len(parameter_ranges)
+    param_names = list(parameter_ranges.keys())
+
+    class ExperimentEnv(gym.Env):
+        def __init__(self):
+            super().__init__()
+            self.action_space = gym.spaces.Box(
+                low=-1, high=1, shape=(n_params,), dtype=np.float32,
+            )
+            self.observation_space = gym.spaces.Box(
+                low=-np.inf, high=np.inf,
+                shape=(n_params + 1,), dtype=np.float32,
+            )
+            self.best_score = -np.inf
+            self.history = []
+
+        def reset(self, seed=None, options=None):
+            super().reset(seed=seed)
+            self.current_params = np.zeros(n_params, dtype=np.float32)
+            return np.zeros(n_params + 1, dtype=np.float32), {}
+
+        def step(self, action):
+            # Scale action to parameter ranges
+            params = {}
+            for i, name in enumerate(param_names):
+                lo, hi = parameter_ranges[name]
+                params[name] = lo + (action[i] + 1) / 2 * (hi - lo)
+
+            score = objective_fn(params)
+            self.history.append({"params": params, "score": score})
+
+            if score > self.best_score:
+                self.best_score = score
+
+            obs = np.append(action, [score]).astype(np.float32)
+            return obs, score, False, False, {}
+
+    env = ExperimentEnv()
+    model = SAC("MlpPolicy", env, verbose=0) if algorithm == "SAC" else PPO("MlpPolicy", env, verbose=0)
+    model.learn(total_timesteps=total_episodes)
+
+    best_idx = max(range(len(env.history)), key=lambda i: env.history[i]["score"])
+    best = env.history[best_idx]
+    print(f"RL Optimization: best score = {best['score']:.4f}")
+    print(f"  Best params: {best['params']}")
+    return best, env.history
+```
+
+---
+
+## パイプライン出力
+
+| 出力ファイル | 説明 | 連携先スキル |
+|---|---|---|
+| `models/rl_model.zip` | 訓練済み RL モデル | → deep-learning (モデル統合) |
+| `results/rl_training_log.json` | 訓練曲線・メトリクス | → publication-figures |
+| `results/rl_optimization.json` | 最適化パラメータ | → doe, process-optimization |
+| `figures/rl_reward_curve.png` | 報酬曲線 | → presentation-design |
+
+## パイプライン統合
+
+```
+doe ──→ reinforcement-learning ──→ lab-automation
+  (実験計画)  (逐次最適化)          (ロボット制御)
+                    │
+                    ├──→ drug-target-profiling (分子設計 RL)
+                    ├──→ protein-design (構造最適化 RL)
+                    └──→ deep-learning (DRL パイプライン)
+```