@nahisaho/satori 0.22.0 → 0.24.0

package/src/.github/skills/scientific-network-visualization/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: scientific-network-visualization
+description: |
+  ネットワーク解析・可視化スキル。NetworkX グラフ構築・
+  コミュニティ検出 (Louvain/Leiden)・中心性指標・
+  PyVis インタラクティブ・ネットワーク統計量・動的ネットワーク。
+---
+
+# Scientific Network Visualization
+
+ネットワーク/グラフデータの解析・コミュニティ検出・
+インタラクティブ可視化パイプラインを提供する。
+
+## When to Use
+
+- 関連性・相互作用のネットワーク構造を解析するとき
+- コミュニティ (クラスタ) を検出するとき
+- 中心性指標でハブ・ブリッジノードを特定するとき
+- PyVis でインタラクティブなネットワーク図を作成するとき
+- 相関行列からネットワークを構築するとき
+- 時間発展するネットワークを解析するとき
+
+> **Note**: タンパク質 PPI ネットワークは `scientific-protein-interaction-network` を参照。
+
+---
+
+## Quick Start
+
+## 1. ネットワーク構築・基本統計
+
+```python
+import numpy as np
+import pandas as pd
+import networkx as nx
+
+
+def build_network_from_edgelist(edges_df, source_col, target_col,
+                                weight_col=None, directed=False):
+    """
+    エッジリストからネットワーク構築 + 基本統計。
+
+    Parameters:
+        edges_df: pd.DataFrame — エッジリスト
+        source_col: str — ソースノードカラム
+        target_col: str — ターゲットノードカラム
+        weight_col: str | None — 重みカラム
+        directed: bool — 有向グラフ
+    """
+    if directed:
+        G = nx.DiGraph()
+    else:
+        G = nx.Graph()
+
+    for _, row in edges_df.iterrows():
+        kwargs = {}
+        if weight_col and pd.notna(row[weight_col]):
+            kwargs["weight"] = row[weight_col]
+        G.add_edge(row[source_col], row[target_col], **kwargs)
+
+    stats = {
+        "n_nodes": G.number_of_nodes(),
+        "n_edges": G.number_of_edges(),
+        "density": nx.density(G),
+        "is_connected": nx.is_connected(G) if not directed else nx.is_weakly_connected(G),
+        "n_components": nx.number_connected_components(G) if not directed
+                        else nx.number_weakly_connected_components(G),
+        "avg_degree": np.mean([d for _, d in G.degree()]),
+        "avg_clustering": nx.average_clustering(G) if not directed else None,
+    }
+
+    if stats["is_connected"] and not directed:
+        stats["avg_path_length"] = nx.average_shortest_path_length(G)
+        stats["diameter"] = nx.diameter(G)
+
+    print(f"Network: {stats['n_nodes']} nodes, {stats['n_edges']} edges, "
+          f"density={stats['density']:.4f}")
+    return G, stats
+
+
+def build_network_from_correlation(df, threshold=0.5,
+                                    method="pearson"):
+    """
+    相関行列からネットワーク構築。
+
+    Parameters:
+        df: pd.DataFrame — 数値データ
+        threshold: float — 相関閾値 (|r| ≥ threshold でエッジ)
+        method: str — "pearson" / "spearman"
+    """
+    corr = df.corr(method=method)
+    G = nx.Graph()
+
+    for i, col_i in enumerate(corr.columns):
+        G.add_node(col_i)
+        for j, col_j in enumerate(corr.columns):
+            if i < j and abs(corr.iloc[i, j]) >= threshold:
+                G.add_edge(col_i, col_j,
+                           weight=abs(corr.iloc[i, j]),
+                           correlation=corr.iloc[i, j])
+
+    print(f"Correlation Network (|r|≥{threshold}): "
+          f"{G.number_of_nodes()} nodes, {G.number_of_edges()} edges")
+    return G
+```
+
+## 2. コミュニティ検出
+
+```python
+def detect_communities(G, method="louvain", resolution=1.0):
+    """
+    コミュニティ検出。
+
+    Parameters:
+        G: nx.Graph — ネットワーク
+        method: str — "louvain" / "leiden" / "label_propagation" / "girvan_newman"
+        resolution: float — 解像度パラメータ (Louvain/Leiden)
+    """
+    import matplotlib.pyplot as plt
+
+    if method == "louvain":
+        communities = nx.community.louvain_communities(
+            G, resolution=resolution, seed=42)
+    elif method == "leiden":
+        try:
+            import leidenalg
+            import igraph as ig
+            ig_graph = ig.Graph.from_networkx(G)
+            partition = leidenalg.find_partition(
+                ig_graph, leidenalg.RBConfigurationVertexPartition,
+                resolution_parameter=resolution, seed=42)
+            communities = [set(ig_graph.vs[c]["_nx_name"] for c in comm)
+                           for comm in partition]
+        except ImportError:
+            communities = nx.community.louvain_communities(
+                G, resolution=resolution, seed=42)
+    elif method == "label_propagation":
+        communities = list(nx.community.label_propagation_communities(G))
+    elif method == "girvan_newman":
+        comp = nx.community.girvan_newman(G)
+        communities = next(comp)  # 最初の分割
+
+    # ノードにコミュニティ ID 割当
+    node_community = {}
+    for i, comm in enumerate(communities):
+        for node in comm:
+            node_community[node] = i
+    nx.set_node_attributes(G, node_community, "community")
+
+    # モジュラリティ
+    modularity = nx.community.modularity(G, communities)
+
+    # 可視化
+    fig, ax = plt.subplots(figsize=(12, 10))
+    pos = nx.spring_layout(G, k=1/np.sqrt(G.number_of_nodes()), seed=42)
+    colors = [node_community.get(n, 0) for n in G.nodes()]
+
+    nx.draw_networkx(G, pos, ax=ax, node_color=colors,
+                     cmap=plt.cm.Set3, node_size=100,
+                     font_size=6, edge_color="gray", alpha=0.7,
+                     with_labels=G.number_of_nodes() < 100)
+    ax.set_title(f"Communities ({method}): {len(communities)} clusters, "
+                 f"Q={modularity:.4f}")
+    plt.tight_layout()
+
+    path = "network_communities.png"
+    plt.savefig(path, dpi=150, bbox_inches="tight")
+    plt.close()
+
+    print(f"Communities ({method}): {len(communities)} clusters, "
+          f"modularity={modularity:.4f}")
+    return {"communities": communities, "modularity": modularity,
+            "node_community": node_community, "fig": path}
+```
+
+## 3. 中心性指標
+
+```python
+def centrality_analysis(G, top_n=20):
+    """
+    多面的中心性解析。
+
+    Parameters:
+        G: nx.Graph — ネットワーク
+        top_n: int — 上位ノード数
+    """
+    centralities = {
+        "degree": nx.degree_centrality(G),
+        "betweenness": nx.betweenness_centrality(G),
+        "closeness": nx.closeness_centrality(G),
+        "eigenvector": nx.eigenvector_centrality(G, max_iter=1000),
+        "pagerank": nx.pagerank(G)
+    }
+
+    # DataFrame 化
+    cent_df = pd.DataFrame(centralities)
+    cent_df.index.name = "node"
+
+    # ランキング
+    rankings = {}
+    for metric in centralities:
+        top = cent_df[metric].nlargest(top_n)
+        rankings[metric] = top.index.tolist()
+
+    # ハブスコア (複数指標の統合)
+    for metric in centralities:
+        cent_df[f"{metric}_rank"] = cent_df[metric].rank(ascending=False)
+    cent_df["hub_score"] = cent_df[[f"{m}_rank" for m in centralities]].mean(axis=1)
+    cent_df = cent_df.sort_values("hub_score")
+
+    print(f"Centrality: {len(G.nodes())} nodes analyzed")
+    print(f"  Top hubs: {cent_df.head(5).index.tolist()}")
+    return {"centrality_df": cent_df, "rankings": rankings}
+```
+
+## 4. PyVis インタラクティブ可視化
+
+```python
+def interactive_network(G, output="network_interactive.html",
+                        height="700px", width="100%"):
+    """
+    PyVis インタラクティブネットワーク図。
+
+    Parameters:
+        G: nx.Graph — ネットワーク
+        output: str — 出力 HTML パス
+        height: str — 高さ
+        width: str — 幅
+    """
+    from pyvis.network import Network
+
+    nt = Network(height=height, width=width, notebook=False,
+                 bgcolor="#ffffff", font_color="black")
+
+    # コミュニティカラーリング
+    community_map = nx.get_node_attributes(G, "community")
+    colors = ["#e41a1c", "#377eb8", "#4daf4a", "#984ea3",
+              "#ff7f00", "#ffff33", "#a65628", "#f781bf"]
+
+    for node in G.nodes():
+        comm = community_map.get(node, 0)
+        degree = G.degree(node)
+        nt.add_node(str(node), label=str(node),
+                    color=colors[comm % len(colors)],
+                    size=max(5, min(degree * 3, 50)),
+                    title=f"{node}\nDegree: {degree}\nCommunity: {comm}")
+
+    for u, v, data in G.edges(data=True):
+        weight = data.get("weight", 1)
+        nt.add_edge(str(u), str(v), value=weight)
+
+    nt.toggle_physics(True)
+    nt.show_buttons(filter_=["physics"])
+    nt.save_graph(output)
+
+    print(f"Interactive Network → {output} "
+          f"({G.number_of_nodes()} nodes, {G.number_of_edges()} edges)")
+    return output
+```
+
+---
+
+## パイプライン統合
+
+```
+eda-correlation → network-visualization → advanced-visualization
+  (相関解析)        (ネットワーク解析)       (高度可視化)
+       │                   │                      ↓
+ graph-neural-networks ───┘          interactive-dashboard
+  (GNN)                                (ダッシュボード)
+```
+
+## パイプライン出力
+
+| ファイル | 説明 | 次スキル |
+|---------|------|---------|
+| `network_communities.png` | コミュニティ構造 | → presentation |
+| `centrality_analysis.csv` | 中心性指標 | → feature-importance |
+| `network_interactive.html` | PyVis 図 | → dashboard |

package/src/.github/skills/scientific-reproducible-reporting/SKILL.md

@@ -0,0 +1,330 @@
+---
+name: scientific-reproducible-reporting
+description: |
+  再現可能レポーティングスキル。Quarto 科学文書・
+  Jupyter Book 多章構成・Papermill パラメトリック実行・
+  nbconvert 自動変換・Sphinx-Gallery コード例ドキュメント。
+---
+
+# Scientific Reproducible Reporting
+
+再現可能な科学レポート・文書生成パイプラインを提供し、
+コード → 実行 → 文書化の自動化を実現する。
+
+## When to Use
+
+- Quarto で再現可能な科学文書を作成するとき
+- Jupyter Book で多章構成の文書を構築するとき
+- Papermill でパラメトリック実行を自動化するとき
+- nbconvert でノートブックを各種形式に変換するとき
+- CI/CD で解析レポートを自動生成するとき
+- 複数パラメータセットで解析を繰り返し実行するとき
+
+---
+
+## Quick Start
+
+## 1. Quarto 科学文書テンプレート
+
+```python
+import os
+
+
+def generate_quarto_document(title="Scientific Analysis Report",
+                             author="SATORI",
+                             format_type="html",
+                             output_dir="quarto_project"):
+    """
+    Quarto 科学文書テンプレート生成。
+
+    Parameters:
+        title: str — ドキュメントタイトル
+        author: str — 著者名
+        format_type: str — "html" / "pdf" / "docx" / "revealjs"
+        output_dir: str — 出力ディレクトリ
+    """
+    os.makedirs(output_dir, exist_ok=True)
+
+    # _quarto.yml
+    quarto_config = f"""project:
+  type: default
+  output-dir: _output
+
+format:
+  {format_type}:
+    toc: true
+    toc-depth: 3
+    number-sections: true
+    code-fold: true
+    code-tools: true
+    theme: cosmo
+
+execute:
+  echo: true
+  warning: false
+  cache: true
+
+bibliography: references.bib
+csl: nature.csl
+"""
+
+    # メインドキュメント
+    main_qmd = f"""---
+title: "{title}"
+author: "{author}"
+date: today
+format:
+  {format_type}:
+    code-fold: true
+    code-tools: true
+jupyter: python3
+---
+
+## はじめに
+
+このレポートは SATORI スキルを用いた再現可能な科学解析文書です。
+
+```{{python}}
+#| label: setup
+#| echo: false
+
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import warnings
+warnings.filterwarnings("ignore")
+
+# パラメータ (Papermill 互換)
+n_samples = 1000
+random_seed = 42
+```
+
+## データ概要
+
+```{{python}}
+#| label: data-summary
+#| tbl-cap: "データセット概要"
+
+np.random.seed(random_seed)
+df = pd.DataFrame({{
+    "x": np.random.randn(n_samples),
+    "y": np.random.randn(n_samples),
+    "group": np.random.choice(["A", "B", "C"], n_samples)
+}})
+df.describe()
+```
+
+## 可視化
+
+```{{python}}
+#| label: fig-scatter
+#| fig-cap: "散布図"
+
+fig, ax = plt.subplots(figsize=(8, 6))
+for g, sub in df.groupby("group"):
+    ax.scatter(sub["x"], sub["y"], label=g, alpha=0.6, s=20)
+ax.legend()
+ax.set_xlabel("X")
+ax.set_ylabel("Y")
+plt.show()
+```
+
+## 結論
+
+解析結果のサマリーを記載する。
+
+## References
+"""
+
+    # references.bib (空テンプレート)
+    bib_template = """@article{example2024,
+  title={Example Reference},
+  author={Author, A.},
+  journal={Journal},
+  year={2024}
+}
+"""
+
+    with open(os.path.join(output_dir, "_quarto.yml"), "w") as f:
+        f.write(quarto_config)
+    with open(os.path.join(output_dir, "report.qmd"), "w") as f:
+        f.write(main_qmd)
+    with open(os.path.join(output_dir, "references.bib"), "w") as f:
+        f.write(bib_template)
+
+    print(f"Quarto project → {output_dir}/")
+    print(f"  Build: cd {output_dir} && quarto render report.qmd")
+    return output_dir
+```
+
+## 2. Papermill パラメトリック実行
+
+```python
+def papermill_parametric_run(template_notebook, output_dir,
+                             parameter_sets, kernel="python3"):
+    """
+    Papermill パラメトリック実行 — 複数パラメータセットで自動実行。
+
+    Parameters:
+        template_notebook: str — テンプレートノートブックパス
+        output_dir: str — 出力ディレクトリ
+        parameter_sets: list[dict] — パラメータセットのリスト
+        kernel: str — カーネル名
+    """
+    import papermill as pm
+
+    os.makedirs(output_dir, exist_ok=True)
+    results = []
+
+    for i, params in enumerate(parameter_sets):
+        output_path = os.path.join(output_dir, f"run_{i:03d}.ipynb")
+        try:
+            pm.execute_notebook(
+                template_notebook,
+                output_path,
+                parameters=params,
+                kernel_name=kernel)
+            results.append({
+                "run": i, "params": params,
+                "output": output_path, "status": "success"})
+        except Exception as e:
+            results.append({
+                "run": i, "params": params,
+                "output": output_path, "status": f"error: {str(e)}"})
+
+    import pandas as pd
+    results_df = pd.DataFrame(results)
+    n_success = (results_df["status"] == "success").sum()
+    print(f"Papermill: {n_success}/{len(parameter_sets)} runs succeeded")
+    return results_df
+```
+
+## 3. Jupyter Book 多章構成
+
+```python
+def generate_jupyter_book(title="Scientific Analysis Book",
+                          chapters=None,
+                          output_dir="jupyter_book"):
+    """
+    Jupyter Book プロジェクトテンプレート生成。
+
+    Parameters:
+        title: str — 書籍タイトル
+        chapters: list[dict] | None — 章情報 [{"title": ..., "file": ...}]
+        output_dir: str — 出力ディレクトリ
+    """
+    os.makedirs(output_dir, exist_ok=True)
+
+    if chapters is None:
+        chapters = [
+            {"title": "Introduction", "file": "intro"},
+            {"title": "Data Loading", "file": "ch01_data"},
+            {"title": "Exploratory Analysis", "file": "ch02_eda"},
+            {"title": "Modeling", "file": "ch03_model"},
+            {"title": "Results", "file": "ch04_results"},
+        ]
+
+    # _config.yml
+    config = f"""title: "{title}"
+author: SATORI
+execute:
+  execute_notebooks: auto
+  timeout: 600
+repository:
+  url: ""
+launch_buttons:
+  binderhub_url: ""
+sphinx:
+  extra_extensions:
+    - sphinx_proof
+"""
+
+    # _toc.yml
+    toc_entries = "\n".join(
+        [f"  - file: {ch['file']}" for ch in chapters])
+    toc = f"""format: jb-book
+root: intro
+chapters:
+{toc_entries}
+"""
+
+    with open(os.path.join(output_dir, "_config.yml"), "w") as f:
+        f.write(config)
+    with open(os.path.join(output_dir, "_toc.yml"), "w") as f:
+        f.write(toc)
+
+    # 各章テンプレート
+    for ch in chapters:
+        filepath = os.path.join(output_dir, f"{ch['file']}.md")
+        if not os.path.exists(filepath):
+            content = f"# {ch['title']}\n\nThis chapter covers {ch['title'].lower()}.\n"
+            with open(filepath, "w") as f:
+                f.write(content)
+
+    print(f"Jupyter Book → {output_dir}/")
+    print(f"  Build: jupyter-book build {output_dir}")
+    return output_dir
+```
+
+## 4. nbconvert 自動変換
+
+```python
+def batch_convert_notebooks(notebook_dir, output_format="html",
+                            output_dir=None, execute=True):
+    """
+    ノートブック一括変換。
+
+    Parameters:
+        notebook_dir: str — ノートブックディレクトリ
+        output_format: str — "html" / "pdf" / "markdown" / "script"
+        output_dir: str | None — 出力先 (None=同ディレクトリ)
+        execute: bool — 実行後に変換
+    """
+    import subprocess
+    import glob
+
+    notebooks = sorted(glob.glob(os.path.join(notebook_dir, "*.ipynb")))
+    if output_dir:
+        os.makedirs(output_dir, exist_ok=True)
+
+    results = []
+    for nb_path in notebooks:
+        cmd = ["jupyter", "nbconvert", f"--to={output_format}"]
+        if execute:
+            cmd.append("--execute")
+        if output_dir:
+            cmd.extend(["--output-dir", output_dir])
+        cmd.append(nb_path)
+
+        try:
+            subprocess.run(cmd, check=True, capture_output=True, text=True)
+            results.append({"notebook": nb_path, "status": "success"})
+        except subprocess.CalledProcessError as e:
+            results.append({"notebook": nb_path, "status": f"error: {e.stderr[:100]}"})
+
+    import pandas as pd
+    results_df = pd.DataFrame(results)
+    n_ok = (results_df["status"] == "success").sum()
+    print(f"nbconvert ({output_format}): {n_ok}/{len(notebooks)} converted")
+    return results_df
+```
+
+---
+
+## パイプライン統合
+
+```
+[解析完了] → reproducible-reporting → presentation-design
+              (レポート自動生成)         (プレゼン作成)
+                     │                        ↓
+            interactive-dashboard      academic-writing
+              (ダッシュボード)           (論文執筆)
+```
+
+## パイプライン出力
+
+| ファイル | 説明 | 次スキル |
+|---------|------|---------|
+| `quarto_project/` | Quarto プロジェクト | → quarto render |
+| `papermill_runs/` | パラメトリック実行結果 | → 集計 |
+| `jupyter_book/` | Jupyter Book プロジェクト | → jb build |