alterlab-eda

探索的データ解析

概要

複数の分野にわたる科学データファイルについて、包括的な探索的データ解析（EDA）を実施します。このスキルでは、ファイル形式の自動検出、形式に応じた解析、データ品質の評価を行い、ドキュメントや後続の解析計画に活用できる詳細なMarkdownレポートを生成します。

主な機能：

• 解析スクリプトで約90種類のファイル拡張子を自動検出（.fastq.gzなど、gzip／bz2／xzで圧縮されたファイルも含む）。200種類以上の形式に関するリファレンス項目を収録
• 形式に応じた包括的なメタデータの抽出
• データ品質と整合性の評価
• 統計的な要約と分布
• 可視化の提案
• 後続の解析に関する提案
• Markdownレポートの生成

このスキルを使う場面

次のような場合に、このスキルを使用してください。

• ユーザーが解析対象の科学データファイルのパスを指定した場合
• ユーザーがデータファイルの「探索」、「解析」、「要約」を求めている場合
• ユーザーが科学データの構造と内容を把握したい場合
• 解析前にデータセットの包括的なレポートが必要な場合
• データ品質や完全性を評価したい場合
• ファイルに適した解析方法を尋ねられた場合

対象外

シナリオ	代わりに使用
すでに探索済みの時系列を予測する	alterlab-timesfm
チャンク化されたZarr配列ストアを作成または設定する（コーデック、チャンクレイアウト、クラウドストレージ）	alterlab-zarr
.h5adに対して単一細胞解析の全ワークフロー（QCフィルタリング、正規化、クラスタリング、マーカー解析）を実行する	alterlab-scanpy
仮定の確認とAPA形式での報告を行いながら、仮説検定を選択して実行する	alterlab-statistical-analysis

対応ファイルカテゴリ

このスキルは、科学データのファイル形式を次の6つの主要カテゴリに分類し、幅広く対応しています。

1. 化学・分子形式（60種類以上の拡張子）

構造ファイル、計算化学の出力、分子動力学の軌跡、化学データベース。

ファイル形式の例： .pdb、.cif、.mol、.mol2、.sdf、.xyz、.smi、.gro、.log、.fchk、.cube、.dcd、.xtc、.trr、.prmtop、.psfなど。

リファレンスファイル： references/chemistry_molecular_formats.md

2. バイオインフォマティクス・ゲノミクス形式（50種類以上の拡張子）

シーケンスデータ、アラインメント、アノテーション、変異、発現データ。

ファイル形式の例： .fasta、.fastq、.sam、.bam、.vcf、.bed、.gff、.gtf、.bigwig、.h5ad、.loom、.counts、.mtxなど。

リファレンスファイル： references/bioinformatics_genomics_formats.md

3. 顕微鏡・画像形式（45種類以上の拡張子）

顕微鏡画像、医用画像、全スライド画像、電子顕微鏡画像。

ファイル形式の例： .tif、.nd2、.lif、.czi、.ims、.dcm、.nii、.mrc、.dm3、.vsi、.svs、.ome.tiffなど。

リファレンスファイル： references/microscopy_imaging_formats.md

4. 分光法・分析化学形式（35種類以上の拡張子）

NMR、質量分析、IR／ラマン、UV-Vis、X線、クロマトグラフィー、その他の分析手法。

ファイル形式の例： .fid、.mzML、.mzXML、.raw、.mgf、.spc、.jdx、.xy、.cif（結晶構造解析）、.wdfなど。

リファレンスファイル： references/spectroscopy_analytical_formats.md

5. プロテオミクス・メタボロミクス形式（30種類以上の拡張子）

質量分析プロテオミクス、メタボロミクス、リピドミクス、マルチオミクスデータ。

ファイル形式の例： .mzML、.pepXML、.protXML、.mzid、.mzTab、.sky、.mgf、.msp、.h5adなど。

リファレンスファイル： references/proteomics_metabolomics_formats.md

6. 一般的な科学データ形式（30種類以上の拡張子）

配列、テーブル、階層型データ、圧縮アーカイブ、一般的な科学データ形式。

ファイル形式の例： .npy、.npz、.csv、.xlsx、.json、.hdf5、.zarr、.parquet、.mat、.fits、.nc、.xmlなど。

リファレンスファイル： references/general_scientific_formats.md

ワークフロー

ステップ 1：ファイル形式の検出

ユーザーがファイルパスを指定したら、まずファイル形式を特定します。

1. ファイルの拡張子を抽出します
2. 適切なリファレンスファイルで拡張子を検索します
3. ファイルのカテゴリと形式の説明を特定します
4. 形式固有の情報を読み込みます

例：

User: "Analyze data.fastq"
→ Extension: .fastq
→ Category: bioinformatics_genomics
→ Format: FASTQ Format (sequence data with quality scores)
→ Reference: references/bioinformatics_genomics_formats.md

ステップ 2：形式固有の情報を読み込む

ファイル形式に応じて、対応するリファレンスファイルを読み、以下を確認します。

• 一般的なデータ： この形式にどのような種類のデータが含まれるか
• 用途： この形式の一般的な用途
• Python ライブラリ： Python でファイルを読み込む方法
• EDA のアプローチ： このデータ型に適した分析

リファレンスファイルで該当する拡張子を検索します（例：bioinformatics_genomics_formats.md で「### .fastq」を検索します）。

ステップ 3：データ分析を実行する

script/eda_analyzer.py を使用するか、カスタム分析を実装します。

オプション A：アナライザースクリプトを使用する（形式を自動検出し、リファレンスを読み込み、形式固有の分析を実行して、レポートを書き込みます）

uv run python scripts/eda_analyzer.py <filepath> [output.md]

このスクリプトには、表形式（.csv／.tsv）、配列（.npy／.npz／.hdf5）、JSON、配列データ（.fasta／.fastq。gzip／bz2／xz 圧縮にも対応）、および基本的な画像（.tif）用のアナライザーが組み込まれています。それ以外の形式でも、形式を検出してリファレンス情報を埋め込みますが、データ分析は自分で行う必要があります（オプション B）。

オプション B：会話内でカスタム分析を行う リファレンスファイルの形式情報に基づいて、適切な分析を実行します。

表形式データ（CSV、TSV、Excel）の場合：

• pandas で読み込みます（pandas 3 ではテキスト列は str dtype として読み込まれます。select_dtypes(include='object') でも引き続き該当しますが、非推奨です。そのため、pandas 2 と 3 の両方で動作する exclude='number' を使用します）
• 次元とデータ型を確認します
• 欠損値を分析します
• 要約統計量を計算します
• 外れ値を特定します
• 重複を確認します

配列データ（FASTA、FASTQ）の場合：

• 配列数を数えます
• 長さの分布を分析します
• GC 含量を計算します
• 品質スコアを評価します（FASTQ）

画像（TIFF、ND2、CZI）の場合：

• 次元（X、Y、Z、C、T）を確認します
• ビット深度と値の範囲を分析します
• メタデータ（チャネル、タイムスタンプ、空間キャリブレーション）を抽出します
• 強度の統計量を計算します

配列（NPY、HDF5）の場合：

• 形状と次元を確認します
• データ型を分析します
• 統計的な要約を計算します
• 欠損値や無効な値を確認します

ステップ 4：包括的なレポートを作成する

以下のセクションを含む Markdown レポートを作成します。

必須セクション：

1. タイトルとメタデータ

   • ファイル名とタイムスタンプ
   • ファイルサイズと場所

2. 基本情報

   • ファイルのプロパティ
   • 形式の特定

3. ファイル形式の詳細

   • リファレンスに記載された形式の説明
   • 一般的なデータ内容
   • 一般的な用途
   • 読み込みに使用する Python ライブラリ

4. データ分析

   • 構造と次元
   • 統計的な要約
   • 品質評価
   • データの特性

5. 主な調査結果

   • 注目すべきパターン
   • 潜在的な問題
   • 品質指標

6. 推奨事項

   • 前処理の手順
   • 適切な分析
   • ツールと手法
   • 可視化の方法

テンプレートの場所

レポートの構成のガイドとして assets/report_template.md を使用します。

ステップ 5：レポートを保存する

説明的なファイル名で Markdown レポートを保存します。

• パターン：{original_filename}_eda_report.md
• 例：experiment_data.fastq → experiment_data_eda_report.md

詳細な形式リファレンス

各リファレンスファイルには、数十種類のファイル形式に関する包括的な情報が含まれています。特定の形式について情報を探すには、次の手順を実行します。

1. 拡張子からカテゴリを特定します
2. 適切なリファレンスファイルを読みます
3. 拡張子に一致する見出しを検索します（例：「### .pdb」）
4. 形式情報を抽出します

リファレンスファイルの構成

各形式の項目には、以下が含まれます。

• 説明： 形式の概要
• 一般的なデータ： 含まれるデータ
• ユースケース： 一般的な用途
• Python ライブラリ： 読み込み方法（コード例付き）
• EDA のアプローチ： 実施する具体的な分析

検索例：

### .pdb - Protein Data Bank
**Description:** Standard format for 3D structures of biological macromolecules
**Typical Data:** Atomic coordinates, residue information, secondary structure
**Use Cases:** Protein structure analysis, molecular visualization, docking
**Python Libraries:**
- `Biopython`: `Bio.PDB`
- `MDAnalysis`: `MDAnalysis.Universe('file.pdb')`
**EDA Approach:**
- Structure validation (bond lengths, angles)
- B-factor distribution
- Missing residues detection
- Ramachandran plots

ベストプラクティス

リファレンスファイルの読み込み

リファレンスファイルは大容量です（各 10,000 語以上）。効率よく利用するには、次の方法に従ってください。

1. 拡張子で検索： grep を使って、対象の形式を見つけます

   import re
   with open('references/chemistry_molecular_formats.md', 'r') as f:
       content = f.read()
       pattern = r'### \.pdb[^#]*?(?=###|\Z)'
       match = re.search(pattern, content, re.IGNORECASE | re.DOTALL)
   

2. 関連するセクションを抽出： リファレンスファイル全体を不必要にコンテキストへ読み込まないでください

3. 形式情報をキャッシュ： 同じ種類のファイルを複数分析する場合は、形式情報を再利用します

データ分析

1. 大容量ファイルをサンプリング： レコードが数百万件あるファイルでは、代表的なサンプルを分析します
2. エラーを適切に処理： 多くの科学系形式では専用ライブラリが必要です。明確なインストール手順を提示してください
3. メタデータを検証： メタデータの整合性を相互確認します（例：記載された次元と実際のデータ）
4. データの来歴を考慮： 装置、ソフトウェアのバージョン、処理手順を記録します

レポートの作成

1. 網羅的に記載： 下流の分析に関連する情報をすべて含めます
2. 具体的に記載： ファイルの種類に応じた具体的な推奨事項を提示します
3. 実行可能な内容にする： 具体的な次の手順やツールを提案します
4. コード例を含める： データの読み込み方法と扱い方を示します

例

手順は常に同じです。拡張子を検出する -> 対応するリファレンスセクションを読む -> 形式に適した分析を実行する -> <stem>_eda_report.md を作成する。

• reads.fastq -> バイオインフォマティクス。from Bio import SeqIO; SeqIO.parse(path, 'fastq')。リード数、長さの分布、リードごとの品質、GC 含量をレポートし、その後、QC に関する推奨事項を示します。
• experiment_results.csv -> 一般的な科学データ。pd.read_csv。形状、データ型、欠損値のパターン、要約統計量、相関、重複、外れ値をレポートします。
• cells.nd2 -> 顕微鏡（Nikon）。import nd2; f = nd2.ND2File(path)（f.sizes、f.metadata、f.voxel_size()）。XYZCT の次元、チャネル／タイムポイント、ピクセルサイズ／キャリブレーション、強度統計量をレポートし、その後、画像分析に関する推奨事項を示します。

トラブルシューティング

ライブラリがない場合

多くの科学系形式では、専用ライブラリが必要です。

問題： ファイルの読み込み時にインポートエラーが発生する

解決策： uv pip install <pkg> でパーサーをインストールします（このマシンでは pip を単独で使用しないでください）。その後、再試行します。カテゴリ別の一般的な要件は次のとおりです。

• バイオインフォマティクス： biopython、pysam、pyBigWig
• 化学： rdkit、mdanalysis、cclib
• 顕微鏡： tifffile、nd2、bioio に加え、bioio-czi や bioio-lif などの形式プラグイン（メンテナンスモードの aicsimageio の後継）、pydicom
• 分光法： nmrglue、pymzml、pyteomics
• 一般： pandas、numpy、h5py、scipy

不明なファイル形式

ファイルの拡張子がリファレンスにない場合：

1. ファイル形式についてユーザーに確認します
2. ベンダー固有の派生形式かどうかを確認します
3. ファイル構造（テキストかバイナリか）に基づいて、汎用的な分析を試みます
4. 一般的な推奨事項を提示します

大容量ファイル

非常に大きなファイルの場合：

1. サンプリング手法を使用します（先頭から N 件のレコード）
2. メモリマップアクセスを使用します（HDF5、NPY の場合）
3. チャンク単位で処理します（CSV、FASTQ の場合）
4. サンプルに基づいて推定値を提示します

スクリプトの使用方法

uv run python scripts/eda_analyzer.py data.csv                 # report -> data_eda_report.md
uv run python scripts/eda_analyzer.py data.csv output_report.md

スクリプトは、末尾の .gz／.bz2／.xz も考慮してファイルの種類を自動検出し、対応するリファレンスセクションを読み込み、利用可能な場合は組み込みの分析を実行して、Markdown レポートを作成します。組み込みアナライザーがない形式では、ドメイン固有の知見を得るため、会話内でのカスタム分析（オプション B）を推奨します。注：.csv／.tsv では、スクリプトは先頭の 10,000 行をサンプリングします。そのため、ファイル全体に対して再実行しない限り、次元や欠損数は サンプルに基づく値 としてレポートしてください。

高度な使用方法

• 複数ファイル： 各ファイルのEDAを個別に実施し、関係性、依存関係、統合戦略を記載した比較レポートを作成します。
• 品質管理： 形式への準拠を確認し、メタデータの一貫性（記載された次元と実際の次元）を検証し、完全性を評価し、想定範囲から外れる値や異常値を特定します。
• 前処理の推奨： データに合わせて、正規化、欠損値の補完、外れ値の処理、バッチ補正、形式変換を提案します。

リソース

scripts/

• eda_analyzer.py：直接実行またはインポートできる包括的な分析スクリプト

references/

• chemistry_molecular_formats.md：60 種類以上の化学・分子ファイル形式
• bioinformatics_genomics_formats.md：50 種類以上のバイオインフォマティクス形式
• microscopy_imaging_formats.md：45 種類以上のイメージング形式
• spectroscopy_analytical_formats.md：35 種類以上の分光分析形式
• proteomics_metabolomics_formats.md：30 種類以上のオミクス形式
• general_scientific_formats.md：30 種類以上の一般的な形式

assets/

• report_template.md：EDA レポート用の包括的な Markdown テンプレート