Back to Details

cja-dimension-analysis

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CJA Dimension Analysis

CJA 维度分析

Analyze one or more CJA dimensions to understand their cardinality, distribution, trends, anomalies, data quality issues, and forecasts. Produces an actionable report that helps teams understand what's inside their dimensions and where to focus attention.
分析一个或多个CJA维度，了解其基数、分布、趋势、异常、数据质量问题及预测结果。生成可执行报告，帮助团队了解维度内部情况并确定关注重点。

Workflow

工作流程

Execute phases in order. Each phase is selectable — the user can ask for a subset (e.g., "just cardinality and errors") or the full analysis. Default is all phases.
按顺序执行各个阶段。每个阶段均可选择——用户可要求仅运行子集分析（例如“只分析基数和错误”）或完整分析，默认运行全部阶段。

Phase 0 — Setup

阶段0 — 准备工作

  1. Call 
    findDataViews
    to list available data views. If the user hasn't specified one, ask which data view to analyze. Set it with 
    setDefaultSessionDataViewId
    .
  2. Ask which dimensions to analyze. Options:
    • Named dimensions: "Analyze Page Name and Browser Type"
    • By ID: user provides dimension IDs directly
    • All dimensions: warn that this may be slow; ask for a limit (default: top 50 by name)
  3. Ask which analyses to run (or confirm "all" as the default):
    • Cardinality, Distribution/Skew, Trends, Anomalies, Data Quality, Comparisons, Forecasting
  4. Ask for the date range. If the user hasn't specified one, test a few ranges to find data:
    • Try last 30 days, last 90 days, last 6 months, last year — use the first that returns rows.
  5. Ask for the primary metric to use for distribution/skew (default: occurrences or visits).
  6. Confirm the plan with the user before proceeding.
  1. 调用
    findDataViews
    列出可用数据视图。如果用户未指定数据视图，询问要分析的视图，并通过
    setDefaultSessionDataViewId
    设置。
  2. 询问要分析的维度，选项包括：
    • 指定维度名称：“分析页面名称和浏览器类型”
    • 通过ID指定：用户直接提供维度ID
    • 所有维度：提醒用户此操作可能较慢，并询问限制数量（默认：按名称取前50个）
  3. 询问要运行的分析类型（或确认默认的“全部”）：
    • 基数、分布/倾斜、趋势、异常、数据质量、对比、预测
  4. 询问日期范围。如果用户未指定，尝试多个范围以找到数据：
    • 尝试过去30天、90天、6个月、1年——使用第一个返回数据的范围。
  5. 询问用于分布/倾斜分析的主指标（默认：出现次数或访问量）。
  6. 在开始执行前与用户确认计划。

Phase 1 — Cardinality

阶段1 — 基数分析

For each dimension:
  1. Call 
    searchDimensionItems(dimensionId, limit: 50000)
    to estimate unique value count, or 
    runReport
    with the dimension as rows and a count metric to get row count.
  2. Classify cardinality:
    LevelThreshold
    LOW< 100 unique values
    MEDIUM100 – 1,000
    HIGH1,000 – 10,000
    VERY HIGH> 10,000
  3. Track cardinality over time (optional): 
    runReport
    with dimension + date breakdown; count unique dimension values per day/week to see cardinality growth trend.
  4. Flag HIGH and VERY HIGH dimensions with performance recommendations.
Store: 
{dimensionId, name, uniqueValueCount, cardinalityLevel, cardinalityTrend}
针对每个维度：
  1. 调用
    searchDimensionItems(dimensionId, limit: 50000)
    估算唯一值数量，或调用
    runReport
    将维度作为行并使用计数指标获取行数。
  2. 分类基数等级：
    等级阈值
    低< 100个唯一值
    中100 – 1,000
    高1,000 – 10,000
    极高> 10,000
  3. 跟踪基数随时间的变化（可选）：调用
    runReport
    并按维度+日期拆分；统计每天/每周的唯一维度值数量，查看基数增长趋势。
  4. 标记高和极高基数的维度并给出性能建议。
存储数据：
{dimensionId, name, uniqueValueCount, cardinalityLevel, cardinalityTrend}

Phase 2 — Distribution & Skew

阶段2 — 分布与倾斜分析

For each dimension:
  1. runReport
    with dimension as rows + primary metric (e.g., occurrences/visits). Request at least 50 rows to capture the distribution shape.
  2. Compute top-N % share (top 1, 5, 10), Gini coefficient, and cumulative distribution.
  3. Classify skew:
    LabelCondition
    Extreme skewTop 1 value > 50% of total
    High skewTop 1 value > 30% of total
    ModerateTop 5 values < 70% of total
    Long tailTop 10 values < 50% of total
  4. Note: per-value breakdown with percentage and cumulative %.
Store: 
{dimensionId, distribution: [{value, metric, pct, cumulative}], gini, skewLabel, top1Pct, top5Pct, top10Pct}
针对每个维度：
  1. 调用
    runReport
    将维度作为行+主指标（例如：出现次数/访问量）。请求至少50行以捕捉分布形态。
  2. 计算Top-N占比（Top 1、5、10）、基尼系数和累积分布。
  3. 分类倾斜程度：
    标签条件
    极端倾斜Top 1值占总量的比例 > 50%
    高度倾斜Top 1值占总量的比例 > 30%
    中度倾斜Top 5值占总量的比例 < 70%
    长尾分布Top 10值占总量的比例 < 50%
  4. 记录：每个值的细分数据，包括占比和累积占比。
存储数据：
{dimensionId, distribution: [{value, metric, pct, cumulative}], gini, skewLabel, top1Pct, top5Pct, top10Pct}

Phase 3 — Trends

阶段3 — 趋势分析

For each dimension:
  1. runReport
    with dimension + date granularity (day or week depending on range). Compare two periods: first half vs second half of the selected date range.
  2. Identify:
    • New values: appeared in period 2 but not period 1
    • Disappeared values: present in period 1, absent in period 2
    • Growth: metric in period 2 > metric in period 1 by > 10%
    • Decline: metric in period 2 < metric in period 1 by > 10%
    • Stable: < 10% change between periods
  3. Assign trend badges per value: 🟢 Growing | 🔴 Declining | 🟡 Stable | 🆕 New | ⬜ Disappeared
Store: 
{dimensionId, periodComparison: {period1, period2, changes: [{value, p1Metric, p2Metric, pctChange, badge}]}, newValues: [], disappearedValues: []}
针对每个维度：
  1. 调用
    runReport
    并按维度+日期粒度（根据范围选择日或周）拆分。比较两个时段：所选日期范围的前半段与后半段。
  2. 识别：
    • 新增值：在时段2出现但时段1未出现的值
    • 消失值：在时段1存在但时段2不存在的值
    • 增长：时段2的指标比时段1增长超过10%
    • 下降：时段2的指标比时段1下降超过10%
    • 稳定：两个时段间变化小于10%
  3. 为每个值分配趋势标识：🟢 增长中 | 🔴 下降中 | 🟡 稳定 | 🆕 新增 | ⬜ 已消失
存储数据：
{dimensionId, periodComparison: {period1, period2, changes: [{value, p1Metric, p2Metric, pctChange, badge}]}, newValues: [], disappearedValues: []}

Phase 4 — Anomalies

阶段4 — 异常分析

For each dimension:
  1. From the Phase 3 time-series, compute rolling mean and stddev per dimension value.
  2. Z-score detection: flag (value, date) pairs where the z-score exceeds the threshold (default: 2.0; sensitive: 1.5; conservative: 3.0).
  3. Threshold alerts:
    • Any single value holding > 50% of total metric on a given day
    • Value count that is > 2× the rolling average for that value
  4. New/disappeared alerts: flag values that appear or disappear mid-period (from Phase 3).
  5. Collect: anomaly type (spike, drop, new, disappeared, threshold), dimension value, date, magnitude.
Store: 
{dimensionId, anomalies: [{value, date, type, magnitude, zScore}]}
针对每个维度：
  1. 从阶段3的时间序列中，计算每个维度值的滚动均值和标准差。
  2. Z-score检测：标记Z-score超过阈值的（值，日期）对（默认阈值：2.0；敏感阈值：1.5；保守阈值：3.0）。
  3. 阈值告警：
    • 某一天中单个值占总指标的比例 > 50%
    • 值的计数超过该值滚动平均值的2倍
  4. 新增/消失告警：标记时段中期出现或消失的值（来自阶段3）。
  5. 收集信息：异常类型（峰值、骤降、新增、消失、阈值触发）、维度值、日期、幅度。
存储数据：
{dimensionId, anomalies: [{value, date, type, magnitude, zScore}]}

Phase 5 — Data Quality / Errors

阶段5 — 数据质量/错误分析

For each dimension:
  1. Search for known bad values using 
    searchDimensionItems
    : 
    • "Unspecified"
      , 
      "None"
      , 
      "(empty)"
      , 
      ""
      , 
      "null"
      , 
      "undefined"
      , 
      "N/A"
      , 
      "unknown"
  2. Count occurrences with 
    runReport
    filtering to each known bad value.
  3. Compute: missing data % = (sum of bad value occurrences) / total occurrences.
  4. Flag: dimensions where missing data > 5% (warning), > 20% (critical).
  5. If the dimension has an expected format (URL, email, date), note it — but don't auto-validate patterns unless the user asks.
Store: 
{dimensionId, errorPatterns: [{pattern, count, pct}], missingDataPct, missingDataSeverity}
针对每个维度：
  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}

Phase 6 — Comparisons (multi-dimension or time-period)

阶段6 — 对比分析（多维度或时段对比）

This phase runs when the user is analyzing 2+ dimensions OR requests period comparison.
Side-by-side (2–3 dimensions):
  1. For each dimension pair, compare cardinality level, skew, top-5 values, error rate.
  2. Produce a comparison table: dimension A vs B vs C on each metric.
Time-period comparison (single dimension):
  1. Compare two custom date ranges provided by the user (or auto-detect: first half vs second half).
  2. For each value: metric in period 1, metric in period 2, delta, % change.
  3. Surface the biggest movers (top 5 growing, top 5 declining).
Store: 
{comparisons: [{type, dimensions or periods, table}]}
当用户分析2个及以上维度或请求时段对比时运行此阶段。
并列对比（2-3个维度）：
  1. 针对每对维度，对比基数等级、倾斜程度、Top5值、错误率。
  2. 生成对比表格：维度A、B、C在各指标上的对比情况。
时段对比（单个维度）：
  1. 对比用户提供的两个自定义日期范围（或自动检测：前半段 vs 后半段）。
  2. 针对每个值：时段1的指标、时段2的指标、差值、变化百分比。
  3. 突出显示变化最大的项（Top5增长项、Top5下降项）。
存储数据：
{comparisons: [{type, dimensions or periods, table}]}

Phase 7 — Forecasting

阶段7 — 预测分析

For each dimension with sufficient time-series data (>= 7 data points):
  1. For the top 5–10 values by metric, fit a linear regression to the time series.
  2. Project 7 periods forward.
  3. Report:
    • Trend direction: Upward / Downward / Flat (based on slope)
    • Confidence: High (R² > 0.7), Medium (0.4–0.7), Low (< 0.4)
    • Projected value at end of forecast window
  4. Flag values with strong upward trend (might become dominant) or strong downward trend (might disappear soon).
Store: 
{dimensionId, forecasts: [{value, slope, r2, direction, confidence, projectedValues: []}]}
针对每个有足够时间序列数据的维度（>=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: []}]}

Phase 8 — Report Generation

阶段8 — 报告生成

After all analysis phases complete:
  1. Save all collected data to a JSON file: 
    dimension_analysis_results_YYYY-MM-DD_HH-MM.json
    (in a temp output directory, e.g. 
    /tmp/cja-dimension-analysis/
    , or a path the user specifies)
  2. Run the Python report generator:
    bash
    python3 scripts/cja_dimension_analysis.py \
  <analysis_json> \
  "<data_view_name>" \
  "<data_view_id>" \
  [output_directory] \
  [--format=html|markdown] \
  [--keep-analyses=N]
    Options:
    • --format=html
      (default): Interactive HTML dashboard with Chart.js visualizations
    • --format=markdown
      : Comprehensive text-based report with tables
    • --keep-analyses=N
      (default: 0 = keep all): Auto-cleanup of old analysis files
  3. The script generates a second output file: the report (HTML or markdown).
  4. Open with 
    open <output_directory>/dimension_analysis_report_*.html
  5. Present the report path to the user and summarize key findings:
    • Dimensions with HIGH/VERY HIGH cardinality
    • Dimensions with extreme or high skew
    • Any anomalies found
    • Data quality issues above warning threshold
    • Forecast trends worth watching
完成所有分析阶段后：
  1. 将所有收集的数据保存到JSON文件： 
    dimension_analysis_results_YYYY-MM-DD_HH-MM.json
    （保存到临时输出目录，例如
    /tmp/cja-dimension-analysis/
    ，或用户指定的路径）
  2. 运行Python报告生成器：
    bash
    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格式）。
  4. 使用
    open <output_directory>/dimension_analysis_report_*.html
    打开报告
  5. 向用户展示报告路径并总结关键发现：
    • 高/极高基数的维度
    • 极端或高度倾斜的维度
    • 发现的任何异常
    • 超过警告阈值的数据质量问题
    • 需要关注的预测趋势

CJA MCP Tools Used

使用的CJA MCP工具

ToolPhasePurpose
findDataViews
0List available data views
setDefaultSessionDataViewId
0Set active data view for session
findDimensions
0Discover dimensions by name/search
describeDimension
0Get dimension metadata and ID
searchDimensionItems
1, 5Count unique values; search for specific items (error patterns)
runReport
1–7Primary data engine: dimension rows + metric, with optional date breakdown
工具阶段用途
findDataViews
0列出可用数据视图
setDefaultSessionDataViewId
0设置会话的活跃数据视图
findDimensions
0通过名称/搜索发现维度
describeDimension
0获取维度元数据和ID
searchDimensionItems
1, 5统计唯一值数量；搜索特定项（错误模式）
runReport
1–7核心数据引擎：维度行+指标，可选择按日期拆分

Output Format

输出格式

HTML Dashboard (default)

HTML仪表盘（默认）

Interactive report with:
  • Executive summary cards (total dimensions, flagged dimensions, critical issues)
  • Per-dimension sections: cardinality badge, distribution chart (Chart.js bar), skew metrics, trend table, anomaly list, data quality indicators
  • Comparison section (if multiple dimensions or period comparison requested)
  • Forecast section (if forecasting was run)
  • Recommendations panel: grouped by priority (critical → warning → info)
  • Design: dark navy-to-blue gradient header, full-width, card-based layout, collapsible sections
交互式报告包含：
  • 执行摘要卡片（总维度数、标记的维度数、严重问题）
  • 每个维度的详情部分：基数标识、分布图表（Chart.js柱状图）、倾斜指标、趋势表格、异常列表、数据质量指标
  • 对比部分（如果请求了多维度或时段对比）
  • 预测部分（如果运行了预测分析）
  • 建议面板：按优先级分组（严重→警告→信息）
  • 设计：深海军蓝到蓝色渐变头部，全宽，卡片式布局，可折叠部分

Report HTML Style — Required

报告HTML样式要求

The generated HTML must use the editorial design system shared across all skills: warm off-white surface, serif display title, red-on-black gradient header, and underline-on-hover text-link nav. Do not introduce corporate-blue chrome, centered headers, or alternative gradients.
Read 
template.html
 and use it verbatim. It contains the Google Fonts 
<link>
tags, the full CSS block, and the 
<header>
structure. Paste the 
<head>
block into the generated report's 
<head>
, paste the 
<header>
block at the top of 
<body>
, and fill in the 
{ORG_NAME}
, 
{DIMENSION_COUNT}
, 
{DATE_RANGE}
, 
{DATA_VIEW_NAME}
, and 
{DATE}
placeholders. Do not improvise the styling.
Where 
{ORG_NAME}
is the customer's brand name (with technical suffixes like 
 — Prod
, 
 - Demo
, 
 MCP
, 
 Stage
stripped). Never substitute a vendor or product name into the title. The title is all white — do not color any word red. For single-dimension reports, replace the h1 with 
{ORG_NAME} {DIMENSION_NAME} Report
.
Section titles — no phase prefix: Section headings in the HTML report must not include the phase number. Use the plain section name only:
  • ✅ "Cardinality" — not "Phase 1 — Cardinality"
  • ✅ "Distribution & Skew" — not "Phase 2 — Distribution & Skew"
  • ✅ "Trends" — not "Phase 3 — Trends"
  • ✅ "Data Quality" — not "Phase 5 — Data Quality / Errors"
生成的HTML必须使用所有Skill共享的编辑设计系统：暖白色背景，衬线标题字体，红黑渐变头部，悬带下划线的文本链接导航。请勿使用企业蓝色边框、居中头部或其他渐变。
阅读并直接使用
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
）。标题中不得替换为供应商或产品名称。标题为纯白色——请勿将任何文字设为红色。对于单维度报告，将h1替换为
{ORG_NAME} {DIMENSION_NAME} Report
。
章节标题——无阶段前缀：HTML报告中的章节标题不得包含阶段编号。仅使用章节的纯名称：
  • ✅ “基数分析”——而非“阶段1 — 基数分析”
  • ✅ “分布与倾斜”——而非“阶段2 — 分布与倾斜”
  • ✅ “趋势分析”——而非“阶段3 — 趋势分析”
  • ✅ “数据质量”——而非“阶段5 — 数据质量/错误分析”

Markdown Report

Markdown报告

Text-based report with:
  • Summary table across all dimensions
  • Per-dimension deep-dive sections with inline tables
  • Anomaly log
  • Recommendations with rationale
The JSON schema consumed by 
scripts/cja_dimension_analysis.py
is derived from the 
Store: {...}
shapes in each phase above. The script knows its own input contract; build the JSON to match the per-phase Store entries.
文本格式报告包含：
  • 所有维度的汇总表格
  • 每个维度的深入分析部分，包含内嵌表格
  • 异常日志
  • 带有理由的建议
scripts/cja_dimension_analysis.py
使用的JSON schema源自上述各阶段的
Store: {...}
结构。脚本了解自身的输入约定；构建JSON时需匹配各阶段的Store条目。

Example Interaction

交互示例

"Can you analyze how our 'Marketing Channel' dimension is performing and break it down by device type?"
  1. Setup: Confirm the data view with 
    findDataViews
    . Call 
    setDefaultSessionDataViewId
    .
  2. Dimension discovery: Call 
    findDimensions
    to locate the 'Marketing Channel' dimension and its ID. Confirm it exists and has data with 
    searchDimensionItems
    .
  3. Analysis: Run 
    runReport
    for Marketing Channel performance over the last 30 days (visits, conversions, revenue). Identify top and bottom performers.
  4. Breakdown: Run a second report cross-tabbing Marketing Channel by Device Type dimension to surface mobile vs. desktop patterns.
  5. Report: Run the Python analysis script to generate an interactive HTML report. Open it. Summarize top findings: "Email drives 38% of conversions despite only 12% of traffic. Paid Search converts 2× better on mobile than desktop."
“你能分析我们的‘营销渠道’维度表现，并按设备类型拆分吗？”
  1. 准备工作：调用
    findDataViews
    确认数据视图。调用
    setDefaultSessionDataViewId
    设置。
  2. 维度发现：调用
    findDimensions
    定位“营销渠道”维度及其ID。通过
    searchDimensionItems
    确认其存在且有数据。
  3. 分析：调用
    runReport
    分析过去30天内营销渠道的表现（访问量、转化量、收入）。识别Top和末位表现者。
  4. 拆分分析：运行第二个报告，将营销渠道与设备类型维度交叉制表，呈现移动端与桌面端的模式。
  5. 报告：运行Python分析脚本生成交互式HTML报告并打开。总结关键发现：“尽管仅占12%的流量，邮件渠道却贡献了38%的转化量。付费搜索在移动端的转化率是桌面端的2倍。”

Important Guardrails

重要约束

  • Never modify dimension definitions or project data. This is read-only analysis.
  • If a dimension returns no data for the selected date range, try a broader range before giving up.
  • For VERY HIGH cardinality dimensions (> 50k values), note that full distribution analysis may be truncated — use sampled top-N values.
  • If 
    runReport
    times out on a dimension, reduce the row limit and note the limitation.
  • Always tell the user which analyses are being run and which were skipped.
  • For large dimension sets (> 20 dimensions), run phases 1–2 first and ask if the user wants to proceed with deeper analysis on a subset.
  • Let the user know progress as you move through phases: "Phase 1 complete (cardinality for 5 dimensions). Running Phase 2 (distribution)..."
  • 切勿修改维度定义或项目数据。此为只读分析。
  • 如果维度在所选日期范围内无数据，尝试更宽的范围后再放弃。
  • 对于极高基数维度（>50k值），需注明完整分布分析可能被截断——使用抽样的Top-N值。
  • 如果
    runReport
    在某个维度上超时，减少行限制并注明此限制。
  • 始终告知用户正在运行的分析类型和跳过的分析类型。
  • 对于大型维度集（>20个维度），先运行阶段1-2，然后询问用户是否要继续对子集进行深入分析。
  • 在各阶段执行过程中向用户告知进度：“阶段1完成（5个维度的基数分析）。正在运行阶段2（分布分析）……”