cja-dimension-analysis

CJA ディメンション分析

1 つ以上の CJA ディメンションを分析し、カーディナリティ、分布、傾向、異常、データ品質の問題、予測を把握します。チームがディメンションの内容を理解し、注目すべき箇所を見極めるための、実行可能なレポートを作成します。

ワークフロー

各フェーズを順番に実行します。各フェーズは選択可能です。ユーザーは一部のフェーズ（例：「カーディナリティとエラーだけ」）または全分析を指定できます。デフォルトではすべてのフェーズを実行します。

フェーズ 0 — セットアップ

1. findDataViews を呼び出して、利用可能なデータビューを一覧表示します。ユーザーが指定していない場合は、分析するデータビューを尋ねます。setDefaultSessionDataViewId で設定します。
2. 分析するディメンションを尋ねます。選択肢は次のとおりです。
   • 名前を指定したディメンション：「ページ名とブラウザータイプを分析」
   • ID で指定：ユーザーがディメンション ID を直接指定
   • すべてのディメンション：処理に時間がかかる場合があることを伝え、上限を尋ねます（デフォルト：名前順で上位 50 件）
3. 実行する分析を尋ねます（またはデフォルトの「すべて」を確認します）。
   • カーディナリティ、分布／偏り、傾向、異常、データ品質、比較、予測
4. 日付範囲を尋ねます。ユーザーが指定していない場合は、データが見つかる範囲を確認するため、いくつかの日付範囲を試します。
   • 過去 30 日、過去 90 日、過去 6 か月、過去 1 年の順に試し、行が返される最初の範囲を使用します。
5. 分布／偏りに使用する主要指標を尋ねます（デフォルト：発生回数または訪問数）。
6. 先に進む前に、ユーザーに計画を確認します。

フェーズ 1 — カーディナリティ

各ディメンションについて、次の手順を実行します。

1. searchDimensionItems(dimensionId, limit: 50000) を呼び出して一意の値の数を推定するか、ディメンションを行、カウント指標を使って runReport を実行し、行数を取得します。
2. カーディナリティを分類します。

   レベル	しきい値
   LOW	一意の値が 100 未満
   MEDIUM	100 ～ 1,000
   HIGH	1,000 ～ 10,000
   VERY HIGH	10,000 超

3. カーディナリティを経時的に追跡します（任意）：ディメンションと日付の内訳を指定して runReport を実行し、日／週ごとの一意のディメンション値を数えて、カーディナリティの増加傾向を確認します。
4. パフォーマンスに関する推奨事項とともに、HIGH および VERY HIGH のディメンションにフラグを付けます。

保存先：{dimensionId, name, uniqueValueCount, cardinalityLevel, cardinalityTrend}

フェーズ 2 — 分布と偏り

各ディメンションについて、次の手順を実行します。

1. ディメンションを行、主要指標（例：発生回数／訪問数）を指標として runReport を実行します。分布の形状を把握するため、少なくとも 50 行を要求します。
2. 上位 N 件の割合（上位 1、5、10 件）、ジニ係数、累積分布を計算します。
3. 偏りを分類します。

   ラベル	条件
   極端な偏り	上位 1 件の値が全体の 50% 超
   強い偏り	上位 1 件の値が全体の 30% 超
   中程度	上位 5 件の値が全体の 70% 未満
   ロングテール	上位 10 件の値が全体の 50% 未満

4. 注記：値ごとの内訳をパーセンテージと累積パーセンテージとともに示します。

保存先：{dimensionId, distribution: [{value, metric, pct, cumulative}], gini, skewLabel, top1Pct, top5Pct, top10Pct}

フェーズ 3 — 傾向

各ディメンションについて、次の手順を実行します。

1. ディメンションと日付の粒度（範囲に応じて日または週）を指定して runReport を実行します。選択した日付範囲を前半と後半に分けて比較します。
2. 次の項目を特定します。
   • 新しい値：期間 1 にはなく、期間 2 に出現した値
   • 消失した値：期間 1 には存在し、期間 2 には存在しない値
   • 増加：期間 2 の指標が期間 1 より 10% 超増加
   • 減少：期間 2 の指標が期間 1 より 10% 超減少
   • 安定：期間間の変化が 10% 未満
3. 値ごとに傾向バッジを割り当てます：🟢 増加 | 🔴 減少 | 🟡 安定 | 🆕 新規 | ⬜ 消失

保存先：{dimensionId, periodComparison: {period1, period2, changes: [{value, p1Metric, p2Metric, pctChange, badge}]}, newValues: [], disappearedValues: []}

フェーズ 4 — 異常値

各ディメンションについて：

1. フェーズ 3 の時系列データから、ディメンション値ごとの移動平均と標準偏差を計算します。
2. Z スコア検出：Z スコアがしきい値を超える（値、日付）の組み合わせにフラグを付けます （デフォルト：2.0、敏感：1.5、保守的：3.0）。
3. しきい値アラート：
   • 特定の日に、単一の値が指標全体の 50% を超えて占める
   • 値の件数が、その値の移動平均の 2 倍を超える
4. 新規／消失アラート：期間の途中で出現または消失する値にフラグを付けます（フェーズ 3 を参照）。
5. 収集項目：異常の種類（急増、急減、新規、消失、しきい値）、ディメンション値、日付、変化量。

保存形式：{dimensionId, anomalies: [{value, date, type, magnitude, zScore}]}

フェーズ 5 — データ品質／エラー

各ディメンションについて：

1. searchDimensionItems を使用して、既知の不正値を検索します：
   • "Unspecified", "None", "(empty)", "", "null", "undefined", "N/A", "unknown"
2. 各既知の不正値で runReport をフィルタリングして、出現件数を数えます。
3. 計算します：欠損データ率 % =（不正値の出現件数の合計）/ 出現件数の合計。
4. フラグを付けます：欠損データが 5% を超えるディメンション（警告）、20% を超えるディメンション（重大）。
5. ディメンションに想定される形式（URL、メールアドレス、日付）がある場合は記録します。ただし、ユーザーから依頼されない限り、パターンの自動検証は行いません。

保存形式：{dimensionId, errorPatterns: [{pattern, count, pct}], missingDataPct, missingDataSeverity}

フェーズ 6 — 比較（複数ディメンションまたは期間）

ユーザーが 2 つ以上のディメンションを分析する場合、または期間比較を依頼した場合に、このフェーズを実行します。

並列比較（2～3 個のディメンション）：

1. ディメンションの各ペアについて、カーディナリティのレベル、偏り、上位 5 件の値、エラー率を比較します。
2. 各指標について、ディメンション A、B、C を比較する表を作成します。

期間比較（単一ディメンション）：

1. ユーザーが指定した 2 つのカスタム日付範囲を比較します（または自動検出：前半と後半）。
2. 各値について、期間 1 の指標、期間 2 の指標、差分、変化率を示します。
3. 変動が最も大きい項目を示します（増加上位 5 件、減少上位 5 件）。

保存形式：{comparisons: [{type, dimensions or periods, table}]}

フェーズ 7 — 予測

十分な時系列データ（データポイントが 7 件以上）がある各ディメンションについて：

1. 指標の上位 5～10 件の値について、時系列データに線形回帰を適合させます。
2. 7 期間先まで予測します。
3. 次の内容を報告します：
   • トレンドの方向：上昇／下降／横ばい（傾きに基づく）
   • 信頼度：高（R² > 0.7）、中（0.4～0.7）、低（< 0.4）
   • 予測期間終了時の予測値
4. 強い上昇トレンド（優勢になる可能性がある）、または強い下降トレンド（まもなく消失する可能性がある）の値にフラグを付けます。

保存形式：{dimensionId, forecasts: [{value, slope, r2, direction, confidence, projectedValues: []}]}

フェーズ 8 — レポート生成

すべての分析フェーズが完了したら：

1. 収集したすべてのデータを JSON ファイルに保存します： dimension_analysis_results_YYYY-MM-DD_HH-MM.json （/tmp/cja-dimension-analysis/ などの一時出力ディレクトリ、またはユーザー指定のパス）

2. Python レポート生成スクリプトを実行します：

   python3 scripts/cja_dimension_analysis.py \
     <analysis_json> \
     "<data_view_name>" \
     "<data_view_id>" \
     [output_directory] \
     [--format=html|markdown] \
     [--keep-analyses=N]
   

   オプション：

   • --format=html（デフォルト）：Chart.js による可視化を備えたインタラクティブな HTML ダッシュボード
   • --format=markdown：表を含む、包括的なテキストベースのレポート
   • --keep-analyses=N（デフォルト：0 = すべて保持）：古い分析ファイルを自動クリーンアップします

3. スクリプトによって、レポート（HTML または Markdown）という 2 つ目の出力ファイルが生成されます。

4. open <output_directory>/dimension_analysis_report_*.html で開きます

5. レポートのパスをユーザーに示し、主な調査結果を要約します：

   • カーディナリティが高または非常に高いディメンション
   • 偏りが極端または大きいディメンション
   • 見つかった異常値
   • 警告しきい値を超えるデータ品質の問題
   • 注目すべき予測トレンド

使用する CJA MCP ツール

ツール	フェーズ	目的
findDataViews	0	利用可能なデータビューを一覧表示します
setDefaultSessionDataViewId	0	セッションのアクティブなデータビューを設定します
findDimensions	0	名前や検索語でディメンションを検出します
describeDimension	0	ディメンションのメタデータと ID を取得します
searchDimensionItems	1, 5	一意の値をカウントし、特定の項目（エラーパターン）を検索します
runReport	1–7	主要なデータエンジンです。ディメンションの行と指標を取得し、必要に応じて日付別の内訳も取得します

出力形式

HTML ダッシュボード（デフォルト）

次の内容を含むインタラクティブなレポートです。

• エグゼクティブサマリーカード（ディメンションの合計数、フラグが付いたディメンション、重大な問題）
• ディメンションごとのセクション：カーディナリティバッジ、分布グラフ（Chart.js の棒グラフ）、偏りの指標、トレンド表、異常の一覧、データ品質指標
• 比較セクション（複数のディメンションまたは期間比較がリクエストされた場合）
• 予測セクション（予測を実行した場合）
• 推奨事項パネル：優先度別（重大 → 警告 → 情報）
• デザイン：濃紺から青へのグラデーションヘッダー、全幅、カードベースのレイアウト、折りたたみ可能なセクション

レポート HTML のスタイル — 必須

生成する HTML では、すべてのスキルで共通のエディトリアルデザインシステムを必ず使用してください。 温かみのあるオフホワイトの背景、セリフ体のディスプレイタイトル、赤から黒へのグラデーションヘッダー、 ホバー時に下線が表示されるテキストリンクのナビゲーションを採用します。コーポレートブルーの装飾、 中央揃えのヘッダー、別のグラデーションは使用しないでください。

template.html を読み込み、そのまま使用してください。Google Fonts の <link> タグ、 完全な CSS ブロック、<header> の構造が含まれています。 <head> ブロックを生成するレポートの <head> に貼り付け、<header> ブロックを <body> の先頭に貼り付けて、 {ORG_NAME}、{DIMENSION_COUNT}、{DATE_RANGE}、{DATA_VIEW_NAME}、{DATE} の各プレースホルダーに値を入力してください。スタイルを独自に変更しないでください。

{ORG_NAME} は顧客のブランド名を指します（ — Prod、 - Demo、 MCP、 Stage などの技術的な接尾辞は削除します）。タイトルにベンダー名や製品名を代入しないでください。タイトルはすべて白で表示し、単語を赤くしないでください。 ディメンションが 1 つのレポートでは、h1 を {ORG_NAME} {DIMENSION_NAME} Report に置き換えてください。

セクションタイトル — フェーズ番号なし：HTML レポートのセクション見出しにフェーズ番号を含めないでください。セクション名のみを使用します。

• ✅ 「Cardinality」—「Phase 1 — Cardinality」ではありません
• ✅ 「Distribution & Skew」—「Phase 2 — Distribution & Skew」ではありません
• ✅ 「Trends」—「Phase 3 — Trends」ではありません
• ✅ 「Data Quality」—「Phase 5 — Data Quality / Errors」ではありません

Markdown レポート

次の内容を含むテキストベースのレポートです。

• すべてのディメンションをまとめたサマリー表
• インライン表を含む、ディメンションごとの詳細分析セクション
• 異常のログ
• 根拠を添えた推奨事項

scripts/cja_dimension_analysis.py が使用する JSON スキーマは、上記の各フェーズにある Store: {...} の形式から導出されます。このスクリプトは独自の入力仕様を把握しているため、フェーズごとの Store エントリに合わせて JSON を作成してください。

対話例

「『Marketing Channel』ディメンションのパフォーマンスを分析し、デバイスタイプ別に分類してもらえますか？」

1. セットアップ： findDataViews でデータビューを確認します。setDefaultSessionDataViewId を呼び出します。
2. ディメンションの検出： findDimensions を呼び出して「Marketing Channel」ディメンションとその ID を特定します。searchDimensionItems で存在とデータの有無を確認します。
3. 分析： runReport を実行し、過去 30 日間の Marketing Channel のパフォーマンス（訪問数、コンバージョン数、売上）を取得します。上位と下位のパフォーマンスを特定します。
4. 内訳： 2 つ目のレポートを実行し、Marketing Channel を Device Type ディメンションとクロス集計して、モバイルとデスクトップの傾向を明らかにします。
5. レポート： Python 分析スクリプトを実行して、インタラクティブな HTML レポートを生成します。レポートを開き、主な調査結果を要約します。「Email はトラフィックの 12% にすぎないにもかかわらず、コンバージョンの 38% を生み出しています。Paid Search のモバイルでのコンバージョン率は、デスクトップの 2 倍です。」

重要なガードレール

• ディメンション定義やプロジェクトデータは決して変更しないでください。これは読み取り専用の分析です。
• 選択した日付範囲でディメンションのデータが返されない場合は、諦める前に、より広い範囲を試してください。
• カーディナリティが非常に高いディメンション（> 50k 個の値）では、分布分析全体が切り捨てられる可能性があることを明記してください。サンプリングした上位 N 件の値を使用してください。
• ディメンションで runReport がタイムアウトした場合は、行数の上限を減らし、その制限を明記してください。
• 実行する分析と、スキップした分析を必ずユーザーに伝えてください。
• ディメンションの数が多い場合（> 20 個）は、まずフェーズ 1～2 を実行し、対象を絞った詳細分析に進むかユーザーに確認してください。
• フェーズの進行状況をユーザーに伝えてください。「フェーズ 1 完了（5 個のディメンションのカーディナリティ）。フェーズ 2（分布）を実行中です……」