DSPL Cookbook

This document contains a cookbook of useful DSPL and canonical concept "recipes". These provide step-by-step directions for a variety of tasks that go above and beyond the basic language features described in the Tutorial and Developer Guide. The content below assumes knowledge of the previous documents, so be sure to read through them before beginning your "cooking".

Each recipe begins with a goal followed by a specific list of steps to follow. Many also include DSPL snippets or links to external examples. If you have any feedback about a recipe or would like to suggest others, please post a message in the DSPL Forum.

Basic Recipes

Specifying display names

Goal

Associate a "display name" with each instance of a (dimension) concept. These names will show up in the Public Data Explorer UI instead of the concept instance IDs, which are generally shorter and harder for users to understand.

Steps

Make your concept extend entity:entity.
Add a name column to the associated concept definition table.
Populate the latter property with the name of each instance.

Notes

There is no need to explicitly define a name property in your concept metadata; this definition is automatically included when you extend entity:entity.
You can also add description and info_url columns to provide instance-level descriptions and URLs, respectively.

Creating concept hierarchies

Goal

Create a hierarchy of (dimension) concepts. These will show up in the Public Data Explorer UI as a tree, allowing users to understand the groupings and navigate between them.

Steps

Define a "parent" concept (e.g., region).
Define a "child" concept (e.g., subregion).
Add a property in the child that references the parent and includes the isParent attribute:
```
<property concept="..." isParent="true"/>
```
where the dots are replaced by the parent ID.
In the definition table for the child, add a column that references the parent.
For each child instance, populate the latter with a valid instance of the parent concept.

Notes

See the country / state relationship in the tutorial dataset for an example of this.
Each parent ID referenced from the child must be in the parent's definition table. Otherwise, the importer will produce an error.
The parent and child can be the same concept (i.e., a self-referencing hierarchy). See the business concept in the US Retail Sales Dataset for an example of this.

Categorizing concept instances

Goal

Create categories for concept instances that will show up as options in the Public Data Explorer color pickers.

Steps

Define a "category" concept (e.g., income_level).
Define a "child" concept (e.g., country).
Add a property in the child that references the category concept and includes a name element:
```
<property concept="..."/>
  <info>
    <name><value>"..."</value></name>
  </info>
</property>
```
where the first set of dots is replaced by the category concept ID and the second set is replaced by the desired display name for your property (e.g., "Income Level").
In the definition table for the child, add a column that references the category concept.
For each child instance, populate the latter with a valid instance of the category concept.

Notes

A concept can have multiple properties that serve as categories; in this case, the user will see all of them as options in the color pickers.
One of the categories can also be a parent for the purposes of organizing the instances hierarchically in the UI. See the previous recipe for details.

Specifying the sort order for concept instances

Goal

Specify the sort order for instances of a concept. This order is used when listing the instances in the left-nav of the Public Data Explorer visualization pages.

Steps

Make your concept extend entity:entity or one of its children (e.g., geo:location).
Add an entity_order attribute to your concept metadata.
Set the value of the previous to one of ALPHA or TABLE; the former will cause the instances to be listed in order of their display names, whereas the latter will keep the instances in the same order as they appear in the concept definition table.

Notes

ALPHA is the current default, so if you'd like to use this ordering, the above steps are optional.
See the entity:entity documentation for an example.

Time Recipes

Quarterly data

Goal

Visualize data that is specified at quarterly intervals.

Steps

Convert all of the quarters in your slice data to months (e.g., the first month of the quarter).
Treat this dimension as a time:month in your slice XML.

Weekly data

Goal

Visualize data that is specified at weekly intervals.

Steps

Convert all of the weeks in your slice data to days (e.g., the first day of the week).
Treat this dimension as a time:day in your slice XML.

Geo Recipes

Using `country` or `state` canonical concepts

Goal

Use the canonical country or state concepts, importing all of the lat/long values, etc., so that these don't need to defined within the dataset.

Steps

Make sure that all of the country and/or US state references in your slice data CSVs are valid IDs from the canonical country and state definition tables.
Add geo:country and/or geo_us:state as dimensions in the corresponding slices.
Make sure that the column names for these match the names of the previous concepts (not including the imported dataset name, e.g., country) or, if not, include mapDimension statements in your slice definition. Example:
```
<slice id="...">
  ...
  <dimension concept="geo:country"/>
  ...
  <mapDimension concept="geo:country" toColumn="my_country"/>
</slice>
```

Using only a subset of the canonical countries or states

Goal

Use a subset of a canonical geo concept so that only this subset (and not the entire list, e.g. all the countries in the world) appears in the Public Data Explorer UI.

Steps

Define a local concept that extends the superset concept. Example:

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

In the associated concept definition CSV, only include the IDs of the superset concept that you want to use. Example:
```
my_country_subset
FR  
MX
US
```

Notes

Each instance of your subset concept must be a valid instance of the superset concept; you cannot "expand" the concept with new instances.

Defining your own geographic concepts

Goal

Create your own geographic concepts that are explorable and mappable, just like the canonical, Google-defined ones.

Steps

Create a concept that extends geo:location.
In the associated concept definition table, include the columns name, latitude, and longitude.
Populate the latter properties for each instance of your concept; the latitude and longitude values are floats with the convention that N and E are positive, and W and S are negative.

Notes

There is no need to explicitly include the name, latitude, and longitude properties in your concept definition as these are automatically included when extending geo:location.
See the definition of state in the tutorial dataset for an example.

Metric and Unit Recipes

Using percents

Goal

Define a (metric) concept that is a percentage of something else.

Steps

Make your concept extend quantity:ratio.

Set the is_percentage attribute to true.

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

Optionally, set the percentage_of attribute based on what this concept is a percentage of. Example:
```
<attribute id="percentage_of">
  <value>labor force</value>
</attribute>
```

Using `currency` units

Goal

Define a (metric) concept that has currency units (e.g., US dollar).

Steps

Make your metric extend quantity:quantity or one of its children, e.g. quantity:amount.
Add a unit attribute that references unit:currency and set the value of this to an ID from the associated currency definition table. Example:
```
<concept id="...">
  <attribute concept="unit:currency">
    <value>EUR</value>
  </attribute>
</concept>
```

Creating a custom unit

Goal

Create a custom unit for one or more of your metrics.

Steps

Create a concept that extends unit:unit.
Add the columns unit_text and symbol to the associated definition table. Optionally, if you'd like to adjust the symbol position, you can also add a symbol_position column.
Fill in the values for the latter properties for each instance of your unit. Example CSV for "area" units:
```
my_unit,unit_text,symbol,symbol_position
SQKM,square kilometers,km²,END
SQML,square miles,miles²,END
```
To use your newly created unit in a (metric) concept, make sure the latter extends quantity:quantity or one of its children. Then, add an attribute that references your unit concept. Example:
```
<concept id="..." extends="quantity:amount">
  ...
  <attribute concept="my_unit">
    <value>SQKM</value>
  </attribute>
  ...
</concept>
```

Notes

If your unit concept has only a single instance, you can omit the ID column from its definition table as well as the value tags in the metrics that use it.
See the definition of the canonical currency concept for a complete example.

DSPL Cookbook

Basic Recipes

Specifying display names

Goal

Steps

Notes

Creating concept hierarchies

Goal

Steps

Notes

Categorizing concept instances

Goal

Steps

Notes

Specifying the sort order for concept instances

Goal

Steps

Notes

Time Recipes

Quarterly data

Goal

Steps

Weekly data

Goal

Steps

Geo Recipes

Using country or state canonical concepts

Goal

Steps

Using only a subset of the canonical countries or states

Goal

Steps

Notes

Defining your own geographic concepts

Goal

Steps

Notes

Metric and Unit Recipes

Using percents

Goal

Steps

Using currency units

Goal

Steps

Creating a custom unit

Goal

Steps

Notes

Using `country` or `state` canonical concepts

Using `currency` units