Libcity笔记：原子文件

news2025/10/30 22:59:50

1 介绍

Libcity中的数据以原子文件的形式存在

2 原子文件类别

对于不同的交通预测任务，可能用到不同的原子文件，同一个数据集不一定包含全部六种原子文件

网格数据需要按照先行后列的顺序遍历
OD数据需要按照先起点后终点的顺序遍历

2.1 geo

存储地理实体属性信息

geo_id	主键，唯一确定一个 geo 实体。（如传感器，经纬度点，路段，区域等的编号)
type	表示该 geo 的类型。有 [`Point`, `LineString`, `Polygon`] 三种值
coordinates	由 float 类型组成的数组或嵌套数组。描述 geo 实体的位置信息，采用 Geojson的 coordinates 格式
properties	描述该 geo 的属性信息若有多个属性，可以使用不同的列名定义为多列数据，如 `POI_name`， `POI_type`。对于网格数据，必有两列 `row_id` 和 `column_id` 属性表示网格的行列编号

2.2 usr

存储交通使用者信息

usr_id 主键，唯一确定一个 usr 实体

properties

描述该 usr 实体的属性信息

若有多个属性，可以使用不同的列名定义为多列数据，如 gender，birth_date

2.3 rel

存储实体间的关系信息，如路网

rel_id	主键，唯一确定一个实体间的关系
type	枚举类。取值为 [`usr`，`geo`]，表示该关系是基于 `geo` 还是 `usr`
origin_id	关系起点方的 ID，为 Geo 表或 Usr 表中的一个
destination_id	关系终点方的 ID，为 Geo 表或 Usr 表中的一个
properties	描述该关系所具有的属性信息。若有多个属性，可以使用不同的列名定义多列数据。

2.4 dyna

需要保证geo文件中的geo_id的顺序跟dyna文件中的`entity_id的顺序保持一致

存储交通状态信息

dyna_id	主键，唯一标识动态表中的一条记录
type	枚举类。一共有两种取值： `trajectory`（轨迹预测任务）和 `state`（状态预测任务）
time	时间信息，采用 ISO-8601 标准中的日期时间组合表示法，如： 2020-12-07T02:59:46Z 按照 <entity_id> 和 <time> 双关键字排列，即<entity_id>相同的记录放在一起并按照<time>排序
entity_id	描述该记录是基于哪一个实体观测产生的，就是 `geo` 或 `usr`的编号
properties	描述该条记录的属性信息，若有多个属性，可以使用不同的列名定义为多列数据

2.4.1 交通预测任务下的entity_id & 文件后缀

对于传感器、路段、区域等实体	entity_id 的列名为 [entity_id]	文件后缀名为 `.dyna`
对于网格结构的交通数据	entity_id 变成2列，列名为 [row_id, column_id] 网格数据需要按照先行后列的顺序遍历网格	文件后缀名为 `.grid`
对于基于OD结构的交通数据	entity_id 变成2列，列名为 [origin_id, destination_id] OD数据需要按照先起点后终点的顺序遍历数据	文件后缀名为 `.od`
对于网格结合OD结构的交通数据	entity_id 变成4列，列名为 [origin_row_id, origin_column_id, destination_row_id, destination_column_id] 网格的OD数据则按照起点行、起点列、终点行、终点列的顺序遍历	文件后缀名为 `.gridod`

2.4.2 轨迹任务下的entity_id & 文件后缀

对于轨迹数据，同一用户 <entity_id> 的轨迹应先按 <traj_id> 排序，<traj_id> 相同者按照 <time> 排序

GPS点轨迹	格式为： dyna_id, type, time, entity_id, (traj_id), coordinates, properties. entity_id列的内容应为usr_id traj_id表示同一用户的多条轨迹的编号（从0开始）,如果用户只有一条轨迹，则该列可以为空 coordinates列的内容为GPS点的纬度和经度
基于路段的轨迹	格式为： dyna_id, type, time, entity_id, (traj_id), location, properties. entity_id列的内容应为usr_id traj_id表示同一用户的多条轨迹的编号（从0开始），如果用户只有一条轨迹，则该列可以为空 location列的内容是geo_id，指向geo表代表一个路段
基于POI的轨迹	格式为： dyna_id, type, time, entity_id, (traj_id), location, properties. entity_id列的内容应为usr_id traj_id表示同一用户的多条轨迹的编号（从0开始），如果用户只有一条轨迹，则该列可以为空 location列的内容是geo_id，指向geo表代表一个POI。

2.5 ext

存储外部信息，如天气、温度等

ext_id

主键，唯一标识外部数据表中的一条记录

time

时间信息，采用 ISO-8601 标准中的日期时间组合表示法，如： 2020-12-07T02:59:46Z

properties

描述该条记录的属性信息

若有多个属性，可以使用不同的列名定义为多列数据，比如既有温度数据、又有湿度数据。

2.6 Config

Config 文件用以补充描述上述五个表自身的信息，以 json 形式保存并由 geo、 usr、 rel、 dyna、 ext、 info 六个键组成
- geo、 rel、 dyna、 ext
  - 包含一个 including_types 键，以数组的形式描述该表中所具有的 type 值
  - 其后每个 type 作为键，描述该 type 下 properties 具有哪些键及其数据类型。
    - - 比如geo的类型是Point，Point没有任何额外properties列
    - - 比如rel的类型的geo，geo有一个额外properties 'cost'类型是'num'
- usr
  - 包含一个 properties 键，描述表中 properties 包含哪些键及其数据类型
- info
  - 包含其他必要的数据集统计信息，针对不同的交通预测任务，包含有不同的内容

文件名	geo_file	`.geo` 文件的文件名，字符串类型，默认为数据集名
	rel_file	`.rel` 文件的文件名，字符串类型，默认为数据集名。
	data_files	数据文件的文件名（例如 `.dyna`， `.grid`， `.gridod`），支持数组或字符串，默认为数据集名
	ext_file	`.ext` 文件的文件名，字符串类型，默认为数据集名
从各文件中加载的列名	weight_col	从 `.rel` 文件中加载的列名【作为训练/预测的内容】，支持只有一个元素的字符串数组或字符串。不指定的话，如果 `.rel` 文件只有一列权重列，则没有问题，否则报错
	data_col	从数据文件（如 `.dyna`， `.grid`， `.gridod`）加载的列名，支持数组或字符串，不指定则全部加载
	ext_col	从外部数据文件中加载的列名，支持数组或字符串，不指定则全部加载
	output_dim	指定模型输出的维度，一般应该跟 `data_col` 中指定的属性列名的数量相同
	time_intervals	数据集时间片的长度，以秒为单位
	init_weight_inf_or_zero	取值为 [`inf` , `zero`]。加载 `.rel` 文件构建邻接矩阵时，初始化邻接矩阵为全INF (`inf`) 还是全0 (`zero`)，默认为 `inf`
	set_weight_link_or_dist	取值为 [`link`, `dist`]，当加载 `.rel` 文件构建邻接矩阵时，使用文件中权重列中的原始值 (`dist`) 还是将之修订为全 01 的矩阵 (`link`)，默认为 `dist`。 [注意：如果 `.rel` 文件中只有相连的关系，没有不相连的关系，应该指定为 `link`]
	calculate_weight_adj	从 `.rel` 文件获取的邻接矩阵的权重是否需要进一步进行计算，默认为 `False`。部分邻接矩阵在原始数据的基础上，进行了一些计算。目前的计算方法是带有阈值的高斯核方法：
	weight_adj_epsilon	高斯核的阈值。经过计算的权重如果小于该阈值，则变成0 此参数依赖于参数 `calculate_weight_adj=True` 。
	distance_upper	【对于轨迹下一跳预测任务才有的参数】 POI点之间的最大距离