SuperAPI AI Directory

scientific-pipeline-scaffold

General & other

View repository

Updated 10-15 21:03

About this skill

Scientific Pipeline Scaffold

A skill that integrates the "scaffold" pattern common to all Exp-01 through 13. Apply it first when launching a new experiment pipeline to ensure reproducibility, readability, and structure.

When to Use

  • When launching a script for a new analysis experiment
  • When building a reproducible experiment pipeline
  • When you want to export analysis results as a JSON summary
  • When you want to automatically generate an overview dashboard figure

Quick Start

1. Script header template

#!/usr/bin/env python3
"""
Exp-XX: [実験タイトル]
Scientific Skills Series

Description:
    [1-2行の概要]

Author: [名前]
Date: [YYYY-MM-DD]
"""

import warnings
warnings.filterwarnings("ignore")

import matplotlib
matplotlib.use("Agg")  # headless 環境対応

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
import seaborn as sns
from pathlib import Path
import json
import time

# === 再現性設定 ===
SEED = 42
np.random.seed(SEED)

# === ディレクトリ構造 ===
BASE_DIR = Path(__file__).resolve().parent
DATA_DIR = BASE_DIR / "data"
FIG_DIR = BASE_DIR / "figures"
RESULTS_DIR = BASE_DIR / "results"

for d in [DATA_DIR, FIG_DIR, RESULTS_DIR]:
    d.mkdir(parents=True, exist_ok=True)

# === 出版品質スタイル ===
plt.rcParams.update({
    "font.family": "sans-serif",
    "font.sans-serif": ["Arial", "Helvetica", "DejaVu Sans"],
    "font.size": 10,
    "axes.titlesize": 12,
    "axes.labelsize": 11,
    "axes.spines.top": False,
    "axes.spines.right": False,
    "savefig.dpi": 300,
    "savefig.bbox": "tight",
    "figure.facecolor": "white",
})

2. Main function template

def main():
    """メインパイプライン実行関数。"""
    start_time = time.time()
    print("=" * 60)
    print("Exp-XX: [実験タイトル]")
    print("=" * 60)

    # ──── Step 0: 仮説・ワークフロー定義の保存 ────
    print("\n[Step 0] 仮説・ワークフロー定義の保存...")
    # → scientific-hypothesis-pipeline スキル参照
    # save_hypothesis_markdown(HYPOTHESIS)
    # save_hypothesis_json(HYPOTHESIS)
    # save_workflow_design(HYPOTHESIS, workflow_steps)
    # save_workflow_json(HYPOTHESIS, workflow_steps)

    # ──── Step 1: データ読み込み / 生成 ────
    print("\n[Step 1] データ読み込み...")
    # df = pd.read_csv(DATA_DIR / "dataset.csv")
    # df = generate_dataset()
    # df.to_csv(DATA_DIR / "dataset.csv", index=False)

    # ──── Step 2: EDA ────
    print("\n[Step 2] 探索的データ解析...")
    # → scientific-eda-correlation スキル参照

    # ──── Step 3: 前処理 ────
    print("\n[Step 3] 前処理...")
    # → scientific-data-preprocessing スキル参照

    # ──── Step 4: モデル学習 ────
    print("\n[Step 4] モデル学習...")
    # → scientific-ml-regression / ml-classification スキル参照

    # ──── Step 5: 可視化 ────
    print("\n[Step 5] 可視化...")
    # → scientific-publication-figures スキル参照

    # ──── Step 6: 仮説判定 ────
    print("\n[Step 6] 仮説判定...")
    # → scientific-hypothesis-pipeline スキル参照
    # hypothesis_verdict = evaluate_hypothesis(result, HYPOTHESIS)

    # ──── Step 7: サマリー ────
    elapsed = time.time() - start_time
    print(f"\n[Step 7] サマリー生成... (elapsed: {elapsed:.1f}s)")
    # → generate_summary() 呼び出し

    # ──── Step 8: 論文執筆・レビュー ────
    print("\n[Step 8] 論文執筆・レビュー...")
    # → scientific-academic-writing スキルで草稿作成
    # → scientific-critical-review スキルでレビュー・修正

    print("\n" + "=" * 60)
    print(f"完了! ({elapsed:.1f} 秒)")
    print("=" * 60)


if __name__ == "__main__":
    main()

3. Progress log utility

class StepLogger:
    """段階的進捗ログを管理するユーティリティ。"""

    def __init__(self, experiment_name):
        self.experiment_name = experiment_name
        self.step_count = 0
        self.start_time = time.time()
        self.step_times = {}
        print("=" * 60)
        print(f"{experiment_name}")
        print("=" * 60)

    def step(self, description):
        """新しい Step を開始する。"""
        self.step_count += 1
        step_start = time.time()
        if self.step_count > 1:
            prev = self.step_count - 1
            self.step_times[prev] = time.time() - self._current_step_start
        self._current_step_start = step_start
        print(f"\n[Step {self.step_count}] {description}...")

    def finish(self):
        """パイプライン完了を記録する。"""
        elapsed = time.time() - self.start_time
        if self.step_count > 0:
            self.step_times[self.step_count] = time.time() - self._current_step_start
        print(f"\n{'=' * 60}")
        print(f"完了! (合計 {elapsed:.1f} 秒)")
        for step_num, t in self.step_times.items():
            print(f"  Step {step_num}: {t:.1f}s")
        print(f"{'=' * 60}")
        return elapsed

4. JSON summary generation

Common to all experiments analysis_summary.json schema.

def generate_summary(results_dict, experiment_name, elapsed_seconds,
                     output_path=None):
    """
    標準フォーマットの analysis_summary.json を生成する。

    results_dict はドメイン固有の結果を含む辞書。
    この関数がメタ情報を自動追加する。
    """
    import datetime

    summary = {
        "experiment": experiment_name,
        "timestamp": datetime.datetime.now().isoformat(),
        "elapsed_seconds": round(elapsed_seconds, 2),
        "environment": {
            "python": __import__("sys").version,
            "seed": SEED,
        },
        "data": {
            "n_samples": results_dict.get("n_samples"),
            "n_features": results_dict.get("n_features"),
            "source": results_dict.get("data_source", "simulation"),
        },
        "results": results_dict,
    }

    if output_path is None:
        output_path = RESULTS_DIR / "analysis_summary.json"

    with open(output_path, "w", encoding="utf-8") as f:
        json.dump(summary, f, indent=2, ensure_ascii=False, default=str)

    print(f"  → Summary saved: {output_path}")
    return summary

List of standard JSON summary keys

Key Type Description Required
experiment str Experiment name ✅
timestamp str ISO 8601 datetime ✅
elapsed_seconds float Execution time ✅
environment.python str Python version ✅
environment.seed int Random seed ✅
data.n_samples int Number of samples ✅
data.n_features int Number of features ○
data.source str Data source ○
results.best_model str Best model name ○
results.best_r2 / best_auc float Best score ○
results.n_figures int Number of generated figures ○

5. Overview dashboard panel

import matplotlib.gridspec as gridspec

def create_summary_panel(panel_data, experiment_name, figsize=(20, 14)):
    """
    解析結果の総括ダッシュボードを 1 枚の Figure にまとめる。

    panel_data: [
        {"type": "table", "title": "...", "data": df_or_dict},
        {"type": "plot_func", "title": "...", "func": callable, "kwargs": {}},
        {"type": "text", "title": "...", "text": "..."},
        {"type": "metrics_bar", "title": "...", "names": [...], "values": [...]},
    ]
    """
    n_panels = len(panel_data)
    ncols = min(3, n_panels)
    nrows = (n_panels + ncols - 1) // ncols

    fig = plt.figure(figsize=figsize)
    gs = gridspec.GridSpec(nrows, ncols, figure=fig, hspace=0.4, wspace=0.3)

    for i, panel in enumerate(panel_data):
        row, col = divmod(i, ncols)
        ax = fig.add_subplot(gs[row, col])

        ptype = panel["type"]
        title = panel.get("title", f"Panel {chr(65 + i)}")

        if ptype == "metrics_bar":
            ax.barh(panel["names"], panel["values"],
                   color="steelblue", edgecolor="black")
            ax.set_xlabel("Value")

        elif ptype == "text":
            ax.text(0.05, 0.95, panel["text"], transform=ax.transAxes,
                   fontsize=9, verticalalignment="top", fontfamily="monospace",
                   bbox=dict(boxstyle="round", facecolor="wheat", alpha=0.5))
            ax.axis("off")

        elif ptype == "table":
            ax.axis("off")
            if isinstance(panel["data"], pd.DataFrame):
                tbl = ax.table(cellText=panel["data"].values,
                              colLabels=panel["data"].columns,
                              cellLoc="center", loc="center")
                tbl.auto_set_font_size(False)
                tbl.set_fontsize(8)
            elif isinstance(panel["data"], dict):
                rows = [[k, str(v)] for k, v in panel["data"].items()]
                tbl = ax.table(cellText=rows, colLabels=["Metric", "Value"],
                              cellLoc="center", loc="center")
                tbl.auto_set_font_size(False)
                tbl.set_fontsize(9)

        elif ptype == "plot_func":
            panel["func"](ax=ax, **panel.get("kwargs", {}))

        # パネルラベル (A, B, C, ...)
        ax.set_title(f"({chr(65 + i)}) {title}", fontsize=11, fontweight="bold")

    fig.suptitle(f"Summary: {experiment_name}", fontsize=14, fontweight="bold")
    plt.savefig(FIG_DIR / "summary_panel.png", dpi=300, bbox_inches="tight")
    plt.close()

6. Common utilities

def save_fig(fig, filename, dpi=300, formats=("png",)):
    """図を保存してクローズする共通関数。"""
    for fmt in formats:
        fig.savefig(FIG_DIR / f"{filename}.{fmt}",
                   dpi=dpi, bbox_inches="tight",
                   facecolor="white", edgecolor="none")
    plt.close(fig)
    print(f"  → Figure saved: {filename}")


def save_results(df, filename, index=False):
    """DataFrame を results/ に保存する共通関数。"""
    path = RESULTS_DIR / filename
    df.to_csv(path, index=index)
    print(f"  → Results saved: {filename}")

Standard directory structure

Exp-XX/
├── exp_analysis.py          # メインスクリプト
├── qiita-exp-analysis.md    # Qiita 記事
├── data/
│   └── dataset.csv          # 入力データ
├── figures/
│   ├── Fig01_*.png          # 個別図(Fig + 連番 + 説明)
│   ├── Fig02_*.png
│   └── summary_panel.png    # 総括ダッシュボード
└── results/
    ├── descriptive_statistics.csv
    ├── model_metrics.csv
    ├── feature_importance.csv
    └── analysis_summary.json  # JSON サマリー

ToolUniverse integration

TU Key Tool name Integration details
biotools bio.tools Pipeline composition tool search

References

Reference skills

Skill Integration
scientific-hypothesis-pipeline Step 0: Saving hypothesis formulation and workflow design
scientific-data-preprocessing Step 1/3: Data loading and preprocessing
scientific-eda-correlation Step 2: Exploratory data analysis and correlation analysis
scientific-ml-regression Step 4: Regression model training
scientific-ml-classification Step 4: Classification model training
scientific-publication-figures Step 5: Publication-quality figure and table generation
scientific-academic-writing Step 8: Paper writing
scientific-critical-review Step 8: Critical review and revision of drafts

Exp references

  • All 13 experiments: Directory structure, seed management, warnings suppression
  • Exp-12, 13: main() + execution time measurement + JSON summary + overview panel
  • Exp-10: save_fig() / write_summary() utility