Przewodnik dla programistów po DSPL

DSPL oznacza Dataset Publishing Language. Jest to format obrazu zarówno dla metadanych (informacji o zbiorze danych, takich jak nazwa i dostawca, jak i zawartych w nim koncepcji) oraz faktycznych danych zbiorów danych. Zbiory danych opisane w tym formacie można zaimportować do narzędzia Google Public Data Explorer, które umożliwia zaawansowane wizualizację danych.

Uwaga: aby przesyłać dane do publicznych danych Google za pomocą narzędzia do przesyłania danych publicznych, musisz mieć konto Google.

Ten dokument jest przeznaczony dla właścicieli danych, którzy chcą udostępniać swoje dane w Eksploratorze danych publicznych. To nie tylko samouczek, który zawiera bardziej szczegółowe informacje na temat schematu DSPL i obsługiwanych funkcji. Zakładamy, że użytkownik korzysta wyłącznie z podstawowej znajomości kodu XML, choć przydatna jest również relacyjna baza danych.

Nie jest to wymagane, ale zalecamy zapoznanie się z samouczkiem (krótszym i łatwiejszym do zapoznania się z tym dokumentem).

Omówienie

Zbiór danych DSPL to plik .zip zawierający plik XML i zestaw plików CSV. Pliki CSV to proste tabele zawierające dane zbioru danych, a plik XML opisuje metadane zbioru danych. Ta druga część zawiera metadane informacyjne, takie jak opisy pomiarów, oraz metadane strukturalne, np. odniesienia między tabelami. Dzięki tym metadanym osoby, które nie są ekspertami w dziedzinie danych, mogą je przeglądać i wizualizować.

Przetwarzanie

Ogólnie proces tworzenia zbioru danych DSPL wygląda następująco (niektóre czynności mogą przebiegać równolegle):

  1. Utwórz plik XML DSPL.
  2. Zidentyfikuj zewnętrzne źródła danych, których chcesz użyć w zbiorze danych.
  3. Zdefiniuj swoje pojęcia, wycinki i (opcjonalnie) tematy. Powtarzaj zawartość pliku DSPL.
  4. Wyeksportuj dane źródłowe do plików .csv.
  5. Utwórz zbiór danych DSPL.
  6. Prześlij zbiór danych do Google.

Struktura XML

Omówienie

Plik XML DSPL definiuje metadane zbioru danych, w tym relacje strukturalne między pojęciami, wycinkami, tematami i tabelami. Chociaż ten plik można utworzyć ręcznie, narzędzia i skrypty mogą znacznie uprościć cały proces. Zobacz przykładowy plik DSPL w nowym oknie

Plik zawiera szereg sekcji podsumowanych w tabeli poniżej. W tabeli poniżej bardziej szczegółowo opisujemy każdy z tych elementów.

Sekcja Podsumowanie Więcej informacji
Nagłówek i importy Nadrzędny dla wszystkich pozostałych elementów zbioru danych. Obejmuje docelową przestrzeń nazw (tj. identyfikator) zbioru danych oraz przestrzenie nazw zaimportowanych zbiorów danych. Dokumentacja
Informacje o zbiorze danych Nazwa, opis i adres URL zbioru danych. Dokumentacja
Informacje o dostawcy Nazwa, opis i adres URL dostawcy zbioru danych. Dokumentacja
Pojęcia

Definicje „rzeczy”, które pojawiają się w zbiorze danych (np. kraje, stopa bezrobocia, płeć itp.)

Każda koncepcja ma unikalny identyfikator, do którego mogą się odwoływać wycinki i tabele.

 Dokumentacja
Wycinki

Kombinacje koncepcji, dla których istnieją dane statystyczne, w zbiorze danych. Każdy wycinek zawiera wymiary i dane.

Wycinki odwołują się do pojęć, a także tabel zawierających rzeczywiste dane. Każdy wycinek ma unikalny identyfikator, do którego mogą się odwoływać tabele zawierające rzeczywiste dane.

 Dokumentacja
Tabele Zdefiniuj dane dla pojęć i wycinków. Tabele koncepcyjne zawierają wyliczenia, a tabele wycinków zawierają dane statystyczne. Tabele są zdefiniowane w pliku XML i wskazują pliki .csv z rzeczywistymi danymi. Dokumentacja
Tematy Kategorie ułatwiające porządkowanie zbiorów danych. Nie są one wymagane, ale mogą być bardzo przydatne dla użytkowników poruszających się po Twoich danych. Dokumentacja

Nagłówek i importy

Deklarowanie przestrzeni nazw danych publicznych

Zbiór danych DSPL zaczyna się od elementu <dspl> najwyższego poziomu. Służy do dołączania wszystkich informacji ze zbioru danych i do określenia wszelkich przestrzeni nazw, które będą używane w całym pliku. Oto przykład:

<?xml version="1.0" encoding="UTF-8"?>
<dspl targetNamespace="http://www.example.com/mystats"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://schemas.google.com/dspl/2010" >
    ...
</dspl>

Przestrzeń nazw to unikalny identyfikator, który można powiązać ze schematem XML (zbiorem elementów i atrybutów XML). targetNamespace udostępnia identyfikator URI, który identyfikuje zbiór danych. Identyfikator ten nie jest wymagany do wskazania rzeczywistego zasobu, ale warto go podać w dokumencie opisującym Twoje treści lub zbiór danych.

Nie musisz podawać targetNamespace. Jeśli tego nie zrobisz, kod zostanie wygenerowany automatycznie w momencie importu.

Po atrybucie targetNamespace następuje seria atrybutów xmlns określających inne schematy XML, które zostaną użyte w pliku. Każdy plik DSPL musi zawierać schemat danych publicznych Google, którego identyfikator URI to „http://schemas.google.com/dspl/2010”, i używać go jako domyślnej przestrzeni nazw. Powinien także zawierać standardowy schemat W3 XML, który jest identyfikowany przez „http://www.w3.org/2001/XMLSchema-instance”. Zgodnie z opisem w następnej sekcji możesz dodawać inne przestrzenie nazw, aby uwzględnić informacje z innych zbiorów danych.

Importowanie innych przestrzeni nazw zbioru danych

Zbiory danych mogą wykorzystywać definicje i dane z innych zbiorów danych. Na przykład Google udostępnia wiele podstawowych zbiorów danych definiujących pojęcia, które często pojawiają się w danych użytkownika. Na przykład większość zbiorów danych musi reprezentować wiele lat. Zamiast definiować nową koncepcję, możesz wykorzystać koncepcję roku ze zbioru danych „http://www.google.com/publicdata/dataset/time”. Więcej informacji znajdziesz na stronie Pojęcia kanoniczne.

Aby użyć zewnętrznego zbioru danych, dodaj element <import> do pliku DSPL tuż po deklaracji przestrzeni nazw i wskaż importowaną przestrzeń danych:

<import namespace="http://www.google.com/publicdata/dataset/google/time"/>

Następnie dodaj importowaną przestrzeń nazw (w tym przypadku time="http://www.google.com/publicdata/dataset/google/time") do deklaracji przestrzeni nazw u góry pliku:

<?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" >
<import namespace="http://www.google.com/publicdata/dataset/google/time"/>

Twój plik DSPL może teraz odwoływać się do elementów ze zbioru danych czasu publicznego Google. Powtórz ten proces dla każdego zbioru danych, do którego chcesz się odwołać.

Odwoływanie się do treści w zewnętrznych zbiorach danych

Po zaimportowaniu innego zbioru danych musisz mieć możliwość odwołania się do pojęć, wycinków i danych z tego zbioru danych. Aby to zrobić, możesz użyć plików referencyjnych w formacie prefix:other_id, gdzie prefix to prefiks używany w przestrzeni nazw zewnętrznego zbioru danych.

Oto przykład odwołania do koncepcji year ze zbioru danych time (zgodnie z opisem powyżej):

<slices>
  <slice id="country_slice">
    <dimension concept="country"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <table ref="country_slice_table"/>
  </slice>
  ...
</slices>

Informacje o zbiorze danych

Element <info> zawiera opisowe informacje o zbiorze danych. Przykład i szczegóły dotyczące wymienionych elementów XML znajdziesz poniżej.

Przykład

<info>
  <name>
    <value>Unemployment Rates</value>
  </name>
  <description>
    <value>Worldwide unemployment rates by region</value>
  </description>
  <url>
    <value>http://www.example.com/mystats/info.html</value>
  </url>
</info>

Elementy

Element Wymagana? Opis
<info> Tak Obejmuje wszystkie informacje opisowe w zbiorze danych. Zawiera elementy podrzędne <name>, <description> i <url>.
<name> Tak Element podrzędny elementu <info>. Zawiera element podrzędny <value>, który identyfikuje nazwę zbioru danych.
<description> Opcjonalna Element podrzędny elementu <info>. Zawiera element podrzędny <value>, który zawiera tekst opisu zbioru danych.
<url> Tak Element podrzędny elementu <info>. Link do adresu URL zawierającego więcej informacji o zbiorze danych.

Informacje o dostawcy

Element <provider> zawiera informacje o dostawcy zbioru danych. Przykład i szczegóły dotyczące wymienionych elementów XML znajdziesz poniżej.

Przykład

<provider>
  <name>
    <value>Bureau of Statistics</value>
  </name>
  <url>
    <value>http://www.example.com</value>
  </url>
</provider>

Elementy

Element Wymagana? Opis
<provider> Tak Obejmuje wszystkie opisowe informacje o dostawcy zbioru danych. Zawiera elementy podrzędne <name> i <url>.
<name> Opcjonalna Element podrzędny elementu <provider>. Zawiera element podrzędny <value>, który identyfikuje nazwę dostawcy zbioru danych.
<url> Opcjonalna Element podrzędny elementu <info>. Link do adresu URL zawierającego więcej informacji o dostawcy zbioru danych.

Pojęcia

Opis

Każdy zbiór danych zawiera co najmniej 1 koncepcję. Pojęcie to definicja określonego typu danych, które pojawiają się w zbiorze danych. Zbiór danych z danymi demograficznymi dotyczącymi populacji może na przykład zawierać pojęcia kraj, stan, populacja i rok. Wartości danych odpowiadające konkretnej koncepcji są nazywane instancjami tej koncepcji. Pojęcia są zwykle opisane w zbiorze danych, ale niektóre koncepcje (np. czas lub rok) mogą być opisane w zewnętrznych zbiorach danych.

Każda koncepcja może mieć jedną lub więcej właściwości. Właściwość to cecha instancji koncepcyjnej, która jest stabilna w czasie. Pojęcie na przykład może obejmować właściwości name, population i capital.

Pojęcia mogą też mieć jeden lub więcej atrybutów. Atrybuty dostarczają informacji na poziomie koncepcji, a nie poszczególnych wystąpień. Jeśli na przykład mamy zbiór danych z oceną stopy bezrobocia, to możemy użyć atrybutu, aby określić, że chodzi o wartość procentową. Innym typowym zastosowaniem atrybutów jest podanie informacji o jednostce.

Przykład

Oto przykład pojęcia kraju z unikalnym identyfikatorem country oraz właściwością name. Identyfikator koncepcji może służyć jako odniesienie do koncepcji z wycinków i tabel.

<concept id="country" extends="geo:location">
  <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>
  <property concept="geo:continent" isParent="true"/>
  <property id="capital" concept="geo:city" />
  <table ref="countries_table" />
</concept>

Oto jak działa ten przykładowy kod.

  • Ten kod opisuje kraj koncepcyjny, który ma identyfikator country oraz właściwości name, continent i capital.
  • Pojęcie rozszerza geo:location, koncepcję kanoniczną lokalizacji. Gdy rozszerzysz właściwość geo:location, country dziedziczy wszystkie właściwości i atrybuty zdefiniowane przez rozszerzoną koncepcję: nazwę, opis, adres URL, szerokość i długość geograficzną. country może ponownie zdefiniować niektóre z tych atrybutów i właściwości, o ile definicja jest zgodna z definicją w rozszerzonej koncepcji.
  • Element <info> odnosi się do kluczowych informacji. Informacje te są wyświetlane na stronie docelowej zbioru danych w eksploratorze danych publicznych.
  • Element <type> odnosi się do typu treści. W tym przypadku jest to ciąg znaków, który może się różnić. Pole „Populacja” miałoby typ integer; koncepcja Eurovision winner mogłaby mieć wartość logiczną.
  • Element <property> opisuje każdą właściwość koncepcji, w tym unikalny identyfikator (id), info i type. Właściwości mogą też odwoływać się do koncepcji, by wskazać, że ich wartości są prawidłowymi wystąpieniami tych pojęć.

  • Ta koncepcja odwołuje się do tabeli danych, która wskazuje plik CSV zawierający rzeczywiste dane. Odwołuje się do niej tabela danych: <table ref="countries_table"/>.

    Jeśli koncepcja odwołuje się do tabeli, powiązany plik danych musi zawierać listę wszystkich wystąpień koncepcji. Nie możesz np. utworzyć tabeli zawierającej tylko kilka krajów uwzględnionych w zbiorze danych. Jeśli jest jakiś podzbiór krajów, które Cię interesują, możesz utworzyć osobną koncepcję ich opisania. na przykład: mycountries).

Elementy

Element Wymagana? Opis
<concepts> Tak Element najwyższego poziomu. Obejmuje wszystkie elementy <concept>.
<concept> Tak Identyfikuje koncepcję. Wartość wymaganego atrybutu id musi być unikalna dla pojęcia w zbiorze danych. Jeśli koncepcja odwołuje się do tabeli danych koncepcyjnych, wartość id musi być zgodna z nagłówkiem kolumny opisującym koncepcję w tabeli danych. Atrybutu extends można używać do oznaczenia, że dotyczy on także innego terminu. Wartość właściwości extends musi odpowiadać identyfikatorowi pojęcia zdefiniowanego w tym samym zbiorze danych lub w formacie prefix:concept_id, gdzie concept_id to identyfikator pojęcia zdefiniowanego w importowanym zewnętrznym zbiorze danych powiązanym z elementem prefix.
<info> Opcjonalna Zawiera opisowe informacje o pojęciu.
<name> Tak Element podrzędny elementu <info>. Nazwa koncepcji. Element podrzędny <value> zawiera tekst – na przykład Country.
<description> Opcjonalna Element podrzędny elementu <info>. Zawiera element podrzędny <value>, który zawiera tekst opisu koncepcji.
<url> Opcjonalna Element podrzędny elementu <info>. Zawiera element podrzędny <value>, który zawiera adres URL koncepcji.
<pluralName> Opcjonalna Element podrzędny elementu <info>. Liczba mnoga oznaczająca koncepcję. Element podrzędny <value> zawiera tekst, na przykład Countries.
<totalName> Opcjonalna Element podrzędny elementu <info>. Nazwa kombinacji wszystkich wystąpień koncepcji. Element podrzędny <value> zawiera tekst – na przykład w przypadku koncepcji country może to być World.
<type> Opcjonalna Identyfikuje typ treści opisane w koncepcji. Wymagany atrybut ref ma następujące dozwolone wartości:
  • tekst
  • liczba zmiennoprzecinkowa
  • liczba całkowita
  • data
  • wartość logiczna
Typ może zostać pominięty, jeśli rozszerza się inna koncepcja. W takim przypadku element jest dziedziczony z koncepcji rozszerzonej.
<property> Opcjonalna

Właściwość koncepcji, np. capital. Wartość wymaganego atrybutu id musi być unikalna dla pomysłu. Możesz użyć opcjonalnego atrybutu concept, by wskazać, że wartości tej właściwości są wystąpieniami danego koncepcji. Jeśli podasz concept, możesz pominąć id, a jej wartość jest domyślnie definiowana jako identyfikator koncepcji, do której odwołuje się (np. <property concept="geo:country"/> jest tożsame z <property id="country" concept="geo:country"/>).

Właściwość może zawierać atrybut wartości logicznej isParent, który wskazuje, że relacja między wystąpieniem koncepcji a wartością tej właściwości jest hierarchiczna.

Usługa może zawierać wartość logiczną isMapping, która wskazuje, że występuje mapowanie 1–1 między instancjami koncepcji i jej wartościami.

Właściwość może zawierać zagnieżdżone atrybuty info i type, które są zdefiniowane tak samo jak w przypadku danego koncepcji. Jeśli właściwość nie określa atrybutu concept, właściwość type jest wymagana. Jeśli tak, musi ona odpowiadać rodzajowi koncepcji, do której się odwołuje.
<attribute> Opcjonalna

Atrybut koncepcji. Atrybuty reprezentują dodatkowe informacje na ten temat (np. PKB to wartość procentowa). Wartość wymaganego atrybutu id musi być unikalna dla pomysłu. Można użyć opcjonalnego atrybutu concept, aby wskazać, że wartości tego atrybutu są wystąpieniami danego pojęcia. Jeśli podasz concept, tag id może zostać pominięty. Jego wartość jest domyślnie definiowana jako identyfikator koncepcji, do której prowadzi odniesienie. (na przykład <attribute concept="unit:unit"/> jest odpowiednikiem <attribute id="unit" concept="unit:unit"/>.

Atrybut może zawierać zagnieżdżone atrybuty info i type, które są zdefiniowane tak samo jak w pojęciu. Atrybut type jest wymagany, jeśli atrybut nie ma określonego atrybutu concept, a jeśli go dotyczy, musi być zgodny z typem koncepcji.
<table> Opcjonalna Identyfikuje tabelę danych zawierającą dane pojęcia. Wartość wymaganego atrybutu ref musi być zgodna z identyfikatorem tabeli określonym w powiązanym elemencie <table>.

Wycinki

Opis

Wycinek to kombinacja pojęć, dla których istnieją dane. Wycinek zawiera 2 rodzaje odwołań do koncepcji: wymiary i dane. Wymiar to koncepcja, która służy do segmentowania lub filtrowania danych. Wskaźnik z kolei opisuje zaobserwowaną wartość lub wartości powiązane z każdym punktem danych.

Ogólnie wymiary są z kategoriami, a dane niekategoryzowane, z uwzględnieniem czasu i wartościami liczbowymi. Oto przykładowe etykiety:

  • Wymiary: kraj, stan, hrabstwo, region, rok, miesiąc, płeć, kategoria wiekowa, segment branży
  • Wskaźniki: populacja, PKB, stopa bezrobocia, kompetencje, przychody, koszt, cena

Przykład

<slices>
  <slice id="country_slice">
    <dimension concept="country"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <table ref="country_slice_table"/>
  </slice>
  ...
</slices>

Oto jak działa ten przykładowy kod.

  • Ten wycinek przedstawia populację według kraju.
  • Ma dane population, wymiary country i year. Każdy wymiar to pojęcie zdefiniowane już w innym miejscu. Koncepcja country i wskaźnik population znajdują się w tym samym zbiorze danych co bieżący wycinek, a odwołanie wygląda tak: concept="country"
  • Pojęcie year występuje w zaimportowanym zbiorze danych, określonym przez prefiks używany przed nazwą koncepcji (year): tak: concept="time:year"
  • Wycinek odwołuje się do tabeli danych wskazującej plik CSV zawierający rzeczywiste dane. Tabela danych odwołuje się w ten sposób: <table ref="country_slice_table"/>. (powyżej znajdziesz informacje na temat importowania zbiorów danych);

Uwaga: ogólnie Twój zbiór danych będzie bardziej elastyczny, jeśli ograniczysz wskaźniki do wartości minimalnych i utworzysz istotne wymiary. Na przykład zamiast tworzyć wskaźniki Female Unemployment i Male Unemployment, utwórz jeden rodzaj danych Unemployment i dodaj wymiar Gender zawierający wystąpienia Female i Male.

Elementy

Element Wymagana? Opis
<slices> Tak Element najwyższego poziomu. Obejmuje wszystkie elementy <slice>.
<slice> Opcjonalna Określa wycinek. Wartość wymaganego atrybutu id musi być unikalna dla wycinka.
<dimension> Opcjonalna Określa wymiar wycinka przez odniesienie do koncepcji. Wartość wymaganego atrybutu concept musi dokładnie odpowiadać niepowtarzalnemu identyfikatorowi koncepcji. Jeśli atrybut należy do zewnętrznego zbioru danych, musi zawierać prawidłowy prefiks.
<metric> Opcjonalna Określa dane wycinka przez odniesienie do koncepcji. Wartość wymaganego atrybutu concept musi dokładnie odpowiadać niepowtarzalnemu identyfikatorowi koncepcji. Jeśli atrybut należy do zewnętrznego importowanego zbioru danych, musi zawierać prawidłowy prefiks.
<table> Tak Identyfikuje tabelę danych zawierającą dane wycinka. Wartość wymaganego atrybutu ref musi być zgodna z identyfikatorem tabeli określonym w powiązanym elemencie <table>.
<mapDimension> Opcjonalna Element podrzędny elementu <table>. Zawiera atrybuty concept i toColumn. Wartość pierwszego elementu to wymiar w segmencie, a drugi – kolumna tabeli odpowiadająca pierwszemu.
<mapMetric> Opcjonalna Element podrzędny elementu <table>. Zawiera atrybuty concept i toColumn. Wartość pierwszego elementu to dane w grupie, a druga – tabeli w tabeli odpowiadającej pierwszemu.

Tabele

Opis

Sekcja tables pliku DSPL wskazuje tabele danych uwzględnione w zbiorze danych. Do tabel mogą się odwoływać pojęcia lub wycinki. Każdy element <table> określa kolumny tabel i ich typy oraz wskazuje plik CSV zawierający dane tabeli.

Przykład

<tables>
  <table id="country_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>

Oto jak działa ten przykładowy kod.

  • W tym przykładzie opisano tabelę country_slice_table. Tabela zawiera kolumny country, year i population.
  • Każda kolumna w tabeli ma unikalny identyfikator określony przez atrybut id. Ten identyfikator musi być zgodny z odpowiednim nagłówkiem kolumny w powiązanym pliku danych.
  • Wartość opcjonalnego atrybutu type określa typ danych dla każdej kolumny.
  • Element <data> opisuje rzeczywisty plik .csv (kraj_fragmenty.csv) zawierający dane tabeli. Format pliku to zawsze csv.

Elementy

Element Wymagana? Opis
<tables> Tak Element najwyższego poziomu. Obejmuje wszystkie elementy <table>.
<table> Tak Identyfikuje tabelę. Wartość wymaganego atrybutu id musi być unikalna w tabeli.
<column> Opcjonalna Element podrzędny elementu <table>. Informacje o kolumnie w tabeli. Obejmuje te atrybuty:
  • id (wymagany): identyfikator kolumny.
  • type (opcjonalnie): typ danych w określonej kolumnie. Dozwolone wartości to string, float, integer, date i boolean.
<data> Opcjonalna Element podrzędny elementu <table>. Plik danych, do którego odwołuje się tabela. Jeśli nazwa pliku ma postać adresu URL (np. http://...), plik zostanie pobrany za pomocą odpowiedniego protokołu (HTTP, HTTPS lub FTP). W przeciwnym razie plik o tej nazwie musi być powiązany ze zbiorem danych. Wartość wymaganego atrybutu format to zawsze csv. Chociaż atrybut encoding jest opcjonalny, pliki .csv muszą być zakodowane w formacie UTF-8.

Tematy

Opis

Tematy klasyfikują hierarchię, co pozwala użytkownikom łatwiej poruszać się po zbiorze danych.

Element <topics> powinien pojawić się w pliku DSPL bezpośrednio przed elementem <concepts>. (Kolejność elementów jest ważna, przez co przesyłanie zbioru danych może być niemożliwe, jeśli elementy będą wyświetlane w niewłaściwej kolejności). Aby używać tematów, odwołuj się do nich przy użyciu definicji koncepcji.

Przykład

Oto przykład definicji tematu:

<topics>
  <topic id="population_indicators">
    <info>
      <name>
        <value>Population indicators</value>
      </name>
    </info>
  </topic>
  ...
</topics>

...a oto przykład odwołania do tego tematu z koncepcji:

<concept id="population">
  <info>
    <name>
      <value>Population</value>
    </name>
    <description>
      <value>Size of the resident population.</value>
    </description>
  <topic ref="population_indicators"/>
  <type ref="integer"/>
</concept>

Tematy można zagnieżdżać, a koncepcja może odnosić się do więcej niż 1 tematu.

Definicja elementu

Element Wymagana? Opis
<topics> Tak Element najwyższego poziomu. Obejmuje wszystkie elementy <topic>.
<topic> Tak Identyfikuje temat. Wartość wymaganego atrybutu id musi być unikalna dla zbioru danych.
<info> Opcjonalna Element podrzędny elementu <topic>. Obejmuje informacje na dany temat.
<name> Opcjonalna Element podrzędny elementu <info>. Element podrzędny <value> określa nazwę tematu.

Pliki danych DSPL

Oprócz pliku metadanych w formacie XML zbiór danych DSPL może zawierać również jeden lub więcej plików danych w formacie CSV. Każdy plik danych obsługuje tabelę w zbiorze danych i odwołuje się do niej z pierwszej w sekcji <data>...</data>. Zasadniczo te pliki i powiązane z nimi tabele służą do definiowania definicji pojęć lub wycinków. Każdy z tych typów danych został szczegółowo opisany poniżej.

Pamiętaj, że bez względu na cel wszystkie pliki danych muszą być rozdzielane przecinkami (CSV) w formacie tekstowym UTF-8. Pliki mogą zawierać tylko zwykły tekst, bez kodu HTML. Możesz tworzyć pliki danych ręcznie, ale w rzeczywistości musisz masować je w narzędziu zawierającym oryginalne źródło danych (np. w arkuszu kalkulacyjnym) lub w wyeksportowanym pliku.

Pliki można połączyć w zbiór danych ze zbiorem danych lub, jeśli nazwa ma postać adresu URL, być pobierane przez HTTP, HTTPS lub FTP ze źródła zdalnego.

Pliki danych koncepcyjnych

Pliki danych koncepcyjnych zawierają odpowiednie informacje dotyczące poszczególnych koncepcji. Definicja koncepcji używa elementu <table> do odwoływania się do tego pliku.

Przykład

Oto przykład tabeli dotyczącej koncepcji country zdefiniowanej powyżej:

country, name
AD, Andorra
AF, Afghanistan
AI, Anguilla
AL, Albania
AO, Angola
AQ, Antarctica
AS, American Samoa

Oto przykład działania:

  • Jeśli nie określono mapowania, pierwszy wiersz pliku danych (nagłówki kolumn) musi być taki sam jak identyfikator koncepcji i odpowiednie identyfikatory właściwości pojęcia, z którym są powiązane dane. Kolejność kolumn w pliku danych i w tabeli koncepcji nie musi jednak być taka sama. W tym przypadku pierwsza kolumna jest powiązana z koncepcją country, a druga – z właściwością name.
  • Kolumny usługi są opcjonalne. Jeśli usługa nie ma kolumny w tabeli, przyjmuje się, że jej wartość jest niezdefiniowana dla każdego wiersza. Na przykład w tabeli powyżej brakuje kolumn właściwości latitude i longitude, więc krajów nie będzie można mapować.
  • Każda wartość w polu identyfikatora pomysłu (w tym przypadku: country) musi być unikalna i nie może być pusta (puste pole musi zawierać zero lub tylko spacje).
  • Wartości właściwości, które odwołują się do innych pojęć, muszą być puste lub zawierać prawidłową wartość.
  • Jeśli wartości są ujęte w cudzysłów podwójny, to opcjonalne, chyba że zawierają przecinki, podwójne cudzysłowy lub znaki nowego wiersza.
  • Zmień znaczenie podwójnego cudzysłowu, który pojawia się w wartości, poprzedzając ją cudzysłowem prostym.

Pliki danych wycinka

Pliki danych wycinka zawierają odpowiednie dane dla każdego wycinka. Definicja wycinka używa elementu <table ref="..."> do odwołania do definicji <table>, która z kolei identyfikuje ten plik.

Przykład

Oto przykład pliku CSV z danymi wycinka z population_by_country opisanego powyżej:

country, year, population
AF, 1960, 9616353
AF, 1961, 9799379
AF, 1962, 9989846
AF, 1963, 10188299

Oto przykład działania:

  • Pole danych to population. Pola country i year to pola wymiarów.
  • Każda wartość pola wymiaru nie może być pusta. Obejmuje to też czas. Wartości w polach danych mogą być puste. Pusta wartość jest reprezentowana przez brak znaku.
  • Każdy nagłówek kolumny, który odwołuje się do koncepcji (np. pierwsze pole powyższego przykładu odnosi się do koncepcji country) musi być taki sam jak jej unikalny identyfikator w definicji.
  • Unikalna kombinacja wartości wymiarów, np. AF, 2000, może wystąpić tylko raz.
  • Wiersze w tym samym ciągu czasowym (tzn. wiersze, które mają tę samą kombinację wszystkich wartości wymiarów z wyjątkiem godziny) muszą być zgrupowane, ale nie muszą być posortowane w inny sposób.

Funkcje zaawansowane

Zbiory danych w wielu językach

Przetłumaczone wartości XML

Możesz użyć atrybutu xml:lang w każdym elemencie <value> w pliku DSPL. Ten język określa język treści elementu za pomocą standardowych tagów języka W3C. Korzystanie z tej funkcji jest opcjonalne. Jeśli nie uwzględnisz atrybutu xml:lang, treść jest uznawana za język angielski.

Poniższy przykład pokazuje fragmenty zbioru danych w języku angielskim, bułgarskim, katalońskim i chińskim uproszczonym:

<dspl ...>
  <info>
    <name>
      <value xml:lang="en">World Bank, World Development Indicators</value>
      <value xml:lang="bg">Световна банка, Индикатори за световно развитие</value>
      <value xml:lang="ca">Banc Mundial, Indicadors del desenvolupament mundial</value>
      <value xml:lang="zh-CN">国家/地区</value>
    </name>
    ...
  </info>

  <concepts>
    <concept id="country">
      <info>
        <name>
          <value xml:lang="en">Country</value>
          <value xml:lang="bg">Страна</value>
          <value xml:lang="ca">País</value>
          <value xml:lang="zh-CN">国家/地区</value>
        </name>
        ...
      </info>
      ...
    </concept>
    ...
  </concepts>

  ...
</dspl>

Przetłumaczone właściwości

W niektórych przypadkach możesz chcieć dostarczyć tłumaczenia, które wykraczają poza metadane na poziomie koncepcji i są stosowane (a nie tylko) do poszczególnych instancji. Jest to szczególnie przydatne, gdy wartości właściwości koncepcji (np. nazwy) różnią się w zależności od języka.

Aby podać takie wartości w wielu językach, utwórz po jednej kolumnie w odpowiedniej tabeli definicji dla każdej kombinacji usługi i języka. Następnie połącz te kolumny z odpowiednimi właściwościami i językami, dodając do tagu odniesienia do tabeli zestaw elementów <mapProperty xml:lang="..." ref="..." toColumn="...">.

Oto przykład, który definiuje koncepcję kraju z nazwami w języku angielskim, hiszpańskim i francuskim:

<concepts>
  ...
  <concept id="country" extends="geo:location">
    ...
    <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">
      <mapProperty xml:lang="en" ref="name" toColumn="name_en"/>
      <mapProperty xml:lang="es" ref="name" toColumn="name_es"/>
      <mapProperty xml:lang="fr" ref="name" toColumn="name_fr"/>
    </table>
  </concept>
  ...
</concepts>

...

<tables>
  ...
  <table id="countries_table">
    <column id="country" type="string"/>
    <column id="name_en" type="string"/>
    <column id="name_es" type="string"/>
    <column id="name_fr" type="string"/>
    ...
  </table>
</tables>

Plik CSV dotyczący zasobu countries_table miałby wtedy taką postać:

country,name_en,name_es,name_fr,...
...
US,United States of America,Estados Unidos de América,États-Unis d'Amérique,...
...

Koncepcje mapowa

Wiele pojęć (np. hrabstwo, stan czy miasto) zawiera wystąpienia odpowiadające lokalizacjom geograficznym. DSPL obsługuje geokodowanie tych instancji, dzięki czemu można je zwizualizować na wykresie animowanym Map publicznych danych Google.

Jeśli koncepcja jest taka sama jak w krajach, stanach lub hrabstwach w Stanach Zjednoczonych, możesz po prostu dodać link do odpowiedniej kanonicznej koncepcji Google, która nie wymaga precyzyjnego geokodowania. Więcej informacji znajdziesz w przewodniku po koncepcjach kanonicznych.

Jeśli nie, to musisz stworzyć mapę z koncepcją. Pierwszym krokiem jest rozszerzenie z geo:location:

<concept id="..." extends="geo:location">
  ...
</concept>

Następnie musisz wyraźnie podać szerokość i długość geograficzną jako właściwości:

<concept id="..." extends="geo:location">
  ...
  <property id="latitude"/>
  <property id="longitude"/>
</concept>

Wartości są następnie określane jako kolumny w odpowiedniej tabeli danych definicji koncepcji.

Relacje koncepcyjne

Pojęcia często odnoszą się do innych pojęć w uporządkowany sposób. Instancja kontynentu może na przykład obejmować wiele krajów, co z kolei może obejmować wiele wystąpień stanu lub prowincji. Zakodowanie tych relacji do metadanych zbioru danych daje większe możliwości wizualizacji, niż byłoby to możliwe w inny sposób, np. wyświetlanie zwijanego drzewa lokalizacji.

W sekcjach poniżej opisujemy relacje koncepcyjne obsługiwane w schemacie DSPL.

Hierarchie

Hierarchie koncepcji są przedstawiane w DSPL za pomocą atrybutu isParent="true" w tagu <property> pojęcia podrzędnego, które zawiera identyfikatory instancji nadrzędnych.

Oto przykład koncepcji hrabstwa Google w USA:

<concept id="us_county" extends="geo:location">
  <info>
    <name>
      <value xml:lang="en">County</value>
    </name>
    ...
  </info>
  ...
  <property id="state" concept="us_state" isParent="true"/>
  ...
  <data>
    <table ref="reference_us_counties"/>
  </data>
</concept>

Obsługiwana tabela danych zawiera kolumnę state z dwuliterowym kodem stanu dla każdego hrabstwa. Ten typ metadanych umożliwia eksploratorowi danych publicznych wyświetlanie stanów i hrabstw jako hierarchii, co znacznie ułatwia użytkownikom eksplorację.

Pamiętaj, że koncepcja może mieć wiele dzieci, ale nie więcej niż 1 rodzica.

Mappings (Mapowania)

Mapowanie pojęć (czyli pojęcia, które zasadniczo oznaczają, że to samo) są przedstawione za pomocą atrybutu isMapping="true" w tagu property zmapowanego koncepcji.

Dzięki temu, że jedna koncepcja jest mapowana na drugą, może ona dziedziczyć wszystkie właściwości i atrybuty drugiej. Przydaje się między innymi w przypadku „połączenia” koncepcji osobistej z definicjami zawartymi w kanonicznym zbiorze danych geograficznych Google:

<concept id="my_country" extends="geo:location">
  <info>
    <name>
      <value xml:lang="en">Country</value>
    </name>
    ...
  </info>
  ...
  <property id="google_country_code" concept="geo:country" isMapping="true"/>
  <data>
    <table ref="countries_concept"/>
  </data>
</concept>

Rozszerzenia

Rozszerzenia koncepcji są określane przez element extends w odpowiedniej definicji koncepcji. Rozszerzenia są przydatne, ponieważ wskazują, że dana koncepcja jest podklasą innej, szerszej koncepcji. Rozszerzona koncepcja dziedziczy wszystkie atrybuty i właściwości nadrzędne, a także dodaje kolejne.

Na przykład koncepcja currency w Google obejmuje również unit:

<concept id="unit">
  ...
</concept>

<concept id="currency" extends="unit">
  <info>
    <name>
      <value xml:lang="en">Currency unit</value>
    </name>
    ...
  </info>
  ...
  <table ref="currency_table"/>
</concept>

Więcej informacji i przykładów znajdziesz w sekcji poświęconej rozszerzeniom koncepcji w tym samouczku.

Przesyłanie zbioru danych

Aby przesłać zbiór danych do Eksploratora danych publicznych Google, wykonaj te czynności:

  1. Utwórz katalog.
  2. Zapisz plik dspl zbioru danych w utworzonym katalogu. Użyj rozszerzenia .xml.
  3. Zapisz wszystkie lokalne pliki CSV w tym katalogu. Pliki danych, do których odwołuje się adres URL, mogą zostać pominięte.
  4. Spakuj katalog.
  5. Prześlij zbiór danych do Eksploratora danych publicznych Google.

Po przesłaniu i zweryfikowaniu zbioru danych możesz go przetestować po zalogowaniu się na konto Google. Nie zostanie opublikowany, dopóki go nie sprawdzisz i nie potwierdzisz, że jest gotowy.