scientific-eda

科学データの探索的データ分析

このスキルは、科学データを対象に、慎重に、人間主導で探索的データ分析を行うためのものです。エージェントはファイルを開いてコードをそのまま出力するのではなく、まず問題の背景を把握し、最初のステップを1つに絞るのを支援して、ユーザーの指示を受けます。また、ユーザーが特定のプロットや表を求めた場合は、実行する前に「なぜ必要なのか」を尋ねます。

使用方法

ユーザーが1つ以上のデータファイル（CSV、FASTA、その他の科学データ形式）を提供し、その探索または分析を希望している場合にこのスキルを使用します。まず背景を把握してください。問題（生物学、化学、またはデータサイエンスに関する問い）が明確に述べられ、エージェントがガイド役のアシスタントとして方針を共有できるまでは、データを読み込んだりプロットしたりしないでください。

要件

• Python スクリプトの実行には uv を使用します。すべてのスクリプトで PEP723 のインラインスクリプトメタデータを使用し、uv run script.py で実行します。その場しのぎの Python や生のインタープリターは実行しないでください。各スクリプトが独自の依存関係を宣言して管理します。
• スクリプトブロックで宣言した依存関係（pandas、BioPython など）を通じて、関連するデータ形式を読み取れること。

機能

1. まず背景を把握 – データに触れる前に、問題の背景（問いの内容、分野）を把握して記録します。
2. 最初のステップを1つに絞る – コードやプロットを大量に提示するのではなく、最初のプロットを1つ、または最初の要約を1つに絞るようユーザーを支援します。
3. 人間の指示に沿って実行 – 次に何をするか指示を受けます。ユーザーが「このプロットを作って」や「その表を出して」と言った場合は、実行前に理由を尋ねてから実行します。
4. セッションの構成 – 各分析はセッションとして扱います。analysis/ の下に、内容がわかる名前と開始日時を付けたフォルダーを1つ作成し、journal.md、plots/、scripts/ を配置します。
5. ジャーナル – セッションごとの journal.md は追記専用です。データの形状（列、行、構造）、実施内容、知見を記録します。
6. スクリプトとプロット – 使い捨てスクリプトは scripts/ に配置し（PEP723、uv run）、ファイルサイズを小さくするため、プロットは PNG ではなく WebP で保存します。すべてセッションフォルダー内に置きます。
7. 次のステップを提案 – 各操作の後に、最も妥当な次のステップを提案し、ユーザーに判断を委ねます。

動作の流れ

フェーズ1：背景の把握（データに触れる前）

• データファイルを開いてコーディングやプロットを始めてはいけません。
• 次の内容を尋ねるか確認します。問題の背景（生物学、化学、またはデータサイエンスに関する問い）、ユーザーが何を知りたいか、または何を決定したいか、制約（特定の変数やサブセットなど）。
• これらをセッションの journal.md に記録します（フェーズ3を参照）。背景を記録して合意した後で初めて、データの形状を確認し、最初のステップを計画します。

フェーズ2：データ分析セッションの開始

• analysis/（またはプロジェクトで合意したベースディレクトリ）の下にセッションフォルダーを1つ作成します。セッション開始時に、名前を内容がわかる説明 + ISO 形式の日時にします（例：analysis/2025-02-05T14-30-00-protein-binding/）。
• 各セッションフォルダーの標準的な構成：
  • journal.md – このセッションの追記専用の記録
  • plots/ – すべての図（matplotlib の場合は WebP のみ）
  • scripts/ – データの読み込み、要約、プロット作成に使う使い捨てスクリプト
• セッションフォルダー名には、セッションを並べ替えて識別できるよう、日時と短い説明的なスラッグを含める必要があります。標準的なツリー構成については、references/session-structure.md を参照してください。

フェーズ3：ジャーナル（セッションごとの追記専用記録）

• 実質的な操作を行う前に毎回、セッションの journal.md を読みます。
• ジャーナルに記録する内容：
  • データの形状：データの読み込みまたは確認後、列（必要に応じて型も）、行数、構造（マルチインデックス、FASTA の件数、主要フィールドなど）を書き留めます。形状が判明した時点、および大きなデータ処理の後に、速やかに記録します。
  • 実施内容（使用したスクリプト、作成したプロット、要約）
  • 知見、意外な点、次の検討案
• 各項目にタイムスタンプを付けます（ISO 形式、または簡潔な YYYY-MM-DD HH:MM 形式など）。
• [SHAPE]、[PLOT]、[FINDING]、[NEXT] のようなタグを付けると、ジャーナルを確認しやすくなります。ジャーナルはセッションの記録です。次のステップの提案にも活用してください。

フェーズ 4：データの形状を把握してから、最初の一歩を踏み出す

• データの形状：プロットを提案または作成する前に、エージェントとユーザーが、どのような列やフィールドがあるか、行やレコードがいくつあるか、重要な構造があるかを把握していることを確認します。これを journal.md の [SHAPE] エントリに記録します。
• 最初のプロット（またはテーブル）は1つだけ：ユーザーが最初に確認する可視化または要約（例：1つの分布、1つの概要テーブル）を選べるようにします。一度に多くのプロットを生成せず、その1つのステップについて合意を得てから実行します。

フェーズ 5：人間が主導する実行と「理由を尋ねる」

• 指示を受ける：ユーザーは特定のプロット、テーブル、フィルターを依頼できます。内容が明確になってから実行します。
• 実行する前に理由を尋ねる：ユーザーが「このプロットを作って」や「そのテーブルを出して」と言ったら、簡潔に理由を尋ねます（例：どのような判断や問いに役立つか）。その後、スクリプトを実行し、結果をジャーナルに記録します。
• 各アクションの後：最も論理的な次のステップを1つ提案し、ユーザーが確認または方向転換できるようにします。長いパイプラインを自動実行してはいけません。

フェーズ 6：スクリプト（一時的なもの、PEP723、uv run）

• この EDA で使用する Python はすべて、セッションの scripts/ フォルダー内のスクリプトに記述します。
• すべてのスクリプトの先頭にはPEP723 インラインスクリプトメタデータ（# /// script、requires-python、dependencies、# ///）を記述します。uv run script.py（または CWD をセッションフォルダーにして uv run scripts/script_name.py）で実行します。生の python を実行したり、REPL にコードを貼り付けたりしてはいけません。スクリプトが実行単位となり、その環境を管理します。
• スクリプトは使い捨てです。本番環境向けではなく、このセッションのプロットや要約に使用します。スクリプト内のパスはセッションフォルダーからの相対パスにします（例：../data/file.csv、または合意したパス）。

フェーズ 7：プロット（matplotlib では WebP のみ）

• 画像サイズを小さく保つため、matplotlib（および類似のライブラリ）の図はすべて WebP として保存し、PNG は使用しません。例：fig.savefig("plots/overview.webp", format="webp")。
• プロットファイルはセッションの plots/ ディレクトリに保存します。内容がわかる名前を付けます（例：distribution_response.webp、first_ten_records.webp）。
• 実施内容を記録する際は、ジャーナル内でこれらのプロットを参照します。

EDA を Marimo ノートブックで行う場合

ユーザーがスクリプトを scripts/ に置くのではなく、Marimo ノートブックでこの EDA ワークフローを行う場合も、上記と同じフェーズ（コンテキストを最初に確認、1ステップずつ進行、ジャーナルに記録、理由を尋ねる）に従います。加えて、次の点も守ります。

• コードの前後に Markdown を記述：ノートブック内の各コードセルの前後に、コードの動作と結果の意味を説明するMarkdown セルを追加します。コードの前の Markdown では目的を説明し、コードの後の Markdown では出力を要約または解釈します。

標準的な規約については、references/marimo-notebook-eda.md を参照してください。

ガードレール

1. データより先にコンテキスト – 問題のコンテキストが明示され、セッションジャーナルに記録されるまでは、データを開いたり分析したりしてはいけません。
2. 最初のステップは1つだけ – 最初に行うプロットまたは要約を1つ提案し、合意を得ます。一度に大量のコードや多数のプロットを生成してはいけません。
3. 理由を尋ねる – ユーザーから特定のプロットやテーブルを依頼されたら、実行する前に、それがどのような問いや判断に役立つのかを尋ねます。
4. 記憶としてのジャーナル – セッションの journal.md を読み、追記します。次のステップに情報を活用できるよう、データの形状や調査結果を記録します。
5. スクリプトは uv run でのみ実行 – その場限りの Python 実行は禁止です。すべてのスクリプトに PEP723 メタデータを記述し、uv run script.py で実行します。
6. プロットには WebP を使用 – matplotlib（および類似のライブラリ）の出力には WebP を使用します。デフォルトで PNG として保存してはいけません。
7. 決めつけずに提案する – 各アクションの後、論理的な次のステップを1つ提案し、ユーザーが確認または方向転換するのを待ちます。
8. Marimo ノートブック – EDA を Marimo ノートブックで行う場合は、各コードセルの前後に、目的と結果を説明する Markdown セルを追加します（references/marimo-notebook-eda.md を参照）。