原子文件

定义如下几种原子文件：

文件名	内容	示例
xxx.geo	存储地理实体属性信息。	geo_id, type, coordinates
xxx.usr	存储交通使用者信息。	usr_id, gender, birth_date
xxx.rel	存储实体间的关系信息，如路网。	rel_id, type, origin_id, destination_id
xxx.dyna	存储交通状态信息。	dyna_id, type, time, entity_id, location_id
xxx.ext	存储外部信息，如天气、温度等。	ext_id, time, properties
config.json	用于补充描述各表信息。

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

原子文件是不同交通预测任务的基本输入元素。你可以在这里下载交通数据原子文件的统一存储格式，了解详情。

.geo、.usr、 .rel、 .dyna 和 .ext 的格式类似 csv 文件， 即含有多列数据。

如果在处理成原子文件的过程中，对任意一种id进行了重映射，我们推荐从0开始编号！

警告：对于交通状态预测的相关任务的所有数据集，请保证geo文件中的geo_id的顺序跟dyna文件中的`entity_id的顺序保持一致，当然这个不是原子文件存储格式的必须，但是在我们的代码中默认了这种顺序的条件下对原子文件进行了读取。特别的，网格数据需要按照先行后列的顺序遍历，OD数据需要按照先起点后终点的顺序遍历，网格的OD数据则按照起点行、起点列、终点行、终点列的顺序遍历。

Geo 表

Geo 表中一个元素由以下四部分组成：

geo_id、 type、 coordinates、 properties （多列）。

• geo_id： 主键，唯一确定一个 geo 实体。 （如传感器， 经纬度点， 路段， 区域等的编号)

• type： 表示该 geo 的类型。有 [Point, LineString, Polygon] 三种值。 这三种取值与 Geojson 中的点线面一致。

• coordinates：由 float 类型组成的数组或嵌套数组。 描述 geo 实体的位置信息，采用 Geojson 的 coordinates 格式

• properties： 描述该 geo 的属性信息，若有多个属性，可以使用不同的列名定义为多列数据，如 POI_name， POI_type。 （对于网格数据，必有两列 row_id 和 column_id 属性表示网格的行列编号。）

注： Geojson 的 coordinates 格式为： (经度, 纬度)

• Point： [102.0, 0.5]

• LineString： [ [102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0] ]

• Polygon： [[ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ]]

Usr 表

Usr 表中一个元素由以下两部分组成：

usr_id， properties （多列）。

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

• properties： 描述该 usr 实体的属性信息，若有多个属性，可以使用不同的列名定义为多列数据，如 gender，birth_date。

Rel 表

Rel 表中一个元素由以下四个部分组成：

rel_id、 type、 origin_id、 destination_id、 properties（多列）。

• rel_id： 主键，唯一确定一个实体间的关系。

• type： 枚举类。取值为 [usr，geo]，表示该关系是基于 geo 还是 usr。

• origin_id： 关系起点方的 ID，为 Geo 表或 Usr 表中的一个。

• destination_id： 关系终点方的 ID，为 Geo 表或 Usr 表中的一个。

• properties： 描述该关系所具有的属性信息。若有多个属性，可以使用不同的列名定义多列数据。

Dyna 表

Dyna 表中一个元素由以下五部分组成：

dyna_id、 type、 time、 entity_id（多列）、 properties（多列）。

各列介绍

• dyna_id： 主键，唯一标识动态表中的一条记录。

• type： 枚举类。一共有两种取值： trajectory（轨迹预测任务） 和 state（状态预测任务）。

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

• entity_id： 描述该记录是基于哪一个实体观测产生的，就是 geo 或 usr的编号。

• properties： 描述该条记录的属性信息，若有多个属性，可以使用不同的列名定义为多列数据，比如既有速度数据、又有流量数据。

详细说明

• 对于交通状态预测任务：

  • 格式为：dyna_id, state, time, entity_id, properties，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结构的交通数据，entity_id 变成4列，列名为 [origin_row_id, origin_column_id, destination_row_id, destination_column_id]，文件后缀名为 .gridod。

• 对于轨迹相关任务:

  轨迹数据包括GPS点轨迹、基于路段的轨迹（路网匹配后）、用户签到轨迹（基于POI的轨迹）。

  • 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。

  对于特定任务，轨迹下一个位置预测任务的输入基于POI点的轨迹，到达时间估计任务的输入为GPS点的轨迹或基于路段的轨迹，地图匹配任务的输入为GPS点的轨迹，输出的是基于路段的轨迹。

数据排列方式

• Dyna表中，应该按照 <entity_id> 和 <time> 双关键字排列，即<entity_id>相同的记录放在一起并按照<time>排序。

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

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

例如：

state.dyna：

dyna_id,type,time,entity_id,traffic_speed
0,state,2012-03-01T00:00:00Z,773869,64.375
1,state,2012-03-01T00:05:00Z,773869,62.666
...
34271,state,2012-06-27T23:55:00Z,773869,65.111
34272,state,2012-03-01T00:00:00Z,767541,67.625
34273,state,2012-03-01T00:05:00Z,767541,68.555
...
68542,state,2012-06-27T23:50:00Z,767541,62.25
68543,state,2012-06-27T23:55:00Z,767541,66.888
68544,state,2012-03-01T00:00:00Z,767542,67.125
68545,state,2012-03-01T00:05:00Z,767542,65.444
...

trajectory.dyna：

dyna_id,type,time,entity_id,traj_id,coordinates,current_dis,current_state
0,trajectory,2014-08-03T18:29:00Z,810,0,"[104.115353,30.64392]",0.0,1.0
1,trajectory,2014-08-03T18:29:40Z,810,0,"[104.113091,30.642129]",0.294091467,1.0
2,trajectory,2014-08-03T18:30:20Z,810,0,"[104.110404,30.64393]",0.6199505718,1.0
3,trajectory,2014-08-03T18:31:00Z,810,0,"[104.108335,30.640667]",1.0332595142,1.0
...
21,trajectory,2014-08-03T18:53:23Z,810,0,"[104.076552,30.626844]",7.0811683597,0.0
22,trajectory,2014-08-03T18:13:00Z,810,1,"[104.106701,30.6916]",0.0,1.0
23,trajectory,2014-08-03T18:13:30Z,810,1,"[104.103889,30.688151]",0.4683813603,1.0
24,trajectory,2014-08-03T18:14:21Z,810,1,"[104.102828,30.68506]",0.8267467429,1.0

Ext 表

Ext 表中一个元素由以下五部分组成：

ext_id、 time、 properties (multiple columns)。

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

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

• 描述该条记录的属性信息，若有多个属性，可以使用不同的列名定义为多列数据，比如既有温度数据、又有湿度数据。

数据类型定义

需要在 config 文件中给出数据集中各列的数据类型定义，有助于后续的数据处理。

类型	说明
geo_id	存在于 geo 表中的离散的有限的 ID
usr_id	存在于 usr 表中的离散的有限的 ID
rel_id	存在于 rel 表中的离散的有限的 ID
time	符合 ISO-8601 标准的时间字符串
coordinate	符合 Geojosn 格式的坐标表示法的字符串
num	实数类
enum	枚举类字符串
other	其余的均以字符串类型存储

Config 文件

Config 文件用以补充描述上述五个表自身的信息， 以 json 形式保存并由 geo、 usr、 rel、 dyna、 ext、 info 六个键组成

• geo、 rel、 dyna、 ext：

  包含一个 including_types 键， 以数组的形式描述该表中所具有的 type 值。 其后每个 type 作为键，描述该 type 下 properties 具有哪些键及其数据类型 。

• 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。 部分邻接矩阵在原始数据的基础上，进行了一些计算。目前的计算方法是带有阈值的高斯核方法： $$ w_{ij} = \exp \left(- \frac{d_{ij}^{2}}{\sigma^{2}}\right)$$

    • weight_adj_epsilon： 高斯核的阈值。 经过计算的权重如果小于该阈值，则变成0，即 $$ w_{ij}[w_{ij}<\epsilon]=0$$ 此参数依赖于参数 calculate_weight_adj=True 。

• 对于轨迹下一跳预测任务：

  • distance_upper： POI点之间的最大距离。

样例如下：

{
    "geo":{
        "including_types":[
            "Point"
        ],
        "Point":{
            "poi_name":"other"
        }
    },
    "usr":{
        "properties":{
            "user_type":"enum",
            "birth_year":"time",
            "gender":"enum"
        }
    },
    "rel":{
        "including_types":[
            "geo"
        ],
        "geo":{
            "link_weight":"num"
        }
    },
    "dyna":{
        "including_types":[
            "state"
        ],
        "state":{
            "entity_id":"geo_id",
            "traffic_speed":"num"
        }
    },
    "grid":{
        "including_types":[
            "state"
        ],
        "state":{
            "row_id": 15,
            "column_id": 5,
            "traffic_speed":"num"
        }
    },
    "od":{
        "including_types":[
            "state"
        ],
        "state":{
            "origin_id":"geo_id",
            "destination_id":"geo_id",
            "traffic_speed":"num"
        }
    },
    "gridod":{
        "including_types":[
            "state"
        ],
        "state":{
            "origin_row_id": 15,
            "origin_column_id": 5,
            "destination_row_id": 15,
            "destination_column_id": 5,
            "traffic_speed":"num"
        }
    },
    "info": {
        "data_col": [
          "inflow",
          "outflow"
        ],
        "ext_col": [
          "Temperature"
        ],
        "data_files": [
          "TAXIBJ2013"
        ],
        "geo_file": "TAXIBJ",
        "ext_file": "TAXIBJ",
        "output_dim": 2,
        "init_weight_inf_or_zero": "inf",
        "set_weight_link_or_dist": "dist",
        "calculate_weight_adj": false,
        "weight_adj_epsilon": 0.1
  	}
}