DSPL 是“Dataset Publishing Language”(数据集发布语言)的缩写。DSPL 中描述的数据集 可以导入到 Google 公开数据 Explorer - 一种用于详细、直观地探索数据 数据。
注意:将数据上传到 Google 公开数据 使用公开数据上传工具 您必须拥有一个 Google 账号。
本教程通过一个分步示例介绍了如何 DSPL 数据集。
DSPL 数据集是一个软件包,其中包含一个 XML 文件和一组 CSV 文件。CSV 文件是简单的表格,包含数据 数据集。XML 文件描述了数据集的元数据, 包括测量描述等信息性元数据, 结构元数据,例如表之间的引用。通过元数据 非专业用户会探索和直观呈现您的数据。
理解本教程的唯一前提条件 对 XML 的理解对简单的数据库概念(例如 表、主键)可能会有所帮助,但这并非强制性要求。为便于您参考, 完成的 XML 文件以及 完整数据集 与此教程相关联的软件包也可供查看。
概览
在开始创建数据集之前,请先大致了解 DSPL 数据集包含的内容:
- 常规信息:关于数据集
- 概念:“事物”的定义那个 出现在数据集中(例如,国家/地区、失业率、性别、 etc.)
- 切片 (Slice):有与之对应的概念的组合 数据
- 表格:概念和切片的数据。概念表 保留枚举和切片表,用于保存统计数据
- 主题:用于整理数据集的概念 通过加标签来组成有意义的层次结构
为了说明这些相当抽象的概念,请考虑使用 虚拟数据): 按不同国家/地区组合的汇总数据, 美国的州和性别。
此示例数据集定义了以下概念:
- country
- gender
- 人口
- 州
- 失业率
- 年
分类概念(例如状态)都与概念相关联 tables,用于枚举所有可能的值(加利福尼亚州、 亚利桑那州等)。概念可能具有额外的属性列,例如 州名或国家/地区。
Slice 定义了每个概念组合,其中
数据集中的统计数据。切片包含维度和
metrics。在上图中,尺寸为蓝色,
都显示为橙色在本示例中,切片
gender_country_slice
包含该指标的数据
population
,尺寸为country
year
和 gender
。另一个 Slice,称为
country_slice
,给出以下国家/地区的年度总人口数(指标)
国家/地区。
除了维度和指标之外,切片还参考了 表格,其中包含实际数据。
现在,我们将逐步介绍如何在 DSPL。
数据集信息
首先,我们需要为数据集创建一个 XML 文件。这里是 示例数据集的 DSPL 说明的开头:
<?xml version="1.0" encoding="UTF-8"?> <dspl targetNamespace="http://www.stats-bureau.com/mystats" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.google.com/dspl/2010" xmlns:time="http://www.google.com/publicdata/dataset/google/time" xmlns:geo="http://www.google.com/publicdata/dataset/google/geo" xmlns:entity="http://www.google.com/publicdata/dataset/google/entity" xmlns:quantity="http://www.google.com/publicdata/dataset/google/quantity"> <import namespace="http://www.google.com/publicdata/dataset/google/time"/> <import namespace="http://www.google.com/publicdata/dataset/google/entity"/> <import namespace="http://www.google.com/publicdata/dataset/google/geo"/> <import namespace="http://www.google.com/publicdata/dataset/google/quantity"/> <info> <name> <value>My statistics</value> </name> <description> <value>Some very interesting statistics about countries</value> </description> <url> <value>http://www.stats-bureau.com/mystats/info.html</value> </url> </info> <provider> <name> <value>Bureau of Statistics</value> </name> <url> <value>http://www.stats-bureau.com</value> </url> </provider> ... </dspl>
数据集说明以顶级 <dspl>
开头
元素。targetNamespace
属性包含一个 URI,
唯一标识此数据集。数据集的命名空间尤其
发布数据集时,请务必注意这一点,因为它是
您的数据集,以及其他人引用该数据集的方式。
请注意,targetNamespace
属性可以省略。在
在这种情况下,当数据集位于数据集内时,
。
使用其他数据集的信息
数据集可以通过导入来重用其他数据集中的定义和数据
这些数据集。每个 <import>
元素都指定了
此数据集将引用的另一个数据集的命名空间。
在示例数据集中,我们需要 http://www.google.com/publicdata/dataset/google/quantity 的一些定义 (Google 创建的数据集,其中包含可用于定义 数值),以及从时间、实体和地理数据集获取,这些数据集提供 分别与时间、实体和地理位置相关的定义。
顶部的 <dspl>
元素提供命名空间前缀
声明(例如,xmlns:time="http://..."
)
不同数据集。前缀声明需要引用
其他数据集中的元素。例如,
time:year
引用 year
中
命名空间与前缀关联的导入数据集
time
。
数据集和提供方信息
<info>
元素包含有关
数据集:名称、说明,以及可用于获取更多信息的网址
找到。
<provider>
元素包含有关
数据集的提供者:数据集的名称,以及可用于查看更多信息的网址
(通常是数据提供商的首页)。
定义概念
我们现在已经提供了一些关于数据集的一般信息, 就可以开始定义其内容了。我们的下一个目标是 过去 50 年来各个国家/地区的人口统计信息。
首先,我们需要为这些概念 人口、国家/地区和年份。在 DSPL 中,这些定义称为 概念。
“概念”是对出现在 数据集。对应于给定概念的数据值称为 实例。
人口
我们先来定义一下人口的概念。在
DSPL 文档,概念在 <concepts>
中定义
元素。
这是一个人口概念,只需提供最少量的信息即可
id
(唯一标识符)、name
和
type
。
<dspl ...> ... <concepts> <concept id="population"> <info> <name> <value>Population</value> </name> </info> <type ref="integer"/> </concept> ... </concepts>
下面对此示例进行了详细说明:
- 每个概念都必须提供用于唯一标识的
id
数据集内的概念。也就是说, 相同的数据集可以具有相同的 ID。 - 与数据集及其提供程序一样,
<info>
元素提供有关 概念,例如其名称和说明。 <type>
元素指定 概念的“实例”(即其“值”)。 在此示例中,population
的类型为integer
。DSPL 支持以下数据类型: <ph type="x-smartling-placeholder">- </ph>
string
integer
float
boolean
date
国家/地区
现在,我们编写国家/地区概念的定义:
<concept id="country"> <info> <name><value>Country</value></name> <description> <value>My list of countries.</value> </description> </info> <type ref="string"/> <property id="name"> <info> <name><value>Name</value></name> <description> <value>The official name of the country</value> </description> </info> <type ref="string" /> </property> <table ref="countries_table" /> </concept>
国家/地区概念定义从上一个概念定义开始,
具有 id
、info
和 type
。
概念值
国家/地区等分类概念枚举了
实例。也就是说,您可以列出所有可以
引用。但为此,每个国家/地区都需要一个唯一标识符。
本示例使用
ISO 国家/地区代码来标识国家/地区;这些代码是
类型为 string
。
在此例中,您不需要使用 ISO 代码;您 也可以使用国家/地区名称不过,名称因语言而异 可能会随时间而变化,并且并非始终以一致的方式在各数据集中使用。 对于国家/地区以及一般的分类概念来说,这是不错的选择 自由选择、简短、稳定、常用且与语言无关 标识符(如果存在)。
概念属性
除了 id
之外,国家/地区概念还有一个
<property>
元素,用于指定国家/地区的名称。
换句话说,国家/地区名称(“爱尔兰”)是一个媒体资源
id
爱尔兰。属性是 DSPL 提供
关于概念个案的额外结构化信息。
就像概念本身一样,属性也有 id
,
info
和type
。
概念数据
最后,国家/地区概念有一个 <table>
元素。
此元素引用一个表格,该表格枚举了
国家/地区。
使用表格对某些概念有效,但对其他概念无效。对于 就没必要针对 概念集中。但是,如果您确实引用了 一个概念,则该表格必须包含该概念的所有实例,例如 它必须列出每个国家/地区,而不是仅列出几个国家/地区。
数据集按如下方式定义 countries_table
表:
... <tables> <table id="countries_table"> <column id="country" type="string"/> <column id="name" type="string"/> <data> <file format="csv" encoding="utf-8">countries.csv</file> </data> </table> ... </tables>
国家/地区表指定了表中的列及其类型,
并引用包含相应数据的 CSV 文件。此 CSV 可以是
与数据集 XML 捆绑并上传,或通过 HTTP、HTTPS、
或 FTP。在后一种情况下,您需要将 countries.csv
替换为
网址,例如 http://www.myserver.com/mydata/countries.csv
。
无论存储在何处,CSV 文件都会如下所示:
country, name AD, Andorra AF, Afghanistan AI, Anguilla AL, Albania US, United States
表格的第一行会列出 DSPL 中指定的列 ID
table
定义。下面的每一行都对应
国家/地区概念的实例如果此概念有一个表格,则
表格必须包含相应概念的所有实例,在本示例中,
则必须列出所有国家/地区。
这些列会根据以下因素映射到国家/地区概念及其属性:
其 ID。第一列的 ID country
与概念匹配
id。这意味着此列包含唯一国家/地区标识符
由国家/地区概念定义下一列对应
国家/地区概念的 name
属性。值
与 name
属性的值匹配。
对于概念表的 CSV 数据,需要满足一些要求:
- 数据文件第一行中的列标题必须
与概念
id
和属性完全匹配id
(尽管 订单可能会发生变化)。 - 每行所包含的元素数量必须与 概念上的属性(即使值为空)。
- 概念的
id
字段的每个值(此处为 国家/地区代码)必须是唯一的,且非空(空字段是含 0 的 1) 或仅包含空白字符)。 - 引用其他概念的属性的值必须是 为空或是所引用概念的有效值。
- 包含逗号、双引号或换行符的值必须 完全括在双引号中。
- 值内任何文本双引号字符都必须紧跟着 前面用另一个双引号引起来。
年
对于国家/地区人口数据,我们需要的最后一个概念是
代表年份。我们不再定义新概念,而是使用
从我们导入的其中一个数据集内获取年份概念:
"http://www.google.com/publicdata/dataset/google/time".为此,
我们需要将其引用为 time:year
,其中 time
表示被引用的数据集,year
表示引用的数据集
概念。
规范概念
time:year
是一小部分规范概念的一部分
由 Google 定义。规范概念提供了时间的基本定义,
地理位置、数值数量、单位等
事实上,上述国家/地区概念以
规范的概念。我们在此处创建该图表仅作说明之用。
您应尽可能在数据集中使用规范概念,
或者通过扩展它们(下文有关于扩展的详细信息)。规范概念
使您的数据与其他数据集进行比较,并为您的
数据集。例如,以动画方式呈现随时间变化的数据
或在地图上显示地理数据都需要用到 time
和
geo
规范概念。
第一个 Slice
现在我们已经了解了人口、国家/地区和年份等概念,现在是时候 将它们组合在一起!
为此,我们需要创建一个切片来将它们合并。在 DSPL 中, 切片是数据存在的概念组合。
为什么不直接创建一个包含正确列的表格呢?因为切片会捕获 数据集的信息。这样一来, 会得到更清晰明了。
Slice 显示在 DSPL 文件中的 <slices>
下
元素,该元素必须紧跟在 concepts
部分之后。
<slices> <slice id="countries_slice"> <dimension concept="country"/> <dimension concept="time:year"/> <metric concept="population"/> <table ref="countries_slice_table"/> </slice> </slices>
与概念一样,每个 Slice 也有一个 id
(countries_slice
) 唯一标识
数据集。
切片包含两种概念引用:维度和
metrics。指标的值会随
维度。在此示例中,population
(指标)的值因
维度 country
和 year
。
与概念一样,切片包含对表格的引用, 包含切片的数据。引用的表必须有一列用于 切片的每个维度和指标与概念一样,切片的 维度和指标会映射到 ID 相同的表格列。
切片表
人口切片的表格显示在 tables
中
部分:
<tables> ... <table id="countries_slice_table"> <column id="country" type="string"/> <column id="year" type="date" format="yyyy"/> <column id="population" type="integer"/> <data> <file format="csv" encoding="utf-8">country_slice.csv</file> </data> </table> ... </tables>
请注意,year
列随附一个 format
属性,用于指定年份的格式。支持的日期格式包括
Joda 日期时间格式定义的日期。
countries_slice
表指定了表中的列,
其类型,并指向包含相应数据的 CSV 文件。CSV 文件
如下所示:
country, year, population AF, 1960, 9616353 AF, 1961, 9799379 AF, 1962, 9989846 AF, 1963, 10188299 ...
数据表格中的每一行都包含维度的唯一组合
country
和 year
,以及相应的值
(例如,总体 -population
metric - 1960 年阿富汗的 metric)。
请注意,country
列中的值与
country
概念的值/标识符,即 ISO 3166
国家/地区的双字母代码。
切片的 CSV 数据必须满足以下限制条件:
- 维度字段的每个值(例如
country
和year
)不能为空。指标字段的值(例如population
)可以为空。空值由 no 表示 字符。 - 引用某个概念的维度字段的每个值都必须是
包含该概念的数据中。例如,值
AF
必须出现在country
概念数据表中。 - 维度值的每个唯一组合,例如
AF, 2000
, 只能出现一次。 - 数据应按非时间维度列(以任意顺序)进行排序,
然后视需要添加任何其他列举个例子
在包含
[date, dimension1, dimension2, metric1, metric2]
列的表格中,可以按dimension1
排序, 之后价格为dimension2
,最后价格为date
,但不是date
,然后是尺寸。
摘要
目前,我们在 DSPL 中有足够的信息来描述 人口数据。总结一下,我们必须做的是:
- 创建数据集及其它的 DSPL 标头和说明 提供方
- 分别为人口和国家/地区创建一种概念,并指定 csv 文件,列举所有国家/地区及其名称。
- 创建一个包含不同国家/地区的人口数量的切片, 引用导入的时间数据集中已定义的年份概念 。
在本教程的其余部分中,我们将通过以下方式使数据集更丰富: 在更多切片中添加更多维度,以及按 主题。
添加维度:美国各州
现在,让我们通过添加以下各州的人口数据来丰富我们的数据集: 美国。我们首先需要定义一个状态概念。看起来 就像我们之前定义的国家/地区概念一样
<concept id="state" extends="geo:location"> <info> <name> <value>state</value> </name> <description> <value>US states, identified by their two-letter code.</value> </description> </info> <property concept="country" isParent="true" /> <table ref="states_table"/> </concept>
概念扩展和属性 参考
状态概念引入了 DSPL 的几项新功能。
首先,状态是对另一个概念的扩展,
geo:location
(在外部地理位置数据集中定义,
在数据集开头导入)。从语义上讲,这意味着
state
是一种 geo:location
。后果是
它继承了
geo:location
。特别是,location 定义
latitude
和 longitude
;通过扩展前者
那么这些属性也会应用于状态。此外,由于
位置继承自 entity:entity
,状态也会获得
后者的所有属性,包括 name
,
description
和info_url
。
注意:之前定义的国家/地区概念
从技术上来说,也应从 geo:location
扩展。
为简单起见,之前省略了这一点;我们添加了
但从地理位置到国家/地区继承
最终的 XML 文件。
注意:您可以使用 extends
构造方法,以重复使用其他数据集定义的信息。
使用 extends
要求概念的所有实例均为
您要扩展的概念的有效实例。借助扩展程序,你可以
额外属性,以及将实例集限制为
扩展概念实例的子集。
除了继承之外,状态属性还引入了
概念参考。
特别是,状态概念有一个名为 country
的属性,
引用了我们在上面创建的国家/地区概念这是通过
使用 concept
属性。请注意,此属性不会
提供一个 ID,只是一个概念引用。这相当于创建一个 ID
其值与所引用概念的 ID 相同(即
country
)。组织之间的层级关系
某个州或省/自治区/直辖市和县
针对引用的 isParent="true"
。一般来说,
具有层级关系的维度(例如地理位置)
子概念有一个属性
使用 isParent
属性引用父概念。
状态的表定义如下所示:
<tables> ... <table id="states_table"> <column id="state" type="string"/> <column id="name" type="string"/> <column id="country" type="string"> <value>US</value> </column> <column id="latitude" type="float"/> <column id="longitude" type="float"/> <data> <file format="csv" encoding="utf-8">states.csv</file> </data> </table> ... </tables>
“国家/地区”列包含所有州的常量值。在
DSPL 会避免为数据中的每个状态重复该值。另请注意
我们添加了 name
、latitude
和
longitude
,因为状态继承自
geo:location
。另一方面,一些继承的属性
(例如,description
) 不含列;没关系-
如果概念定义表中省略了某个属性,则其值
都假设未定义。
CSV 文件如下所示:
state, name, latitude, longitude AL, Alabama, 32.318231, -86.902298 AK, Alaska, 63.588753, -154.493062 AR, Arkansas, 35.20105, -91.831833 AZ, Arizona, 34.048928, -111.093731 CA, California, 36.778261, -119.417932 CO, Colorado, 39.550051, -105.782067 CT, Connecticut, 41.603221, -73.087749 ...
由于我们已经有关于人口和年份的概念,因此可以重复使用这些概念 为状态人口定义新的切片。
<slices> <slice id="states_slice"> <dimension concept="state"/> <dimension concept="time:year"/> <metric concept="population"/> <table ref="states_slice_table"/> </slice> </slices>
数据表定义如下:
<tables> ... <table id="states_slice_table"> <column id="state" type="string"/> <column id="year" type="date" format="yyyy"/> <column id="population" type="integer"/> <file format="csv" encoding="utf-8">state_slice.csv</file> </table> ... </tables>
CSV 文件如下所示:
state, year, population AL, 1960, 9616353 AL, 1961, 9799379 AL, 1962, 9989846 AL, 1963, 10188299
等等,我们为什么要创建新切片,而不是再添加一个 与上一个维度进行比较?
包含州和国家/地区维度的切片不正确, 因为有些行是国家/地区数据,有些行是州/省级行政区 数据。桌子上就会有“空洞”对于某些维度, 不允许(请注意,只有指标和 而不是维度)。
维度充当“主键”。这意味着 每个数据行都必须包含所有维度的值,并且不能有 2 个数据行 所有维度的值都可以完全相同。
添加指标:失业率 费率
现在,让我们向数据集再添加一个指标:
<concept id="unemployment_rate" extends="quantity:rate"> <info> <name> <value>Unemployment rate</value> </name> <description> <value>The percent of the labor force that is unemployed.</value> </description> <url> <value>http://www.bls.gov/cps/cps_htgm.htm</value> </url> </info> <type ref="float/> <attribute id="is_percentage"> <type ref="boolean"/> <value>true</value> </attribute> </concept>
此指标的 info
部分包含名称、说明和
网址(链接至美国劳工统计局)。
此概念还扩展了 quantity:rate
规范概念。
数量
数据集定义了表示数值的核心概念。在
您应通过扩展
适当的数量概念因此,population
的概念
从技术上来讲应该是扩展了
quantity:amount
。
概念属性
此概念还引入了属性的结构。在
在此示例中,我们使用一个属性来表示 unemployment_rate
是百分比。is_percentage
属性继承自
此概念扩展的 quantity:rate
概念。本次
信息,公开数据浏览器会使用这些信息在发生以下情况时显示百分号:
直观呈现数据
属性提供了一种将键值对附加到
概念(与属性相反,属性会将其他值与
实例)。与概念和属性一样,
属性具有 id
、info
和
type
。与属性一样,它们也可以引用其他概念。
属性不仅仅适用于预定义的一般内容, 属性。您可以为自己的概念定义自己的属性。
添加美国的失业率数据 州/省/自治区/直辖市
我们现在已准备好添加美国各州的失业率数据。因为 失业率是一项指标,我们已经拥有各州的人口数据, 我们只需将其添加到已为州和年份创建的 Slice 中即可 维度:
<slices> ... <slice id="states_slice"> <dimension concept="state"/> <dimension concept="time:year"/> <metric concept="population"/> <metric concept="unemployment_rate"/> <table ref="states_slice_table"/> </slice> ... </slices>
... 并在表定义中添加另一列:
<tables> ... <table id="states_slice_table"> <column id="state" type="string"/> <column id="year" type="date" format="yyyy"/> <column id="population" type="integer"/> <column id="unemployment_rate" type="float"/> <data> <file format="csv" encoding="utf-8">state_slice.csv</file> </data> </table> ... </tables>
... 然后导入 CSV 文件:
state, year, population, unemployment_rate AL, 1960, 9616353, 5.1 AL, 1961, 9799379, 5.2 AL, 1962, 9989846, 4.8 AL, 1963, 10188299, 6.9
我们之前说过,对于每个切片,维度构成一个主键 。此外,对于每个数据集,每个数据集只能包含一个切片, 维度组合。所有这些指标的可用指标 维度必须属于同一切片。
更多维度:按性别细分的人口
让我们使用按性别细分的人口数据来丰富我们的数据集, 国家/地区。现在,你开始了解演习了...我们首先需要 添加性别概念:
<concept id="gender" extends="entity:entity"> <info> <name> <value>Gender</value> </name> <description> <value>Gender, Male or Female</value> </description> <pluralName> <value>Genders</value> </pluralName> <totalName> <value>Both genders</value> </totalName> </info> <type ref="string"/> <table ref="genders_table"/> </concept>
性别概念 info
部分包含
pluralName
:提供用于指代的文本
性别概念的多个实例。info
部分还
包含一个 totalName
,它提供了要用于
将性别概念的所有实例作为一个整体指代。这两者
供公开数据浏览器用来显示与性别相关的信息
概念。一般来说,对于可以用作实验目的的概念
维度。
请注意,性别这一概念也源于
entity:entity
。这种做法对于
这些用作维度的维度,因为它允许您添加自定义名称、
网址和颜色。
性别概念指的是 genders_table
表,
包含性别及其显示名称的可能值
(此处已省略)。
要将按性别的人口添加到数据集中,我们需要创建一个新的切片 (请注意:每个可用的维度组合都对应着 数据集)。
<slice id="countries_gender_slice"> <dimension concept="country"/> <dimension concept="gender"/> <dimension concept="time:year"/> <metric concept="population"/> <table ref="countries_gender_slice_table"/> </slice>
切片的表定义如下所示:
<table id="countries_gender_slice_table"> <column id="country" type="string"/> <column id="gender" type="string"/> <column id="year" type="date" format="yyyy"/> <column id="population" type="integer"/> <data> <file format="csv" encoding="utf-8">gender_country_slice.csv</file> </data> </table>
表的 CSV 文件如下所示:
country, gender, year, population AF, M, 1960, 4808176 AF, F, 1960, 4808177 AF, M, 1961, 4899689 AF, F, 1961, 4899690...
与之前的国家/地区相比,人口和失业率方面, 还有一个额外的维度人口指标的每个值 不仅对应特定的国家/地区和年份,而且还对应某个 特定性别。
请注意,我们已经创建了一个“稀疏”数据集。并非所有 指标适用于所有维度:人口为 国家/地区和美国各州,每年提供此数据, 费率仅适用于国家/地区。提供按性别细分的数据 仅按国家/地区统计人口数据;它不能用来计算失业率数据 指标,而不是状态维度。稀疏性也可能存在于 某些指标的某些维度值没有对应的值 但在 DSPL 中并不表示。
主题
我们在数据集中使用的最后一个功能是 topics。 主题用于以分层方式对概念进行分类, 可帮助用户导航到您的数据
在 DSPL 文件中,主题紧跟在概念前面。下面是一个示例 主题层次结构:
<dspl ... > ... <topics> <topic id="geography"> <info> <name> <value>Geography</value> </name> </info> </topic> <topic id="social_indicators"> <info> <name> <value>Social indicators</value> </name> </info> </topic> <topic id="population_indicators"> <info> <name> <value>Population indicators</value> </name> </info> </topic> <topic id="poverty_and_income"> <info> <name> <value>Poverty & income</value> </name> </info> </topic> <topic id="health"> <info> <name> <value>Health</value> </name> </info> </topic> </topics>
您可以根据需要进行深入嵌套的主题。
要使用主题,您只需要在概念中引用主题 定义如下:
<concept id="population"> <info> <name> <value>Population</value> </name> <description> <value>Size of the resident population.</value> </description> </info> <topic ref="population_indicators"/> <type ref="integer"/> </concept>
一个概念可以引用多个主题。
提交数据集
现在您已经创建了数据集,下一步是将其压缩, 将 ZIP 文件上传到 Google 公开数据浏览器工具。如果您遇到任何问题,请查看 常见问题解答,其中包括 最常见的上传问题
您还可以下载完整的 XML 文件和完整的数据集 bundle 作为参考 与本教程关联的工具
相关资料
恭喜您创建了您的第一个 DSPL 数据集!现在 建议您通读开发者指南,其中 文档“高级”DSPL 功能,例如 多语言支持和可映射概念。
您可能还想查看更多示例数据集。