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) に由来し、帰属表示要件の対象となる。license: CC BY 4.0 任务类别： - 时间序列预测 语言： - 日语 标签： - 合成数据 - 模拟 - 学园祭 - 销售预测 展示名称：学园祭合成数据集 源数据集： - 扩展数据集 配置项： - 配置名称：sales 默认：是 数据文件： - 划分：训练集 路径： - "*_sales.csv" - 配置名称：customers 数据文件： - 划分：训练集 路径： - "*_customers.csv" - 配置名称：transactions 数据文件： - 划分：训练集 路径： - "*_transactions.csv" - 配置名称：scenario 数据文件： - 划分：训练集 路径： - "*_scenario.json" # 学园祭合成数据集 > **警告：** 本数据集为黑客松原型项目/概念验证产物，未经过生产级优化，请勿直接用于生产场景。 本数据集专为15分钟间隔的销售预测任务设计，包含日本学园祭的合成销售数据。数据集共包含25组独立的学园祭场景，每组覆盖3天时长，均通过大语言模型（Large Language Model, LLM）驱动的流水线生成。 ### 生成流水线 步骤1：身份生成（DeepSeek-V3.2） → 生成虚构的大学名称、学园祭名称、学校/学园祭简介 步骤2：场景生成（DeepSeek-V3.2） → 生成店铺详情、访客分布参数、天气情况、营业时间 步骤3：逛游模式生成（GPT-oss-20b） → 基于从Nemotron-Personas-Japan采样的人物角色，生成每位访客的购物行为 模拟环节 → 分配访客到访时间、构建交易数据 聚合环节 → 按15分钟间隔聚合销售数据、计算滞后特征 ### 文件结构 每个样本（编号00001至00025）包含4个文件： | 文件名称 | 描述 | |---|---| | `XXXXX_scenario.json` | 场景信息（包含大学设置、店铺详情、天气、访客数量、时间分布参数） | | `XXXXX_customers.csv` | 访客人物角色（每日100名访客 × 3天 = 共300行数据） | | `XXXXX_transactions.csv` | 单笔交易数据（包含到访店铺、停留时长、购买状态、消费金额） | | `XXXXX_sales.csv` | 15分钟间隔的销售聚合数据（核心训练数据集） | 生成脚本位于`main.py`和`src/`目录下。 仓库根目录下的`00001`至`00025`文件为公开的数据集快照。重新运行生成流水线时，新生成的文件将保存至`output/<时间戳>/`目录下，不会覆盖仓库根目录中的公开快照。 ### 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个间隔）设定，第1日无该特征 | | `lag192` | 2日前同时刻间隔的`paid_sales`值。列名基于24小时制15分钟间隔（2天共192个间隔）设定，第1、2日无该特征 | > 注：本公开快照中的`sales.csv`并非完整的24小时序列，仅包含场景设定的营业时间内的时段。因此`lag96`/`lag192`应理解为「前日/2日前同时刻特征」，而非严格意义上的96/192行偏移特征。 `scenario.json`中的`menu_items.price`字段可能取值为0（代表免费商品或灵活定价商品），因此存在`purchased=True`但`amount=0`的购买事件。此类事件将被计入`paid_count`，且对`paid_sales`的贡献为0。 ### scenario.json 字段说明 顶层字段： | 字段名 | 类型 | 说明 | |---|---|---| | `festival_name` | 字符串 | 学园祭名称 | | `school_name` | 字符串 | 大学名称 | | `school_description` | 字符串 | 大学概况（包含类型、规模、院系设置、所在地区） | | `festival_description` | 字符串 | 学园祭氛围与亮点介绍 | | `open_hour` | 整数 | 开场时间（例如：10） | | `close_hour` | 整数 | 闭场时间（例如：18） | | `total_shops` | 整数 | 学园祭总摊位数量（范围：35~180） | | `shops` | 数组 | 用于模拟的20家店铺详情（详见下文） | | `age_weights` | 数组 | 访客年龄分布权重（详见下文） | | `days` | 数组 | 3天的场景参数（详见下文） | `shops[]`数组元素： | 字段名 | 类型 | 说明 | |---|---|---| | `shop_id` | 整数 | 店铺ID（1~20） | | `shop_name` | 字符串 | 店铺名称 | | `genre` | 字符串 | 店铺品类（例如：餐饮、饮品、游戏） | | `location` | 字符串 | 校园内的摊位位置 | | `menu_items` | 数组 | 1~3款商品，每个商品包含`name`（字符串，商品名）、`price`（整数，日元，可为0代表免费/灵活定价）、`catchphrase`（字符串，宣传语） | | `popularity` | 浮点数 | 店铺人气评分（范围：0.0~1.0） | | `congestion` | 浮点数 | 店铺峰值拥堵程度（范围：0.0~1.0） | `age_weights[]`数组元素： | 字段名 | 类型 | 说明 | |---|---|---| | `age_min` | 整数 | 年龄区间下限 | | `age_max` | 整数 | 年龄区间上限 | | `weight` | 浮点数 | 该年龄区间访客占总访客的比例（所有区间权重之和为1.0） | `days[]`数组元素： | 字段名 | 类型 | 说明 | |---|---|---| | `day` | 整数 | 日期编号（1/2/3） | | `weather` | 字符串 | 天气描述（例如：「晨间多云，午后转晴，最高气温23℃」） | | `total_visitors` | 浮点数 | 当日总访客数（单位：万人） | | `arrival_dist` | 数组 | 5个高斯混合模型分量（详见下文） | `arrival_dist[]`数组元素： | 字段名 | 类型 | 说明 | |---|---|---| | `mean_hour` | 浮点数 | 访客到访峰值时刻（例如：12.5代表12:30） | | `std_hours` | 浮点数 | 标准差（单位：小时） | | `coefficient` | 浮点数 | 该分量的权重（所有分量权重之和为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 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/<时间戳>/`目录下，不会覆盖仓库根目录中的公开数据集快照。 ### 版权许可 本数据集采用[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），仍需遵守原数据集的署名要求。 关于数据集的局限性、偏差与预期用途，请参阅[DATASHEET.md](DATASHEET.md)文件。