# 虚拟城市 · 样例数据包（SAMPLE_PACKAGE）

> 这是**样例**，不是完整数据集。目的：让接收方在 10 分钟内判断
> 「这套数据能做什么 / 不能做什么 / 我能不能用」。

---

## ⚠ 三句必须随数据一起给出的话

> **许可已生效**：本目录内容采用 **CC BY 4.0**（署名即可 · 可引用/转载/研究/教学/商业原型）。
> 详见 [`LICENSE.md`](LICENSE.md)。

**任何引用、转述、二次分发本包内容时，下面三句必须一并出现：**

```
① 本数据全部是【虚构】的。其中的人、姓名、家庭、事件均为程序生成，
   不对应任何真实个人。姓名取自公开姓名库，与真实人物无关联。

② 本数据是【仿真输出】，不是【测量数据】。它是"给定规则下会发生什么"的推演，
   不是"现实中已经发生了什么"的观测记录。

③ 本数据【不能用于预测】。它未与任何真实统计口径对齐过（见 DATA_SPEC.md 的
   "已知限制"）。它可以用于：方法探索、机制演示、合成数据实验、教学。
   它不可以用于：预测某地某政策的效果、作为决策依据、对外声称"模拟显示…"。
```

**这三句不是免责套话** —— 它们是本数据集**唯一诚实的用法边界**。
本项目的 `LIMITATIONS.md` 记录了 6 类已知限制，其中 **L-1 会让"学历 → 行为"类结论的方向出错**，
请务必先读。

---

## 这个包是什么

一个**行为级虚拟城市**在若干年运行后的**抽样导出**。与常见的统计型人口模型不同，
这里每个个体有：

- **身份**：`sid`（灵魂号，跨世不变）· `bid`（身体号，每世一个）· `gen`（第几代）
- **人格**：`O/C/E/A/N` 五维（大五人格）· `arche`（原型分型）
- **一生**：`birthDay` / `deathDay` / `ageAtDeath` / 逐年状态 / 事件流
- **社会关系**：恋爱、婚姻、生育、离异、丧偶、再婚（`mstat`）
- **社会经济**：`edu`（学历）· `health` · `job` · `inc`（收入）· `dist`（居住区）

**"灵魂"与"身体"分离**是本系统的一个设计：性别是身体的属性、随世改变；
而人格与跨世记忆挂在灵魂上。所以同一个 `sid` 会有多个 `life`（＝投胎转世）。

---

## 里面有什么

| 文件 | 内容 | 行/条 | 大小 |
|---|---|---|---|
| `sample_souls.csv` | **灵魂级**汇总：每个 sid 有几世、各世性别、平均结局人格 | 表头 + 100 | 4 KB |
| `sample_panel.csv` | **人·年面板**（长表）：每个 bid 逐年的五维人格 / 学历 / 健康 / 职业 / 收入 / 婚况 / 居住区 | 表头 + 200 | 13 KB |
| `sample_lives.jsonl` | **一生档案**：一条 = 一个人的完整一生（含逐年序列与事件流） | 20 条 | 746 KB |
| `sample_demog.csv` | **城市级年度指标**（72 列）：人口 / 出生 / 婚姻 / TFR / 分层队列 / 匹配池 … | 表头 + 200 年 | 118 KB |
| `sample_queries.md` | ⭐ **5 个“这套数据能回答什么问题”的例子** + 各自用哪些字段 | — | — |
| `LICENSE.md` | **许可协议（CC BY 4.0 · 已生效）** + 署名格式 | — | 4 KB |
| `LICENSE-CC-BY-4.0.txt` | CC BY 4.0 官方法律全文 | — | 18 KB |

**总计 ≈ 861 KB。**

### 四个文件的粒度关系

```
sample_demog.csv   ← 城市（1 行 = 1 年）
sample_souls.csv   ← 灵魂（1 行 = 1 个 sid，跨世汇总）
sample_panel.csv   ← 人·年（1 行 = 1 个 bid 的 1 年）      ← 做统计最常用这张
sample_lives.jsonl ← 人·一生（1 行 = 1 个 bid 的完整一生）  ← 做质性/序列分析用这张
```

**同一个体在四张表里靠 `sid` / `bid` 关联**（`souls.sid` ↔ `panel.sid` ↔ `lives.sid`；
`panel.bid` ↔ `lives.bid`）。

---

## 怎么用

```bash
# 面板回归 / 描述统计（人·年粒度）
python -c "import pandas as pd; d=pd.read_csv('sample_panel.csv'); print(d.describe())"

# 一生序列（人·一生粒度 · JSON Lines）
python -c "
import json
for i,l in enumerate(open('sample_lives.jsonl',encoding='utf-8')):
    o=json.loads(l); print(o['sid'],o['life'],o['ageAtDeath'],len(o['events']))
    if i>=4: break"

# 城市年度指标
python -c "import pandas as pd; print(pd.read_csv('sample_demog.csv')[['year','pop','births','tfr']].tail())"
```

**字段字典、生成方法、可复现性参数、已知限制 ⇒ 见 [`DATA_SPEC.md`](DATA_SPEC.md)。**

---

## 可复现性（本包对应的运行）

| 项 | 值 | 在哪里看 |
|---|---|---|
| 引擎指纹（demog 批次） | `0269A820E07E0423` | `manifest.json` → `provenance` |
| 各文件哈希（sha256） | 逐文件登记 | `manifest.json` → `integrity.files` |
| 抽样方式 | 每表前 100~200 行 | `manifest.json` → `provenance.sampling` |
| 哈希盐 / 编号方案 | sid/bid 由 `hashOf(id, salt)` 派生，可与引擎逐位对齐 | `manifest.json` → `reproducibility` |

⚠ **本包的四个文件来自不同批次**（`souls`/`panel`/`lives` 来自 `ab17A` 档案批次，
`demog` 来自 `govB_ctrl` 批次）—— 目的是展示**四张表的格式**，**不是**一个自洽的切片。
完整数据集会按**同一批次**交付。

⚠ **`demog.csv` 的列数随引擎版本变化**（实测：29 / 57 / 70 / 72 列）。
本包用的是**最新的 72 列**版本。对应表见 `DATA_SPEC.md`。

---

## ⚠ 不要把本包当成"完整数据集"

本包是**格式样例**（每张表取前 100~200 行）。它**不足以**做任何有统计意义的分析。
若要用于研究，请索取**完整批次**。