Książka kucharska DSPL

Ten dokument zawiera książkę kucharską z przydatnymi informacjami o DSPL i kanonicznym pojęciu „przepisy”. Znajdziesz tam szczegółowe instrukcje dotyczące różnych zadań, które wykraczają poza podstawowe funkcje językowe opisane w samouczku i w przewodniku dla programistów. W treściach założono, że użytkownik zna poprzednie dokumenty, dlatego zapoznaj się z nimi, zanim rozpoczniesz „gotowanie”.

Każdy przepis zaczyna się od celu, po którym następuje konkretna lista czynności. Wiele z nich zawiera też fragmenty kodu DSPL lub linki do przykładów zewnętrznych. Jeśli chcesz podzielić się opinią na temat przepisu lub zaproponować inne dania, opublikuj wiadomość na forum DSPL.

Przepisy podstawowe

Określanie wyświetlanych nazw

Cel

Powiąż „wyświetlaną nazwę” z każdym wystąpieniem koncepcji (wymiaru). Te nazwy pojawią się w interfejsie Public Data Explorer, a nie w identyfikatorach instancji koncepcji, które są zwykle krótsze i trudniejsze do zrozumienia dla użytkowników.

Instrukcje

1. Niech entity:entity. się rozwinie
2. Dodaj kolumnę name do tabeli z powiązaną definicją koncepcji.
3. W tej drugiej właściwości wpisz nazwę każdej instancji.

Uwagi

• W metadanych koncepcji nie musisz wyraźnie określać właściwości name. Ta definicja jest automatycznie uwzględniana po rozszerzeniu entity:entity.
• Możesz też dodać kolumny description i info_url, aby odpowiednio dodać opisy i adresy URL na poziomie instancji.

Tworzenie hierarchii koncepcji

Cel

Utwórz hierarchię pojęć (wymiarów). Będą one widoczne w interfejsie Public Data Explorer jako drzewa, co umożliwia użytkownikom zrozumienie grupowania i przechodzenie między nimi.

Instrukcje

1. Określ koncepcję „nadrzędnego” (np. region).
2. Określ koncepcję „dziecka” (np. subregion).
3. Dodaj w elemencie podrzędnym właściwość odwołującą się do elementu nadrzędnego, która zawiera atrybut isParent:

   <property concept="..." isParent="true"/>
   

   , gdzie kropki są zastępowane identyfikatorem nadrzędnym.
4. W tabeli definicji obiektu podrzędnego dodaj kolumnę, która odwołuje się do elementu nadrzędnego.
5. W każdej instancji podrzędnej uzupełnij prawidłową instancję koncepcji nadrzędnej.

Uwagi

• Przykład znajdziesz w relacji country/state w zbiorach danych do samouczka.
• Każdy identyfikator nadrzędny, do którego odwołuje się wydawca podrzędny, musi znajdować się w tabeli definicji obiektu nadrzędnego. W przeciwnym razie importer wygeneruje błąd.
• Podmiot nadrzędny i podrzędny mogą mieć tę samą koncepcję (czyli hierarchię, która odsyła do siebie). Aby to zrobić, zapoznaj się z koncepcją business w zbiorze danych o sprzedaży detalicznej amerykańskiej.

Kategoryzowanie instancji koncepcji

Cel

Utwórz kategorie dla instancji koncepcji, które będą wyświetlane jako opcje w selektorach kolorów Eksploratora danych publicznych.

Instrukcje

1. Określ koncepcję „kategorii” (np. income_level).
2. Określ koncepcję „dziecka” (np. country).
3. Dodaj w elemencie podrzędnym właściwość odwołującą się do koncepcji kategorii i zawierającą element name:

   <property concept="..."/>
     <info>
       <name><value>"..."</value></name>
     </info>
   </property>
   

   , gdzie pierwszy zestaw kropek jest zastąpiony identyfikatorem koncepcji kategorii, a drugi jest zastąpiony żądaną wyświetlaną nazwą Twojej usługi (np. „Poziom przychodu”).
4. W tabeli definicji obiektu podrzędnego dodaj kolumnę, która odwołuje się do koncepcji kategorii.
5. W przypadku każdej instancji podrzędnej wypełnij prawidłową instancję koncepcji kategorii.

Uwagi

• Koncepcja może mieć wiele właściwości, które służą jako kategorie. W tym przypadku użytkownik zobaczy je wszystkie jako opcje w selektorach kolorów.
• Jedna z kategorii może być również nadrzędna na potrzeby hierarchii instancji w hierarchii. Szczegóły znajdziesz w poprzednim przepisie.

Określanie kolejności sortowania instancji koncepcji

Cel

Określ kolejność sortowania wystąpień koncepcji. Ta kolejność jest używana na liście instancji w panelu po lewej stronie stron wizualizacji w narzędziu Public Data Explorer.

Instrukcje

1. Uzupełnij swój zasób o element entity:entity lub jedno z jego obiektów podrzędnych (np. geo:location).
2. Dodaj atrybut entity_order do metadanych koncepcji.
3. Ustaw wartość poprzedniej na jedną z tych wartości: ALPHA lub TABLE. W pierwszej instancji instancje będą wyświetlane w takiej kolejności, w jakiej były wyświetlane, a druga będzie utrzymywać je w tej samej kolejności, w jakiej występują w tabeli definicji koncepcji.

Uwagi

• ALPHA jest domyślną wartością domyślną, więc jeśli chcesz użyć tej kolejności, powyższe czynności są opcjonalne.
• Przykład znajdziesz w dokumentacji entity:entity.

Przepisy kulinarne

Dane kwartalne

Cel

Wizualizacja danych określonych w odstępach kwartalnych.

Instrukcje

1. Przekonwertuj wszystkie kwartały w danych o wycinkach na miesiące (np. w pierwszym miesiącu kwartału).
2. Traktuj ten wymiar jako time:month w wycinku XML.

Dane tygodniowe

Cel

Wizualizacja danych określonych w odstępach tygodniowych.

Instrukcje

1. Przekonwertuj wszystkie tygodnie w danych o wycinkach na dni (np. pierwszego dnia tygodnia).
2. Traktuj ten wymiar jako time:day w wycinku XML.

Przepisy geograficzne

Stosuje koncepcje kanoniczne na poziomie country lub state

Cel

Użyj kanonicznych wartości country lub state, importując wszystkie wartości długości i szerokości geograficznej itp., aby nie trzeba było ich określać w zbiorze danych.

Instrukcje

1. Sprawdź, czy wszystkie odwołania do kraju lub stanu w plikach CSV wycinków są prawidłowymi identyfikatorami z tabel kanonicznych krajów i stanów.
2. Dodaj geo:country lub geo_us:state jako wymiary w odpowiednich wycinkach.
3. Sprawdź, czy nazwy tych kolumn są zgodne z nazwami poprzednich pojęć (bez nazwy importowanego zbioru danych, np. country) lub – jeśli tak nie jest – w definicji wycinka umieść instrukcje mapDimension. Przykład:

   <slice id="...">
     ...
     <dimension concept="geo:country"/>
     ...
     <mapDimension concept="geo:country" toColumn="my_country"/>
   </slice>
   

Używanie tylko podzbioru krajów lub stanów kanonicznych

Cel

Użyj podzbioru koncepcji geograficznej, tak aby w interfejsie Public Data Explorer wyświetlił się tylko ten podzbiór (a nie cała lista, np. wszystkie kraje).

Instrukcje

1. Zdefiniuj koncepcję lokalną, która rozszerza koncepcję nadrzędną. Przykład:

   <concept id="my_country_subset" extends="geo:country">
   ...
   </concept>
   

2. W pliku CSV z powiązaną koncepcją podaj tylko identyfikatory elementu nadrzędnego, którego chcesz użyć. Przykład:

   my_country_subset
   FR  
   MX
   US
   

Uwagi

• Każde wystąpienie koncepcji podzbioru musi być prawidłową instancją koncepcji nadrzędnej. Nie można „rozwijać” koncepcji za pomocą nowych instancji.

Tworzenie własnych pojęć geograficznych

Cel

Twórz własne koncepcje geograficzne, które są zrozumiałe i mapowane, tak samo jak kanoniczne i definiowane przez Google.

Instrukcje

1. Utwórz koncepcję, która rozciąga się do geo:location.
2. W tabeli definicji koncepcji uwzględnij kolumny name, latitude i longitude.
3. Określ te właściwości w każdym wystąpieniu koncepcji. Wartości szerokości i długości geograficznej są liczbami zmiennoprzecinkowymi zgodnie z wartością dodatnią, a i E – ujemne.

Uwagi

• W definicji koncepcji nie musisz jednoznacznie uwzględniać właściwości name, latitude i longitude, ponieważ występują one automatycznie podczas rozszerzania geo:location.
• Przykład znajdziesz w definicji obiektu state w zbiorze danych samouczka.

Przepisy dotyczące danych i jednostek

Na podstawie wartości procentowych

Cel

Zdefiniuj koncepcję (dane) stanowiącą odsetek czegoś innego.

Instrukcje

1. Niech quantity:ratio się rozwinie.
2. Ustaw atrybut is_percentage na true.

   <attribute id="is_percentage">
     <value>true</value>
   </attribute>
   

3. Opcjonalnie ustaw atrybut percentage_of na podstawie wartości procentowej, której używa ta koncepcja. Przykład:

   <attribute id="percentage_of">
     <value>labor force</value>
   </attribute>
   

Używasz currency jednostek

Cel

Zdefiniuj koncepcję (dane) zawierającą jednostki walutowe (np. dolar amerykański).

Instrukcje

1. Ustaw wskaźnik jako rozszerzenie quantity:quantity lub jednego z jego elementów podrzędnych, np. quantity:amount.
2. Dodaj atrybut unit, który odwołuje się do unit:currency i ustaw jego wartość na identyfikator z powiązanej tabeli definicji waluty. Przykład:

   <concept id="...">
     <attribute concept="unit:currency">
       <value>EUR</value>
     </attribute>
   </concept>
   

Tworzenie jednostki niestandardowej

Cel

Utwórz jednostkę niestandardową dla wybranych danych.

Instrukcje

1. Utwórz koncepcję, która rozciąga się do unit:unit.
2. Dodaj kolumny unit_text i symbol do powiązanej tabeli definicji. Opcjonalnie, jeśli chcesz dostosować pozycję symbolu, możesz też dodać kolumnę symbol_position.
3. Wypełnij właściwości pozostałych właściwości każdej instancji jednostki. Przykładowy plik CSV dla jednostek „obszaru”:

   my_unit,unit_text,symbol,symbol_position
   SQKM,square kilometers,km²,END
   SQML,square miles,miles²,END
   

4. Aby używać nowo utworzonej jednostki w koncepcji (dane), upewnij się, że to drugie rozszerzenie obejmuje rozszerzenie quantity:quantity lub jedno z jego elementów podrzędnych. Następnie dodaj atrybut, który odwołuje się do koncepcji jednostki. Przykład:

   <concept id="..." extends="quantity:amount">
     ...
     <attribute concept="my_unit">
       <value>SQKM</value>
     </attribute>
     ...
   </concept>
   

Uwagi

• Jeśli koncepcja jednostki ma tylko jedną instancję, możesz pominąć kolumnę Identyfikator w tabeli definicji i tagi value w wskaźnikach, które jej używają.
• Pełny przykład znajdziesz w definicji koncepcji waluty kanonicznej.