ナラティブテキストビジュアライゼーションスキル

このスキルは、T8 Syntaxを使用してデータを構造化されたナラティブテキストビジュアライゼーションに変換するためのワークフローを提供します。T8 Syntaxはセマンティックエンティティアノテーション付きでデータナラティブを作成するための宣言型Markdown風言語です。

T8とは

T8はAntVテクノロジースタック傘下のテキストビジュアライゼーションソリューションで、インサイトベースのナラティブテキスト表示専用に設計されています。DOMエレメントを手動で構築する代わりに、データナラティブを説明する単純で人間が読みやすい構文を記述します。

主な特徴:

• LLMフレンドリー: この構文は直感的で、AIモデルによって簡単に生成できます
• 宣言型で読みやすい: どう構築するかではなく、何をしたいかを書く
• フレームワークに依存しない: React、Vue、またはバニラJavaScriptで動作します
• 標準化されたスタイリング: デフォルトでプロフェッショナルな外観
• ビルトインデータビジュアライゼーション: ミニチャート(円グラフ、折れ線グラフ)は構文に組み込まれています
• 軽量: gzip前で20KB未満

ワークフロー

ナラティブテキストビジュアライゼーションを生成するには、以下の手順に従ってください:

1. 要件の理解

ユーザーのリクエストを分析して以下を決定します:

• 分析対象のトピックまたはデータ
• 必要なナラティブのタイプ(レポート、要約、記事)
• ハイライトするキーインサイト
• 特定のデータソースまたはメトリクス

2. T8 Syntaxコンテンツの生成

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

• 適切なドキュメント構造(見出し、段落、リスト)
• すべての意味のあるデータポイントのエンティティアノテーション
• エンティティの適切なメタデータ(origin、assessmentなど)

3. フロントエンドコードの生成

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

4. 出力の検証

以下を確認します:

• すべてのデータが信頼できるソースから取得されたものであること
• 最小コンテンツ長(800語相当以上)
• 全体的な適切なエンティティアノテーション
• 明確な構造と論理的な流れ

---

T8 Syntax仕様

T8 Syntaxはセマンティックエンティティアノテーション付きのナラティブテキスト作成用のMarkdown風言語です。これにより、データ分析レポートがより表現力豊かで視覚的に魅力的になります。

ドキュメント構造

見出し(6レベル)

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

# レベル1見出し(メインタイトル)
## レベル2見出し(セクション)
### レベル3見出し(サブセクション)
#### レベル4見出し
##### レベル5見出し
###### レベル6見出し

ルール:

• 各見出しは独立した行に配置する必要があります
• #シンボルの後に1つのスペースを追加します
• 見出しはレンダリング出力で視覚的な階層を作成します

段落

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

これは最初の段落で、コンテンツが含まれています。

これは2番目の段落で、空白行で区切られています。

ルール:

• 段落は複数行にまたがることができます
• 異なる段落を区切るために空白行を使用します
• 段落内のテキストは自然に流れます

リスト

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

順序なしリスト:

- 最初のアイテム
- 2番目のアイテム
- 3番目のアイテム

順序付きリスト:

1. 最初のステップ
2. 2番目のステップ
3. 3番目のステップ

ルール:

• 各リストアイテムは独立した行に配置する必要があります
• 箇条書きマーカー(-, *)または番号の後に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の名前	測定対象の言及時	"revenue", "user count", "market share"
metric_value	プライマリメトリック値	報告される主な数値/値	"¥1.5 million", "50,000 users", "250 units"
other_metric_value	二次的またはサポートメトリック値	コンテキストを提供する追加メトリック	"average order value: $120"
delta_value	絶対変更/差分	期間間での数値変更を示す時	"+1,200 units", "-$50K", "increased by 500"
ratio_value	パーセンテージ変更/レート	パーセンテージ変更を示す時	"+15.3%", "-5.2%", "grew 23%"
contribute_ratio	貢献パーセンテージ	何がパーセンテージで貢献するかを示す時	"accounts for 45%", "represents 30% of total"
trend_desc	トレンド説明	変更の方向/パターンを説明時	"steadily rising", "declining trend", "stable"
dim_value	ディメンションバリュー/カテゴリ	地理的、カテゴリ別、またはセグメンテーションデータ	"North America", "Enterprise segment", "Q3"
time_desc	時間期間またはタイムスタンプ	何かが発生した時期を指定時	"Q3 2024", "January-March", "fiscal year 2023"
proportion	比率またはレート	全体の部分を表現時	"3 out of 5", "60% of customers"
rank	ランキングまたは位置	リスト内の順序または位置を示す時	"ranked 1st", "top 3", "5th place"
difference	比較差分	2つのアイテム間の差分を強調時	"difference of $50K", "gap of 200 units"
anomaly	異常または予期しない値	外れ値または異常を指摘時	"unusual spike", "unexpected drop"
association	関係または相関	メトリック間の接続を説明時	"strongly correlated", "linked to", "related"
distribution	データ分布パターン	データがどう分散されているかを説明時	"evenly distributed", "concentrated in", "spread across"
seasonality	季節パターンまたはトレンド	繰り返される季節パターンを説明時	"seasonal peak", "holiday period", "Q4 surge"

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

以下のオプションフィールドを追加して、より豊かなデータコンテキストを提供します:

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"

例:

• [increased 15%](ratio_value, assessment="positive")
• [dropped 8%](ratio_value, assessment="negative")
• [remained flat](trend_desc, assessment="equal")

用途: 良い/悪いトレンドの視覚的インジケータ(色、アイコン)を有効にします

unit (文字列)

値の測定単位。

例:

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

detail (任意)

チャートレンダリング用の追加コンテキストまたはブレークダウンデータ。特定のエンティティ型に必須。

これらのエンティティ型に必須:

• rank: ランキングデータを表す数値の配列
  • 例: [top performer](rank, detail=[5, 8, 12, 15, 20])
• difference: 比較値を示す数値の配列
  • 例: [gap narrowing](difference, detail=[100, 80, 60, 40])
• anomaly: 外れ値をハイライトする数値の配列
  • 例: [unusual spike](anomaly, detail=[10, 12, 11, 45, 13])
• association: 相関データ用の{x, y}オブジェクトの配列
  • 例: [strong correlation](association, detail=[{"x":1,"y":2},{"x":2,"y":4},{"x":3,"y":6}])
• distribution: データスプレッドを示す数値の配列
  • 例: [uneven distribution](distribution, detail=[5, 15, 45, 25, 10])
• seasonality: データ配列とオプションの範囲を持つオブジェクト
  • 例: [Q4 peak](seasonality, detail={"data":[10,12,15,30],"range":[0,40]})

他の型ではオプション:

• [steady growth](trend_desc, detail=[100, 120, 145, 180, 210])

---

データ要件

重要: すべてのデータは公式で信頼できるソースから取得する必要があります:

• 公式発表/財務報告書
• 信頼できるメディア(Reuters、Bloomberg、TechCrunch等)
• 業界調査機関(IDC、Canalys、Counterpoint Research等)
• 虚構のデータ、AI推測データ、シミュレートされたデータは決して使用しないでください
• 曖昧な近似値ではなく、具体的な数値を使用(例: "146 million units", "7058 units")

---

完全なT8 Syntax例

# 2024年スマートフォン市場分析

## 市場概要

グローバルな[スマートフォン出荷数](metric_name)は[2024年](time_desc)に[12億ユニット](metric_value, origin=1200000000)に達し、前年比で[2.1%のわずかな減少](ratio_value, origin=-0.021, assessment="negative")を示しました。

**プレミアムセグメント**(800ドル以上のデバイス)は*顕著な*[回復力](trend_desc, assessment="positive")を示し、[5.8%成長](ratio_value, origin=0.058, assessment="positive")しました。[平均販売価格](other_metric_value)は[$420](metric_value, origin=420, unit="USD")でした。

## 主要な知見

1. [アジア太平洋](dim_value)は__最大市場__のままです
2. [プレミアムデバイス](dim_value)は**強い成長**を示しました
3. 予算セグメントは*逆風*に直面しました

## 地域別内訳

### アジア太平洋

[アジア太平洋](dim_value)は[6億8,000万ユニット](metric_value, origin=680000000)出荷で最大市場のままですが、これは前年から[1億8,000万ユニットの減少](delta_value, origin=-180000000, assessment="negative")を表しています。

主要市場:
- [中国](dim_value): [3億2,000万ユニット](metric_value, origin=320000000) - [8.5%減少](ratio_value, origin=-0.085, assessment="negative")、グローバルで[1位ランク](rank, detail=[320, 180, 90, 65, 45])、地域売上の[47%を占める](contribute_ratio, origin=0.47, assessment="positive")
- [インド](dim_value): [1億8,000万ユニット](metric_value, origin=180000000) - [12.3%増加](ratio_value, origin=0.123, assessment="positive")、[2位ランク](rank, detail=[320, 180, 90, 65, 45])
- [東南アジア](dim_value): [1億8,000万ユニット](metric_value, origin=180000000) - [安定](trend_desc, assessment="equal")

詳細な方法論については、[当社のリサーチページ](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>

  <!-- T8をunpkg CDNからインポート -->
  <script src="https://unpkg.com/@antv/t8/dist/t8.min.js"></script>
  
  <script>
    // T8はグローバル変数として利用可能です
    const { Text } = window.T8;

    // T8インスタンスを初期化
    const text = new Text(document.getElementById('container'));

    // T8 Syntaxを使用してナラティブテキストをレンダリング
    const narrativeText = `
# 売上レポート

今四半期は[予約](metric_name)がいつもより高いです。[¥348k](metric_value, origin=348.12)です。

[予約](metric_name)は前四半期の同時期と比べて[¥180.3k](delta_value, assessment="positive")増加しています。
    `;

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

インストール:

npm install @antv/t8
# または
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;

    // T8インスタンスを初期化
    const text = new Text(containerRef.current);

    // T8 Syntaxを使用してナラティブテキストをレンダリング
    const narrativeText = `
# 売上レポート

今四半期は[予約](metric_name)がいつもより高いです。[¥348k](metric_value, origin=348.12)です。

[予約](metric_name)は前四半期の同時期と比べて[¥180.3k](delta_value, assessment="positive")増加しています。
    `;

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

    // アンマウント時のクリーンアップ
    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;

  // T8インスタンスを初期化
  textInstance = new Text(containerRef.value);

  // T8 Syntaxを使用してナラティブテキストをレンダリング
  const narrativeText = `
# 売上レポート

今四半期は[予約](metric_name)がいつもより高いです。[¥348k](metric_value, origin=348.12)です。

[予約](metric_name)は前四半期の同時期と比べて[¥180.3k](delta_value, assessment="positive")増加しています。
  `;

  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() {
    // T8インスタンスを初期化
    this.textInstance = new Text(this.$refs.container);

    // T8 Syntaxを使用してナラティブテキストをレンダリング
    const narrativeText = `
# 売上レポート

今四半期は[予約](metric_name)がいつもより高いです。[¥348k](metric_value, origin=348.12)です。

[予約](metric_name)は前四半期の同時期と比べて[¥180.3k](delta_value, assessment="positive")増加しています。
    `;

    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