dbnomics数据模型
dbnomics-data-model的Python项目详细描述
dbnomics数据模型
这个存储库定义了dbnomics的数据模型。
有关数据模型的快速示意图，请阅读cheat\u sheet.md文件。 如果你是一个开发人员在抓取，你可以打印它！
另请参见这些示例目录。
注意：--符号表示通过验证脚本验证约束。
实体和关系
provider -> dataset -> time series -> observations
- 每个提供程序都包含数据集
- 每个数据集都包含时间序列
- 每个时间序列都包含观测值
- 每个观察都是一个元组，如
（period，value，attribute1，attribute2，…，attributen），其中属性是可选的
注："时间序列"的单数形式和复数形式是相同的（cfwiktionary）。
储存
dbnomics数据存储在文件系统的常规目录中。
一个目录，其中包含由取款器转换的提供程序中的数据。
- ☆目录名必须是
{provider_code}-json data
修订版
使用git对每个存储目录进行版本控制，以便跟踪修订。
一般约束
最小数据
如果数据不增加值或可以从任何其他数据中计算出来，则不得存储该数据。
因此：
- 如果源数据未提供序列名，则不能生成序列名；
dbnomics可以从维度值代码生成名称
数据稳定性
提供程序的存储目录中的任何提交都必须反映来自提供程序一侧的更改。
数据转换必须稳定：在同一源数据上运行转换脚本不能更改已转换的数据。
因此：
- 当从维度dict生成序列代码时，请始终使用相同的顺序；
- json对象的属性必须按字母顺序排序；
/provider.json
此json文件包含有关提供程序的元数据。
请参见其json模式。
/category_tree.json
此json文件包含一个类别树，其叶为数据集，节点为类别。
此文件是可选的：
- 如果类别是由源数据提供的，则它应该存在；
- 如果缺少，dbnomics将生成一个按字典顺序排列的数据集列表；
- 如果它与上述生成的列表相同（由于有关最小数据的一般限制），则不能写入它。
请参见其json模式。
/{dataset_code}/
此目录包含有关提供商数据集的数据。
- 目录名必须等于数据集代码。
/{dataset_code}/dataset.json
此json文件包含有关提供程序的数据集的元数据。
请参见其json模式。
序列属性（如果可选）：请参见存储时间序列部分。
/{dataset_code}/series.jsonl
这个json行文件包含关于提供者数据集时间序列的元数据。
每一行都是一个json对象，根据这个json模式验证。
此文件是可选的：请参见存储时间序列E系列部分。
/{dataset\u code}/{series\u code}.tsv
此文件包含对提供者数据集时间序列的观察。
这些文件是可选的：请参见存储时间序列部分。
时间序列的约束
- 提供程序使用由维度值代码组成的序列代码时：
- 分隔符必须是"."才能与序列代码掩码兼容。允许更改提供程序最初使用的分隔符。示例：此提交在bis上
- 系列代码的部分必须遵循
Dimensions\u codes\u order定义的顺序。示例：如果dimensions\u codes\u order=["freq"，"country"]，则系列代码必须是a.fr而不是fr.a - 如果提供程序未定义维度代码顺序，则应使用维度代码的字典顺序，并且不得写入
维度代码顺序键。示例：如果维度是freq和country，则系列代码是fr.a；因为维度代码是按字母顺序排序的：["country"，"freq"]
对tsv文件的限制
注意：--符号表示通过验证脚本验证约束。
- TSV文件必须用UTF-8编码。
- ☆标题的前两列必须命名为
period和value - ☆每行的列数必须与标题相同。
句点列的值：- ☆必须遵守特定格式：
yyyy持续数年yyyy-mm数月（必须填充mm）yyyy-mm-dd天（必须为mm和dd填充）yyyy-q[1-4]对于年度季度- 示例：
2018-q1表示2018年1月至3月，2018-q4表示2018年10月至12月
- 示例：
yyyy-s[1-2]学年学期（即两年制、半年制）- 示例：
2018-s1表示2018年1月至6月，2018-s2表示2018年7月至12月
- 示例：
yyyy-b[1-6]两个月（也称为双月）- 示例：
2018-b1表示2018年1月+2月，2018-b6表示2018年11月+12月
- 示例：
yyyy-w[01-53]年周（必须填充）
- ☆必须具有相同的格式
- ☆不得包含平均值，如
m13或q5句点（某些提供者这样做） - 必须与频率一致（即对于季度观测使用
yyyy-q[1-4]，而不是yyyy-mm-dd，即使这些日周期之间有3个月）
- ☆必须遵守特定格式：
- ☆必须按升序对
句点列排序。 - ⑤
值列的值必须：- 遵循xmlschema中的decimal的顺序：由句点分隔的非空有限长十进制数字序列，作为十进制指示符。允许使用可选的前导符号。如果省略符号，则假定为"+"。前导零和尾随零是可选的。如果小数部分为零，则可以省略周期和后面的零。例如：'-1.23'，'12678967.543233'，'+100000.00'，'210'。
- 或者
na表示"不可用"。
- tsv文件可以有补充列，以便一些观察值。
- 这些列的值是自由的，空字符串表示没有标记
- 如果可能，重用提供者定义的值；否则，使用dbnomics团队定义值
存储时间序列
元数据
时间序列元数据可以存储：
- 在
系列属性下的{dataset_code}/dataset.json中，将其作为对象的json数组 - 在
{dataset_code}/series.jsonl文件中，ajson行中，每一行都是一个（非缩进的）json对象
当一个数据集包含大量的时间序列时，dataset.json文件会急剧增长。在这种情况下，建议使用series.jsonl格式，因为逐行解析json行文件比打开整个json文件占用的内存更少。建议在dataset.json中最大限制1000个时间序列。
无论您选择何种格式，json对象都将根据这个json模式进行验证。
架构的附加约束：
- ☆序列列表的
代码属性必须是唯一的
示例：
- 此数据集在
系列属性下的dataset.json中存储时间序列元数据 - 此数据集将时间序列元数据存储在
series.jsonl
尺寸值顺序
有时维度值的顺序不同于字典顺序。
例如：对于"国家"这个维度，我们有"所有国家[全部]"、"阿富汗[空军]、"法国[法国]"、"德国[德国]"、"其他国家[其他]"。在这种情况下，首先显示"所有国家"，最后显示"其他国家"似乎更为自然。我们不希望"阿富汗"仅仅因为词汇顺序而排在"所有国家"之前。
可以在dataset.json中对该顺序进行编码，如下所示：
{"dimensions_values_labels":{"country":[["ALL","All countries"],["AF","Afghanistan"],["FR","France"],["DE","Germany"],["OTHER","Other countries"]]}}
另一种情况是当维度值谈到单位时，我们希望从最小到最大排序单位。例如，"毫米"、"厘米"、"米"、"公里"。
观察结果
可以存储时间序列观测：
- 在tsv文件中
- 在
{dataset_code}/series.jsonl中，在每个对象的observations属性下，ajson行文件中，每一行都是一个（非缩进的）json对象。
当一个数据集包含大量的时间序列时，tsv文件的数量急剧增加。在这种情况下，建议使用series.jsonl格式，因为单个文件比数千个文件占用更少的磁盘空间（每个文件在文件系统目录中占用大约千字节），而且当提交的文件数增加时，git速度会变慢。建议最大限制为1000个TSV文件。
无论您选择何种格式，json对象都将根据这个json模式进行验证。
示例：
- 此数据集将观察结果存储在tsv文件中
- 此数据集将观察结果存储在
series.jsonl
向数据添加文档（说明和注释字段）
数据集和数据系列可以使用说明和注释字段记录。
- <> >代码>说明显示数据的含义
注释显示有关数据的一些注释。示例："在2002年3月之前，风险敞口在银行和交易账簿中进行了净额结算。这就需要在这个系列中稍作休息。"
=>；请参见本示例
数据验证
dbnomics数据模型附带一个验证脚本。验证json数据目录：
dbnomics-validate <storage_dir>
# for example:
dbnomics-validate wto-json-data
请注意，验证脚本尚未检查上面表示的某些约束。
测试
运行单元测试：
python setup.py test代码质量：
pylint --rcfile ../code-style/pylintrc *.py dbnomics_data_model
另请参见：https://git.nomics.world/dbnomics-fetchers/documentation/wikis/code-style" rel="nofollow">https://git.nomics.world/dbnomics fetchers/documentation/wikis/code style
对虚拟提供程序运行验证脚本：
dbnomics-validate tests/fixtures/provider1-json-data dbnomics-validate tests/fixtures/provider2-json-data
更改日志
请参见changelog.md。它包含一个升级指南，说明如果数据模型以意外方式更改，如何修改获取程序的源代码。
发布新版本
对于软件包维护人员：
git tag x.y.z git push git push --tags
gitlab ci将把这个包发布到https://pypi.org/project/dbnomics-data-model/" rel="nofollow">https://pypi.org/project/dbnomics-data-model/（请参见.gitlab ci.yml）。
欢迎加入QQ群-->： 979659372
