hibiday/school-festival-synthetic-data

---
license: cc-by-4.0
task_categories:
- time-series-forecasting
language:
- ja
tags:
- synthetic
- simulation
- school-festival
- sales-forecasting
pretty_name: School Festival Synthetic Data
source_datasets:
- extended
configs:
- config_name: sales
default: true
data_files:
- split: train
path:
- "*_sales.csv"
- config_name: customers
data_files:
- split: train
path:
- "*_customers.csv"
- config_name: transactions
data_files:
- split: train
path:
- "*_transactions.csv"
- config_name: scenario
data_files:
- split: train
path:
- "*_scenario.json"
---

# School Festival Synthetic Data

> **Warning:** This is a hackathon prototype / Proof of Concept. Not production-ready.

Synthetic sales data for Japanese school festivals (学園祭), designed for 15-minute interval sales forecasting.

25 unique festival scenarios, each spanning 3 days, generated via an LLM-driven pipeline.

### Generation Pipeline

```
Shot 1: Identity Generation (DeepSeek-V3.2)
→ Fictional university names, festival names, school/festival descriptions

Shot 2: Scenario Generation (DeepSeek-V3.2)
→ Shop details, visitor distribution parameters, weather, operating hours

Shot 3: Wandering Pattern Generation (GPT-oss-20b)
→ Visitor shopping behavior generated from personas sampled
from Nemotron-Personas-Japan

Simulation
→ Arrival time assignment, transaction data construction

Aggregation
→ 15-min interval sales aggregation, lag feature calculation
```

### File Structure

Each sample (00001–00025) contains 4 files:

| File | Description |
|---|---|
| `XXXXX_scenario.json` | Scenario info (university settings, shop details, weather, visitor count, time distribution parameters) |
| `XXXXX_customers.csv` | Visitor personas (100 visitors/day x 3 days = 300 rows) |
| `XXXXX_transactions.csv` | Individual transaction data (visited shops, dwell time, purchase status, amount) |
| `XXXXX_sales.csv` | 15-min interval sales aggregation (main training data) |

Generation scripts are in `main.py` and `src/`.

The `00001`-`00025` files in the repository root are the published dataset snapshot.
When you rerun the generation pipeline, newly generated files are written to `output/<timestamp>/`.

### sales.csv Column Definitions

| Column | Description |
|---|---|
| `day` | Day number (1 / 2 / 3) |
| `time` | Start time of the 15-min interval (e.g., `10:00`, `10:15`) |
| `paid_count` | Number of purchase events with `purchased=True` per 15-min interval, including free / 0-JPY items |
| `paid_sales` | Total recorded purchase amount per 15-min interval (JPY). 0-JPY purchases contribute `0` |
| `basket_size` | Average recorded amount per purchase event (`paid_sales / paid_count`) |
| `admissions` | Number of visitors per 15-min interval |
| `lag96` | `paid_sales` from the same clock-time slot on the previous day. The name assumes a full 24-hour, 15-minute grid (`96` steps/day). Empty for Day 1 |
| `lag192` | `paid_sales` from the same clock-time slot 2 days prior. The name assumes a full 24-hour, 15-minute grid (`192` steps/2 days). Empty for Day 1, 2 |

In this published snapshot, `sales.csv` is not a full 24-hour series. Each day only contains slots within the scenario's operating hours, so `lag96` / `lag192` should be interpreted as same-time previous-day features rather than literal 96/192-row shifts.

Some `menu_items.price` values in `scenario.json` can be `0` (for example free items or flexible-price items). As a result, purchase events with `purchased=True` can also have `amount=0`; those events are included in `paid_count` and contribute `0` to `paid_sales`.

### scenario.json Field Definitions

Top-level fields:

| Field | Type | Description |
|---|---|---|
| `festival_name` | string | Festival name |
| `school_name` | string | University name |
| `school_description` | string | University profile (type, size, faculties, region) |
| `festival_description` | string | Festival atmosphere and highlights |
| `open_hour` | int | Opening hour (e.g., 10) |
| `close_hour` | int | Closing hour (e.g., 18) |
| `total_shops` | int | Total number of stalls at the festival (35–180) |
| `shops` | array | 20 shops sampled for simulation (see below) |
| `age_weights` | array | Visitor age distribution weights (see below) |
| `days` | array | 3-day scenarios (see below) |

`shops[]`:

| Field | Type | Description |
|---|---|---|
| `shop_id` | int | Shop ID (1–20) |
| `shop_name` | string | Shop name |
| `genre` | string | Genre (e.g., food, drink, game) |
| `location` | string | Location on campus |
| `menu_items` | array | 1–3 items, each with `name` (string), `price` (int, JPY; may be `0` for free / flexible-price items), `catchphrase` (string) |
| `popularity` | float | Popularity score (0.0–1.0) |
| `congestion` | float | Peak congestion level (0.0–1.0) |

`age_weights[]`:

| Field | Type | Description |
|---|---|---|
| `age_min` | int | Minimum age of bracket |
| `age_max` | int | Maximum age of bracket |
| `weight` | float | Proportion of visitors in this bracket (sum = 1.0) |

`days[]`:

| Field | Type | Description |
|---|---|---|
| `day` | int | Day number (1 / 2 / 3) |
| `weather` | string | Weather description (e.g., "朝は曇り、昼から晴れ、最高気温23℃") |
| `total_visitors` | float | Daily visitors in units of 10,000 |
| `arrival_dist` | array | 5 Gaussian mixture components (see below) |

`arrival_dist[]`:

| Field | Type | Description |
|---|---|---|
| `mean_hour` | float | Peak arrival hour (e.g., 12.5 = 12:30) |
| `std_hours` | float | Standard deviation in hours |
| `coefficient` | float | Weight of this component (sum = 1.0) |

### transactions.csv Column Definitions

| Column | Description |
|---|---|
| `customer_id` | Visitor ID |
| `day` | Day number |
| `shop_id` | Visited shop ID |
| `visited_at` | Visit time (decimal hours, e.g., `10.5` = 10:30) |
| `dwell_minutes` | Dwell time (minutes) |
| `purchased` | Purchase status (`True` / `False`) |
| `amount` | Recorded purchase amount (JPY). `0` if no purchase, and it may also be `0` when `purchased=True` for free / flexible-price items |

### customers.csv Column Definitions

| Column | Description |
|---|---|
| `customer_id` | Visitor ID |
| `day` | Day number |
| `uuid` | Unique persona identifier |
| `persona` | Persona summary |
| `cultural_background` | Cultural background |
| `culinary_persona` | Culinary preferences |
| `hobbies_and_interests` | Hobbies and interests |
| `age` | Age |
| `sex` | Sex |

Personas are sampled and processed from [nvidia/Nemotron-Personas-Japan](https://huggingface.co/datasets/nvidia/Nemotron-Personas-Japan) (NVIDIA, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)).

### Regenerating the Data

```bash
cp .env.example .env
# Set API keys in .env:
# OPENROUTER_API_KEY — OpenRouter (for DeepSeek-V3.2)
# GROQ_API_KEY — Groq (for GPT-oss-20b)
# HF_TOKEN — HuggingFace (for Nemotron-Personas-Japan)
uv sync
uv run main.py
```

Generated files will be saved under `output/<timestamp>/`. They do not overwrite the published snapshot in the repository root.

### License

This dataset is distributed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). See [LICENSE](LICENSE) for details.

Persona-related fields in `customers.csv` are derived from [nvidia/Nemotron-Personas-Japan](https://huggingface.co/datasets/nvidia/Nemotron-Personas-Japan) (NVIDIA, CC BY 4.0) and remain subject to attribution requirements.

For dataset limitations, biases, and intended use, see [DATASHEET.md](DATASHEET.md).

---

## 日本語ドキュメント

> **Warning:** 本プロジェクトはハッカソンで作成したプロトタイプ / Proof of Concept であり、本番利用を想定していない。

学園祭（3日間）の売上予測用合成データセット。LLM によるシナリオ生成とシミュレーションを組み合わせたパイプラインで、25パターンの学園祭データを生成している。

### 生成パイプライン

```
Shot 1: アイデンティティ生成 (DeepSeek-V3.2)
→ 架空の大学名・学園祭名・大学/学園祭の概要

Shot 2: シナリオ生成 (DeepSeek-V3.2)
→ 店舗詳細、来場者分布パラメータ、天気、開催時間

Shot 3: 回遊パターン生成 (GPT-oss-20b)
→ Nemotron-Personas-Japan からサンプリングしたペルソナをもとに
来場者ごとの店舗訪問・購買行動を生成

シミュレーション
→ 来場時刻の割り当て、取引データの構築

集計
→ 15分足での売上集計、ラグ特徴量の算出
```

### ファイル構成

各サンプル (00001〜00025) につき4ファイル:

| ファイル | 内容 |
|---|---|
| `XXXXX_scenario.json` | シナリオ情報（大学設定・店舗詳細・天気・来場者数・時間分布パラメータ） |
| `XXXXX_customers.csv` | 来場者ペルソナ（100人/日 x 3日 = 300行） |
| `XXXXX_transactions.csv` | 個別取引データ（訪問店舗・滞在時間・購買有無・金額） |
| `XXXXX_sales.csv` | 15分足売上集計（メインの学習用データ） |

生成スクリプトは `main.py` および `src/` に含まれる。

リポジトリ直下の `00001`〜`00025` は公開用のデータスナップショットであり、再生成時の出力先は `output/<timestamp>/` である。

### sales.csv カラム定義

| カラム | 説明 |
|---|---|
| `day` | 日目 (1 / 2 / 3) |
| `time` | 15分足の開始時刻 (例: `10:00`, `10:15`) |
| `paid_count` | 15分ごとの `purchased=True` の購買イベント件数。0円商品の購入を含みうる |
| `paid_sales` | 15分ごとの記録上の購入金額合計（円）。0円購入は `0` として加算される |
| `basket_size` | 購買イベントあたりの平均記録金額 (`paid_sales / paid_count`) |
| `admissions` | 15分ごとの来場者数 |
| `lag96` | 前日同時刻スロットの `paid_sales`。列名は 24時間を15分刻みで表した `96` ステップ/日を前提にしている。Day 1 は空 |
| `lag192` | 2日前同時刻スロットの `paid_sales`。列名は 24時間を15分刻みで表した `192` ステップ/2日を前提にしている。Day 1, 2 は空 |

この公開スナップショットの `sales.csv` は24時間フル系列ではなく、各日の営業時間帯のみを含む。そのため `lag96` / `lag192` は、厳密には 96/192 行前ではなく「前日/2日前の同時刻特徴量」として解釈すること。

`scenario.json` の `menu_items.price` には `0` が入りうるため（無料配布や自由料金の想定）、`purchased=True` でも `amount=0` になる購買イベントがある。これらのイベントは `paid_count` に含まれ、`paid_sales` には `0` として反映される。

### scenario.json フィールド定義

トップレベル:

| フィールド | 型 | 説明 |
|---|---|---|
| `festival_name` | string | 学園祭名 |
| `school_name` | string | 大学名 |
| `school_description` | string | 大学の概要（種別・規模・学部構成・地域） |
| `festival_description` | string | 学園祭の雰囲気・見どころ |
| `open_hour` | int | 開場時刻（例: 10） |
| `close_hour` | int | 閉場時刻（例: 18） |
| `total_shops` | int | 学園祭全体の模擬店数（35〜180） |
| `shops` | array | シミュレート対象の20店舗（詳細は下記） |
| `age_weights` | array | 来場者の年齢分布（詳細は下記） |
| `days` | array | 3日間のシナリオ（詳細は下記） |

`shops[]`:

| フィールド | 型 | 説明 |
|---|---|---|
| `shop_id` | int | 店舗ID（1〜20） |
| `shop_name` | string | 店舗名 |
| `genre` | string | ジャンル（例: フード、ドリンク、ゲーム） |
| `location` | string | キャンパス内の出店場所 |
| `menu_items` | array | 1〜3品、各メニューに `name` (string)・`price` (int, 円。無料配布や自由料金の想定で `0` を含みうる)・`catchphrase` (string) |
| `popularity` | float | 人気度（0.0〜1.0） |
| `congestion` | float | ピーク時の混雑度（0.0〜1.0） |

`age_weights[]`:

| フィールド | 型 | 説明 |
|---|---|---|
| `age_min` | int | 年齢層の下限 |
| `age_max` | int | 年齢層の上限 |
| `weight` | float | 来場者に占める割合（合計 = 1.0） |

`days[]`:

| フィールド | 型 | 説明 |
|---|---|---|
| `day` | int | 日目（1 / 2 / 3） |
| `weather` | string | 天気予報形式の記述（例: 「朝は曇り、昼から晴れ、最高気温23℃」） |
| `total_visitors` | float | 来場者数（万人単位） |
| `arrival_dist` | array | 5個の正規分布成分（詳細は下記） |

`arrival_dist[]`:

| フィールド | 型 | 説明 |
|---|---|---|
| `mean_hour` | float | ピーク来場時刻（例: 12.5 = 12時30分） |
| `std_hours` | float | 標準偏差（時間単位） |
| `coefficient` | float | 成分の重み（合計 = 1.0） |

### transactions.csv カラム定義

| カラム | 説明 |
|---|---|
| `customer_id` | 来場者ID |
| `day` | 日目 |
| `shop_id` | 訪問店舗ID |
| `visited_at` | 訪問時刻（小数時間表記、例: `10.5` = 10:30） |
| `dwell_minutes` | 滞在時間（分） |
| `purchased` | 購買有無 (`True` / `False`) |
| `amount` | 記録上の購入金額（円）。未購入時は `0` で、無料配布や自由料金の品目では `purchased=True` でも `0` になりうる |

### customers.csv カラム定義

| カラム | 説明 |
|---|---|
| `customer_id` | 来場者ID |
| `day` | 日目 |
| `uuid` | ペルソナの一意識別子 |
| `persona` | ペルソナの概要 |
| `cultural_background` | 文化的背景 |
| `culinary_persona` | 食の嗜好 |
| `hobbies_and_interests` | 趣味・関心 |
| `age` | 年齢 |
| `sex` | 性別 |

ペルソナは [nvidia/Nemotron-Personas-Japan](https://huggingface.co/datasets/nvidia/Nemotron-Personas-Japan) (NVIDIA, [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)) からサンプリング・加工したものである。

### データの再生成

```bash
git clone https://huggingface.co/datasets/hibiday/school-festival-synthetic-data
cd school-festival-synthetic-data
cp .env.example .env
# .env に API キーを設定:
# OPENROUTER_API_KEY — OpenRouter (DeepSeek-V3.2 用)
# GROQ_API_KEY — Groq (GPT-oss-20b 用)
# HF_TOKEN — HuggingFace (Nemotron-Personas-Japan 取得用)
uv sync
uv run main.py
```

生成されたファイルは `output/<timestamp>/` 配下に保存され、リポジトリ直下の公開スナップショットは上書きしない。

### ライセンス

本データセットは [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) で公開している。詳細は [LICENSE](LICENSE) を参照。

`customers.csv` のペルソナ関連フィールドは [nvidia/Nemotron-Personas-Japan](https://huggingface.co/datasets/nvidia/Nemotron-Personas-Japan) (NVIDIA, CC BY 4.0) に由来し、帰属表示要件の対象となる。