exploring-data

データを調べる

0. まずサイズに応じて使い分けます

ls -la <filepath>   # or: wc -l for row estimate

• 200MB 未満かつ約 500 万行未満 → ydata-profiling の手順（セクション A）。正確な統計情報とインタラクティブな HTML を生成します。
• それより大きい場合 → 大容量ファイルの手順（セクション B）。ydata-profiling はデータ全体を pandas に読み込むため、処理が極端に遅くなったり、メモリ不足になったりします。DuckDB／スケッチの手順なら、サイズにかかわらずメモリ使用量が一定です。
• 特定のタスク向けの処理（サイズ不問）：重複、結合可能性、ドリフト → セクション C。

A. 標準的な手順（ydata-profiling）

1. インストール済みか確認する（すぐに完了します）

bash /mnt/skills/user/exploring-data/scripts/check_install.sh

戻り値：installed または not_installed

2. 必要に応じてインストールする（初回のみ、約 19 秒）

if [ "$(bash /mnt/skills/user/exploring-data/scripts/check_install.sh)" = "not_installed" ]; then
    bash /mnt/skills/user/exploring-data/scripts/install_ydata.sh
fi

3. 分析を実行する（デフォルトで常に JSON と HTML を生成します）

bash /mnt/skills/user/exploring-data/scripts/analyze.sh <filepath> [minimal|full] [html|json]

デフォルト： minimal + html（JSON も生成します）

出力：

• eda_report.html - ユーザー向けのインタラクティブなレポート
• eda_report.json - Claude による分析用の機械可読形式

4. Claude に分析させる場合（ユーザーから「どう思う？」などと聞かれた場合）

python /mnt/skills/user/exploring-data/scripts/summarize_insights.py /mnt/user-data/outputs/eda_report.json

Claude には、JSON レポート全体ではなく、標準出力の Markdown 要約を読ませてください。

5. 分析結果を視覚的に示す（ydata の HTML をそのまま渡すだけでは不十分です）

ydata のレポートは網羅的ですが情報量が多いため、リンクを渡すだけでは成果物として不十分です。 JSON をもとに、重要な分析結果をまとめた簡潔なダッシュボードを作成します。

python3 /mnt/skills/user/exploring-data/scripts/visualize_findings.py \
    /mnt/user-data/outputs/eda_report.json
# → /mnt/user-data/outputs/eda_findings.html

自己完結型の HTML ファイルを 1 つ生成します（cdnjs の Chart.js を使用し、ダークモードに対応）。 列ごとの欠損率（段階別の良否表示）、最も歪んでいる、またはゼロが多い数値分布の小さな複数ヒストグラム、カテゴリごとの最大規模の内訳を表示します。--top N でカテゴリごとのグラフ数を制限できます（デフォルトは 6）。profile_large.py --json の出力も読み込めるため、大容量ファイルの手順でも同様に表示できます。

両方のファイルを提示してください。概要を確認する eda_findings.html と、詳細を掘り下げる eda_report.html です。チャット画面内にビジュアルを表示できる場合は、ファイルへのリンクを示すよりも、ユーザーの質問に実際に答える 2、3 個の分析結果をインラインのグラフで表示してください。ユーザーが開く必要のあるリンクは、データを「見せる」方法として最も不十分です。

モード

Minimal（デフォルト、5～10 秒）： 概要、変数分析、相関、欠損値、アラート Full（10～20 秒）： minimal に散布図行列、サンプルデータ、文字分析を追加

Full モードを使う条件：「包括的な分析」「詳細な EDA」「全項目のプロファイリング」「詳細分析」。それ以外は minimal を使用します。

時系列

データに datetime インデックスまたは列があり、ユーザーが時間的な挙動（欠落、傾向、季節性、自己相関）に関心がある場合は、tsmode=True を ProfileReport に渡してください。analyze.sh ではなく、venv の Python を直接実行します。

ProfileReport(df, tsmode=True, sortby="<datetime_col>", title=...)

これにより、デフォルトのレポートでは省略される、欠落の検出、定常性、季節性のチェックが追加されます。

小規模ファイルのドリフト

メモリに収まるデータセットの 2 つのバージョンを比較する場合は、ydata の組み込み比較機能を使用します — ProfileReport(df_a).compare(ProfileReport(df_b)).to_file(...)。 大きすぎて読み込めないファイルや、数か月前のファイルを手元に残しておらず比較できない場合は、セクション C のスケッチのスナップショット／ドリフト処理を使用します。

B. 大容量ファイルの手順（DuckDB、メモリ使用量一定）

1. 依存関係をインストールする（何度実行しても安全、初回は約 10 秒）

bash /mnt/skills/user/exploring-data/scripts/install_large.sh

2. プロファイリングする

python3 /mnt/skills/user/exploring-data/scripts/profile_large.py <file> [--json out.json]

DuckDB でファイルをストリーミング処理し、列ごとの null%、概算ユニーク数（HLL）、最小値／最大値／平均値、数値の概算分位点（t-digest）、文字列の上位 5 件の値に加え、品質フラグ（null が大半を占める列、定数列、ID のような列）を取得します。Markdown は標準出力に出力されるため、そのまま読み取ることができ、要約の手順は不要です。csv／tsv／parquet／json／ndjson に対応しています。100 万行のプロファイリングは数秒で完了し、ファイルサイズにかかわらずメモリ使用量は一定です。

同じ大容量ファイルに対してその場で追加クエリを実行する場合は、pandas に読み込むのではなく、DuckDB の SQL を直接使用します（duckdb.connect().execute("SELECT ... FROM read_csv_auto('...')")）。

C. スケッチ処理（ファイルサイズ不問、メモリ使用量一定）

すべて scripts/sketch_ops.py から実行します（依存関係は install_large.sh でインストールします）。プロファイラーでは答えられない質問に対応します。

近似重複行

python3 sketch_ops.py dups <file> [--threshold 0.9] [--cols a,b,c] [--unweighted]

完全に重複する行はハッシュで数え、近似重複行は行のトークンに対する MinHash LSH で検出します。--threshold は重み付きJaccard のしきい値です。行内に c 回出現するトークンは c 回として数えるため、new york new york と york new のスコアは 1.0 ではなく 0.5 になります。重複を破棄する集合として扱うには、--unweighted を指定します。識別に使う列に限定するには、--cols を使用します。

キーの重複／結合の実現可能性

python3 sketch_ops.py overlap <fileA> <fileB> --key <col> [--key-b <col>]

各キー列の Theta スケッチから、共通部分、Jaccard、および「A のキーのうち B に含まれる割合」を両方向について推定します。どちらのファイルも読み込まずに、「この結合は成立するか？」を確認できます。

保存済みベースラインとのドリフト

python3 sketch_ops.py snapshot <file> --out baseline.sketch.json   # ~20KB
python3 sketch_ops.py drift <newfile> --baseline baseline.sketch.json

スナップショットでは、HLL（全列）と KLL 分位点スケッチ（数値列）を小さな JSON にシリアライズします。ドリフトレポートでは、スキーマの変更、個別値の数の 10% 超の変動、IQR を基準とした分位点の移動を確認できます。スナップショットは数 KB です。保存しておけば（リポジトリやメモリなど）、元のファイルを保持せずに翌月のデータを比較できます。

注：snapshot/dups は Python で行をストリーム処理します（数百万行でも数秒）。profile_large は DuckDB のみで処理するため、より高速です。大きなファイルを手早く確認するには、まずプロファイルを実行し、必要な場合にのみスケッチ操作を使ってください。