narrative-text-visualization

ナラティブテキスト可視化スキル

このスキルでは、データを構造化されたナラティブテキストの可視化に変換するワークフローを、T8 Syntax（セマンティックなエンティティ注釈を付けてデータナラティブを作成する宣言型の Markdown 風言語）を使って紹介します。

T8 とは

T8 は、インサイトに基づくナラティブテキストの表示に特化して設計された、AntV 技術スタックのテキスト可視化ソリューションです。DOM 要素を手動で構築する代わりに、データナラティブを記述する、シンプルで人が読みやすい構文を記述します。

主な機能：

• LLM に適した設計：構文が直感的で、AI モデルが簡単に生成できます
• 宣言型で読みやすい：構築方法ではなく、実現したい内容を記述します
• フレームワークに依存しない設計：React、Vue、またはバニラ JavaScript で動作します
• 標準化されたスタイル：デフォルトでプロフェッショナルな外観になります
• 組み込みのデータ可視化：ミニチャート（円グラフ、折れ線グラフ）が構文に標準で含まれています
• 軽量：gzip 圧縮前で 20KB 未満です

ワークフロー

ナラティブテキストの可視化を生成するには、次の手順に従います。

1. 要件を理解する

ユーザーのリクエストを分析し、次の点を特定します。

• 分析対象のトピックまたはデータ
• 必要なナラティブの種類（レポート、要約、記事）
• 強調すべき主要なインサイト
• 指定されたデータソースや指標

2. T8 Syntax のコンテンツを生成する

以下の仕様に従って、T8 Syntax を使用したナラティブテキストを作成します。コンテンツには次の内容を含める必要があります。

• 適切なドキュメント構造（見出し、段落、リスト）
• 意味のあるすべてのデータポイントに対するエンティティ注釈
• エンティティに適切なメタデータ（出典、評価など）

3. フロントエンドコードを生成する

ユーザーが希望するフレームワークに基づき、T8 コンテンツをレンダリングする HTML、React、または Vue のコードを作成します。

4. 出力を検証する

次の点を確認します。

• すべてのデータが信頼できるソースに基づいている
• コンテンツの長さが最小要件を満たしている（800 語、または同等の長さ）
• 全体にわたって適切なエンティティ注釈が付いている
• 構造が明確で、論理的に展開されている

---

T8 Syntax の仕様

T8 Syntax は、セマンティックなエンティティ注釈を付けてナラティブテキストを作成するための Markdown 風言語です。データ分析レポートを、より表現豊かで視覚的に魅力的なものにできます。

ドキュメント構造

見出し（6 レベル）

標準的な Markdown の見出し構文を使用します。

# Level 1 Heading (Main Title)
## Level 2 Heading (Section)
### Level 3 Heading (Subsection)
#### Level 4 Heading
##### Level 5 Heading
###### Level 6 Heading

ルール：

• 各見出しは独立した行に記述します
• # 記号の後に半角スペースを 1 つ入れます
• 見出しによって、レンダリング後の出力に視覚的な階層が生まれます

段落

通常のテキスト段落は、空行で区切ります。

This is the first paragraph with some content.

This is the second paragraph, separated by a blank line.

ルール：

• 段落は複数行にわたって記述できます
• 個別の段落は空行で区切ります
• 段落内のテキストは自然につながります

リスト

T8 Syntax は、順序なしリストと順序付きリストの両方をサポートしています。

順序なしリスト：

- First item
- Second item
- Third item

順序付きリスト：

1. First step
2. Second step
3. Third step

ルール：

• 各リスト項目は独立した行に記述します
• 箇条書き記号（-、*）または番号の後に半角スペースを 1 つ入れます
• リストにはエンティティとテキスト書式を含めることができます

テキストの書式設定

T8 Syntax は、Markdown 構文を使ったインラインのテキスト書式設定をサポートしています。

太字： This is **bold text** that stands out.

斜体： This is *italic text* for emphasis.

下線： This is __underlined text__ for importance.

リンク： Visit [our website](https://example.com) for more information.

ルール：

• 書式マーカーは開始と終了が対になっている必要があります
• エンティティと書式設定を組み合わせることができます
• リンクには [text](URL) 構文を使用します。URL は http://、https://、または / で始まります

エンティティ注釈の構文

T8 Syntax の中核となる機能はエンティティ注釈です。特定のデータポイントにセマンティックな意味とメタデータを付与します。

基本的なエンティティ構文

[displayText](entityType)

• displayText：読者に表示されるテキスト
• entityType：このエンティティのセマンティックな種類

例：

The [sales revenue](metric_name) reached [¥1.5 million](metric_value) this quarter.

メタデータ付きエンティティ

[displayText](entityType, key1=value1, key2=value2, key3="string value")

メタデータのルール：

• 複数のメタデータフィールドはカンマで区切ります
• 数値とブール値：そのまま記述します（例：origin=1500000、active=true）
• 文字列：二重引用符で囲みます（例：unit="元"、region="Asia"）

例：

Revenue grew by [15.3%](ratio_value, origin=0.153, assessment="positive") compared to last year.

エンティティタイプのリファレンス

次のエンティティタイプを使用して、さまざまな種類のデータに注釈を付けます。

エンティティタイプ	説明	使用するタイミング	例
metric_name	指標または KPI の名前	測定対象を示す場合	"売上高"、"ユーザー数"、"市場シェア"
metric_value	主要な指標値	報告する主な数値／値	"¥150万"、"50,000人のユーザー"、"250単位"
other_metric_value	補助的な指標値	背景情報を提供する追加の指標	"平均注文額：$120"
delta_value	絶対的な変化／差	期間間の数値変化を示す場合	"+1,200単位"、"-$50K"、"500増加"
ratio_value	変化率／割合	割合の変化を示す場合	"+15.3%"、"-5.2%"、"23%増加"
contribute_ratio	貢献率	何かが占める割合を示す場合	"45%を占める"、"全体の30%を占める"
trend_desc	トレンドの説明	変化の方向やパターンを説明する場合	"着実に上昇"、"減少傾向"、"安定"
dim_value	次元値／カテゴリ	地理、カテゴリ、またはセグメントのデータ	"北米"、"エンタープライズセグメント"、"第3四半期"
time_desc	期間またはタイムスタンプ	発生時期を指定する場合	"2024年第3四半期"、"1月〜3月"、"2023会計年度"
proportion	比率または割合	全体に対する部分を表す場合	"5つのうち3つ"、"顧客の60%"
rank	順位または位置	リスト内の順序や位置を示す場合	"1位にランクイン"、"トップ3"、"5位"
difference	比較上の差	2つの項目間の違いを強調する場合	"$50Kの差"、"200単位の差"
anomaly	異常値または予期しない値	外れ値や異常を指摘する場合	"異常な急上昇"、"予期しない減少"
association	関係または相関	指標間のつながりを説明する場合	"強い相関がある"、"関連している"、"関係がある"
distribution	データの分布パターン	データの広がり方を説明する場合	"均等に分布"、"〜に集中"、"〜全体に広がる"
seasonality	季節的なパターンまたはトレンド	繰り返される季節的なパターンを説明する場合	"季節的なピーク"、"ホリデー期間"、"第4四半期の急増"

一般的なメタデータフィールド

データの背景情報をより豊かにするため、次の任意フィールドを追加します。

origin（数値）

表示テキストの元となる生の数値です。

例：

• [¥1.5M](metric_value, origin=1500000)
• [23.7%](ratio_value, origin=0.237)
• [5.2K users](metric_value, origin=5200)
• [3 out of 4](proportion, origin=0.75)

使用する理由： データの可視化、並べ替え、計算が可能になります

assessment (文字列)

変更がポジティブ、ネガティブ、またはニュートラルであるかを評価します。

有効な値: "positive"、"negative"、"equal"、"neutral"

例:

• [15%増加](ratio_value, assessment="positive")
• [8%下落](ratio_value, assessment="negative")
• [横ばい](trend_desc, assessment="equal")

使用する理由: 良好/悪化のトレンドを示す視覚的インジケーター (色、アイコン) を有効にします

unit (文字列)

値の測定単位です。

例:

• [¥1,500,000](metric_value, unit="元", origin=1500000)
• [150](metric_value, unit="units")

detail (任意)

チャート描画のための追加コンテキストまたは内訳データです。特定のエンティティタイプでは必須です。

これらのエンティティタイプでは必須:

• rank: ランキングデータを表す数値の配列
  • 例: [トップパフォーマー](rank, detail=[5, 8, 12, 15, 20])
• difference: 比較値を示す数値の配列
  • 例: [差の縮小](difference, detail=[100, 80, 60, 40])
• anomaly: 外れ値を強調する数値の配列
  • 例: [異常な急増](anomaly, detail=[10, 12, 11, 45, 13])
• association: 相関データ用の {x, y} オブジェクトの配列
  • 例: [強い相関](association, detail=[{"x":1,"y":2},{"x":2,"y":4},{"x":3,"y":6}])
• distribution: データの広がりを示す数値の配列
  • 例: [不均一な分布](distribution, detail=[5, 15, 45, 25, 10])
• seasonality: データ配列とオプションの範囲を持つオブジェクト
  • 例: [Q4のピーク](seasonality, detail={"data":[10,12,15,30],"range":[0,40]})

その他のタイプではオプション:

• [着実な成長](trend_desc, detail=[100, 120, 145, 180, 210])

---

データ要件

重要: すべてのデータは公的に信頼できる情報源からのものでなければなりません:

• 公式発表/財務報告書
• 権威あるメディア (Reuters、Bloomberg、TechCrunch など)
• 業界調査機関 (IDC、Canalys、Counterpoint Research など)
• 架空、AI が推測した、またはシミュレートされたデータは絶対に使用しないでください
• 曖昧な概算ではなく、具体的な数値 (例: 「1億4600万台」、「7058台」) を使用してください

---

完全な T8 構文の例

# 2024 Smartphone Market Analysis

## Market Overview

Global [smartphone shipments](metric_name) reached [1.2 billion units](metric_value, origin=1200000000) in [2024](time_desc), showing a [modest decline of 2.1%](ratio_value, origin=-0.021, assessment="negative") year-over-year.

The **premium segment** (devices over $800) showed *remarkable* [resilience](trend_desc, assessment="positive"), growing by [5.8%](ratio_value, origin=0.058, assessment="positive"). [Average selling price](other_metric_value) was [$420](metric_value, origin=420, unit="USD").

## Key Findings

1. [Asia-Pacific](dim_value) remains the __largest market__
2. [Premium devices](dim_value) showed **strong growth**
3. Budget segment faced *headwinds*

## Regional Breakdown

### Asia-Pacific

[Asia-Pacific](dim_value) remains the largest market with [680 million units](metric_value, origin=680000000) shipped, though this represents a [decline of 180 million units](delta_value, origin=-180000000, assessment="negative") from the previous year.

Key markets:
- [China](dim_value): [320M units](metric_value, origin=320000000) - down [8.5%](ratio_value, origin=-0.085, assessment="negative"), [ranked 1st](rank, detail=[320, 180, 90, 65, 45]) globally, accounting for [47%](contribute_ratio, origin=0.47, assessment="positive") of regional sales
- [India](dim_value): [180M units](metric_value, origin=180000000) - up [12.3%](ratio_value, origin=0.123, assessment="positive"), [ranked 2nd](rank, detail=[320, 180, 90, 65, 45])
- [Southeast Asia](dim_value): [180M units](metric_value, origin=180000000) - [stable](trend_desc, assessment="equal")

For detailed methodology, visit [our research page](https://example.com/methodology).

---

HTML、React、Vue での T8 の使用

HTML での使用 (CDN 経由)

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>T8 Narrative Text</title>
</head>
<body>
  <div id="container"></div>

  
  <script src="https://unpkg.com/@antv/t8/dist/t8.min.js"></script>
  
  <script>
    // T8 is available as a global variable
    const { Text } = window.T8;

    // Initialize T8 instance
    const text = new Text(document.getElementById('container'));

    // Render narrative text using T8 Syntax
    const narrativeText = `
# Sales Report

This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).

[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
    `;

    text.theme('light').render(narrativeText);
  </script>
</body>
</html>

インストール:

npm install @antv/t8
# or
yarn add @antv/t8

React での使用

import { Text } from '@antv/t8';
import { useEffect, useRef } from 'react';

function T8Component() {
  const containerRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!containerRef.current) return;

    // Initialize T8 instance
    const text = new Text(containerRef.current);

    // Render narrative text using T8 Syntax
    const narrativeText = `
# Sales Report

This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).

[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
    `;

    text.theme('light').render(narrativeText);

    // Cleanup on unmount
    return () => {
      text.unmount();
    };
  }, []);

  return <div ref={containerRef} />;
}

export default T8Component;

Vue 3 での使用

<template>
  <div ref="containerRef"></div>
</template>

<script setup lang="ts">
import { Text } from '@antv/t8';
import { ref, onMounted, onBeforeUnmount } from 'vue';

const containerRef = ref<HTMLDivElement>();
let textInstance: Text | null = null;

onMounted(() => {
  if (!containerRef.value) return;

  // Initialize T8 instance
  textInstance = new Text(containerRef.value);

  // Render narrative text using T8 Syntax
  const narrativeText = `
# Sales Report

This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).

[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
  `;

  textInstance.theme('light').render(narrativeText);
});

onBeforeUnmount(() => {
  if (textInstance) {
    textInstance.unmount();
  }
});
</script>

Vue 2 での使用

<template>
  <div ref="container"></div>
</template>

<script>
import { Text } from '@antv/t8';

export default {
  name: 'T8Component',
  data() {
    return {
      textInstance: null,
    };
  },
  mounted() {
    // Initialize T8 instance
    this.textInstance = new Text(this.$refs.container);

    // Render narrative text using T8 Syntax
    const narrativeText = `
# Sales Report

This quarter, [bookings](metric_name) are higher than usual. They are [¥348k](metric_value, origin=348.12).

[Bookings](metric_name) are up [¥180.3k](delta_value, assessment="positive") relative to the same time last quarter.
    `;

    this.textInstance.theme('light').render(narrativeText);
  },
  beforeDestroy() {
    if (this.textInstance) {
      this.textInstance.unmount();
    }
  },
};
</script>

---

執筆ガイドラインとベストプラクティス

コンテンツ要件

1. 最小文字数: 800 語以上 (データの複雑さに応じて調整)
2. 構造: 論理的な流れを持つ明確な階層
3. 分析: 数値を並べるだけでなく、その重要性と文脈を説明する
4. トーン: 自然で流暢、客観的かつプロフェッショナル
5. エンティティの使用: 意味のあるすべてのデータポイント (指標、値、トレンド、時間、変化、パーセンテージ) に注釈を付ける

エンティティ注釈のベストプラクティス

1. 網羅的に: 主要な数値だけでなく、すべての定量的データをマークする
2. 適切なタイプを使用: 意味的な意味を最もよく表すエンティティタイプを選択する
3. メタデータを追加: 該当する場合は origin、assessment、その他の関連フィールドを含める
4. 自然な流れ: エンティティは読みやすい文章にシームレスに溶け込むべきです

注釈を付ける対象

✅ 注釈を付ける:

• すべての数値 (売上高、件数、測定値)
• すべてのパーセンテージ (変化、寄与、割合)
• 指標名と KPI
• 期間
• 地理的地域とカテゴリ
• トレンドの説明
• 比較と変化

❌ 注釈を付けない:

• 特定のデータ的意味を持たない一般的なテキスト
• 接続詞やつなぎのフレーズ
• 測定可能な概念を表さない文脈

---

出力形式

ユーザー向けに T8 Syntax のコンテンツを生成する場合：

1. コードブロックで囲まず、T8 Syntax のコンテンツを直接出力します
2. ユーザーの希望に応じて、フロントエンドのコード（HTML/React/Vue）を提供します
3. すべてのエンティティに適切なメタデータが付与されていることを確認します
4. コンテンツが最低限の長さと品質要件を満たしていることを確認します

レンダリングされた出力には、次の要素が含まれます：

• データエンティティの豊富なセマンティックマークアップ
• インタラクティブなエンティティのハイライト表示
• 明確な視覚的階層
• プロフェッショナルなレポート形式の書式
• あらゆるデバイスに対応するレスポンシブデザイン

---

参考リンク

• T8 GitHub リポジトリ：https://github.com/antvis/T8
• T8 ドキュメント：https://github.com/antvis/T8/blob/main/site/en/tutorial/quick-start.md
• T8 Syntax リファレンス：https://github.com/antvis/T8/blob/main/prompt.md