chartwerk.datamap

The datamap contains classifications of the columns in a user's data. This branch of the API drives what controls are presented to a chart creator in the editor and much of the rest of the API. That makes the datamap the most critical part of the API to understand.

Data classification grammar

Because of the many types of data Chartwerk has to parse while creating charts it's necessary to have terms that define the relationship between the data schema and a chart.

Most common dataviz terms don't bridge that gap. For example, describing data columns as traditional X and Y axes is tied too closely to the hard rules of a chart's coordinate plane. What happens when we want to use the same logic in terms of X & Y axes to draw both a horizontal and a vertical bar chart?

Chartwerk introduces a new coarse, high-level grammar to describe tabular data schema in terms that represent a column-by-column mapping to the dimensions of a chart. For example, the grammar may describe which columns in the data schema are responsible for determining the position of chart elements and which determine their color.

The grammar represents the structure of the data, but also drives what additional options are appropriate for the data. Once a user classifies the columns in their data, the Editor renders the appropriate controls to specify other chart features, like the appropriate color scale and axes properties.

The core classifications of the grammar are called "axes" because each represents a discrete vector within which the data vary, like color or position.

Users classify the columns of the raw data they paste into the Editor using the grammar's terms. But while the terms are necessarily abstract from the perspective of template developers, in the Editor, the classifications can be aliased to more familiar terms.

There are six data classifications built in to Chartwerk. Template developers can also add custom data classifications for individual templates.

Default classifications

datamap.base

A data column classified as a base axis most often contains data like time series dates or categorical values. Commonly, these are values by which numeric data are charted. Mortality rates by occupation. Stock prices by company.

The base axis corresponds to the traditional X axis in the case of horizontal line and bar charts. It can also represent a column of state names used to chart data in a choropleth map or a column of numeric values plotted along the X axis of a scatterplot.

datamap.value

A value axis is a single column of numeric data used to determine positional attributes of a data point. For example, the height on the Y axis of a point in a scatterplot or the number of units to draw in a unit chart.

datamap.scale

Scale axis data is used to set the color or size of a data point. It can contain numeric or categorical data.

By design, Chartwerk does not allow for multiple scale axes, for example, scaling a data point by size and color.

datamap.series

Often, it is more natural to keep data in a crosstab format than in a flat table schema that neatly corresponds to base, value and scale axes. Data series accommodate that convenience.

Data series are crosstabbed columns always containing numeric values, never categorical data. These data are always translated to a positional dimension on the chart and to a categorical color range.

The data series classifications are mutually exclusive with value axis and scale axis options because they contain the same data, simply represented differently in the table schema.

Take, for example, these two table schemas:

Crosstab

Schema:

Date Male Female
01/01/16 22 24
02/01/16 26 32

Classification:

Column Classification
Date base axis
Male data series
Female data series
Flat table schema

Schema:

Date Gender Age
01/01/16 Female 24
02/01/16 Female 32
01/01/16 Male 22
02/01/16 Male 26

Classification:

Column Classification
Date base axis
Gender scale axis
Age value axis

In the crosstab, the Male and Female columns will represent both a color and a position, whereas in the flat table, Gender is a scale axis and Age, a value axis.

datamap.facet

Faceting columns are always categorical data used to create sub-groups of data for small multiples, i.e., faceted charts.

datamap.ignore

Users are also given the option to specify columns to ignore in their data.

Aliasing default classifications

While the default classification names are hard-coded into Chartwerk's API, they can be aliased in the editor's interface to terms more familiar to chart creators.

For example, a base axis in a line chart template might be aliased to "X axis." The chart creator would choose the alias from a dropdown, but the chart developer would see the column selected in the API at chartwerk.datamap.base.

Aliases are specified in the save template modal on the Publish tab in the editor.

Custom data classifications

Template creators can specify custom data classifications in the save template modal on the Publish tab in the editor.

Custom data classifications require both a class name and an alias.

Class names will be camel-cased and represented in the API at chartwerk.datamap.custom.<className>. They must be unique.

Custom data classifications can only specify a single data column.

API example

{
  base: 'baseColumn',
  value: 'valueColumn',
  scale: 'scaleColumn',
  series: ['seriesColumn1', 'seriesColumn2'],
  facet: 'facetColumn',
  ignore: ['ignoreColumn1', 'ignoreColumn2'],
  custom: {
    myCustomClass1: 'customColumn1',
    myCustomClass2: 'customColumn2',
  }
}

Examples of the grammar

The following are some examples of the datamap API applied to different chart types.

Bar chart

Schema:

A 2-column dataset of percent of executive jobs held by women by company.

Classification:

Column Classification
Company base axis
Percent women value axis

Unit chart

Schema:

A 2-column dataset of leading causes of death among 100 teens.

Classification:

Column Classification
Cause of death scale axis (color of each block)
Number of dead value axis

Line chart

Schema:

A 2-column dataset of company production rates over time.

Classification:

Column Classification
Date base axis
Production value axis / data series

Multi-line chart

Schema:

A 3-column dataset of company stock prices over time.

Classification:

Column Classification
Date base axis
Company A data series
Company B data series

Faceted multi-line chart

Schema:

A 4-column dataset of company stock prices over time by industry.

Classification:

Column Classification
Date base axis
Company A data series
Company B data series
Industry faceting column

Grouped bar chart

Schema:

A 4-column dataset of recidivism rates by inmate risk category by county.

Classification:

Column Classification
County base axis
Low risk data series
Medium risk data series
High risk data series

Scatterplot chart

Schema:

A 4-column dataset of state SAT scores.

Classification:

Column Classification
Student testing rate base axis
SAT score value axis
Student poverty rate scale axis
State name tooltip (custom classification)

Boxplots

Schema:

A 3-column dataset of medical utilization rates by doctor by practice specialty.

Classification:

Column Classification
Specialty base axis
Utilization rate value axis
Doctor NPI ignored column

Polar line chart

Schema:

A 3-column dataset comparing two players performance stats.

Classification:

Column Classification
Performance dimension base axis
Player A data series
Player B data series

Choropleth maps

Schema:

A 2-column dataset of infant mortality rates by state.

Classification:

Column Classification
State base axis
Mortality rate scale axis

Schema:

A 2-column dataset of states who voted for each political party.

Classification:

Column Classification
State base axis
Republican or Democrat scale axis

Dot maps

Schema:

A 3-column dataset of minority population growth rates by city.

Classification:

Column Classification
Longitude base axis
Latitude value axis
Population growth scale axis

Schema:

A 3-column dataset of cities that are above or below an EPA smog threshold.

Classification:

Column Classification
Longitude base axis
Latitude value axis
Above or below scale axis

results matching ""

    No results matching ""