Dutch map

Updated 7 years ago by Daan Louter

This section documents API usage specific to this template, so for an introduction we suggest you refer to the generic API documentation instead.

template: _128

version: _3

Template data

There are three different formats in which you can supply data to this template. The most convenient for you to use likely depends on the source of your data, as described below.

1. Array of arrays, and a bindings object

You can supply arrays of arrays to opts.data, which might look like:

{
    data: {
        data: [
            [ "DataColumn1Value1", "DataColumn2Value1",
            [ "DataColumn1Value2", "DataColumn2Value2",
            [ "DataColumn1Value3", "DataColumn2Value3",
            ...
        ],
        points: [
            [ "PointsColumn1Value1", "PointsColumn2Value1",
            [ "PointsColumn1Value2", "PointsColumn2Value2",
            [ "PointsColumn1Value3", "PointsColumn2Value3",
            ...
        ]
    }
}

where each array of arrays represents the rows in a data sheet.

To tell the API how the values from each column should be associated with the keys that the template is expecting, you must also supply an object attached to opts.bindings. (The meanings of the keys in the bindings object are documented below.) The minimal bindings you can supply for this template are as shown in this example:

{
    template: "_128",
    version: "_3",
    bindings: {
        data: {
            name: 0, // index of a column in your data
            value: 1, // index of a column in your data
        },
        points: {
            name: 0, // index of a column in your data
            lat: 1, // index of a column in your data
            lon: 2, // index of a column in your data
            value: 3, // index of a column in your data
        }
    },
    data: {
        data: [
            [ "DataColumn1Value1", "DataColumn2Value1",
            [ "DataColumn1Value2", "DataColumn2Value2",
            [ "DataColumn1Value3", "DataColumn2Value3",
            ...
        ],
        points: [
            [ "PointsColumn1Value1", "PointsColumn2Value1",
            [ "PointsColumn1Value2", "PointsColumn2Value2",
            [ "PointsColumn1Value3", "PointsColumn2Value3",
            ...
        ]
    }
}

All possible bindings that you can supply are shown in this example:

{
    template: "_128",
    version: "_3",
    bindings: {
        data: {
            name: 0, // index of a column in your data
            value: 1, // index of a column in your data
        },
        points: {
            name: 0, // index of a column in your data
            lat: 1, // index of a column in your data
            lon: 2, // index of a column in your data
            value: 3, // index of a column in your data
        }
    },
    data: {
        data: [
            [ "DataColumn1Value1", "DataColumn2Value1",
            [ "DataColumn1Value2", "DataColumn2Value2",
            [ "DataColumn1Value3", "DataColumn2Value3",
            ...
        ],
        points: [
            [ "PointsColumn1Value1", "PointsColumn2Value1",
            [ "PointsColumn1Value2", "PointsColumn2Value2",
            [ "PointsColumn1Value3", "PointsColumn2Value3",
            ...
        ]
    }
}

2. Array of objects with arbitrary keys, and a bindings object

This format is most likely useful when you have data from an external source, such as CSV data loaded from d3-dsv. You should supply this attached to the opts.data, which might look like:

{
        data: [
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            ...
        ],
        points: [
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            ...
        ]
    }

... but with the keys being the column headers from your source data instead. You must also supply an object attached to opts.bindings. The minimal bindings you can supply for this template are as shown in this example:

{
    template: "_128",
    version: "_3",
    bindings: {
        data: {
            name: "DataHeader1",
            value: "DataHeader2",
        },
        points: {
            name: "PointsHeader1",
            lat: "PointsHeader2",
            lon: "PointsHeader3",
            value: "PointsHeader4",
        }
    },
    data: {
        data: [
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            ...
        ],
        points: [
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            ...
        ]
    }
}

All possible bindings that you can supply are shown in this example:

{
    template: "_128",
    version: "_3",
    bindings: {
        data: {
            name: "DataHeader1",
            value: "DataHeader2",
        },
        points: {
            name: "PointsHeader1",
            lat: "PointsHeader2",
            lon: "PointsHeader3",
            value: "PointsHeader4",
        }
    },
    data: {
        data: [
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            { "DataHeader1": ..., "DataHeader2": ..., ... },
            ...
        ],
        points: [
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            { "PointsHeader1": ..., "PointsHeader2": ..., ... },
            ...
        ]
    }
}

(As before, the keys containing "Header" would be replaced by column names from your data source.)

3. Array of objects with template-defined keys

There is an alternative format you can use, which is likely to be easier to use if your data is not from a spreadsheet source. With this alternative format you supply your data to the template as an array of objects, attached to opts.data, where the keys must be those used by the template, as documented below. In this case there is no need to supply a bindings object, since the key names are already those expected by the template. The required properties in the data object are as follows (scroll down for a description of what each property is):

{
    template: "_128",
    version: "_3",
    data: {
    data: [
        {
            name: ...,
            value: ...
        },
        ...
    ],
    points: [
        {
            name: ...,
            lat: ...,
            lon: ...,
            value: ...
        },
        ...
    ]
},
    ...
}

And the full list of all possible properties is as follows:

{
    template: "_128",
    version: "_3",
    data: {
    data: [
        {
            name: ...,
            value: ...
        },
        ...
    ],
    points: [
        {
            name: ...,
            lat: ...,
            lon: ...,
            value: ...
        },
        ...
    ]
},
    ...
}

Meanings of the template data keys:

  • data.name: The column containing the display name of the region
  • data.value: A column of values
  • points.name: Name associated with point
  • points.lat: Latitude of point
  • points.lon: Longitude of point
  • points.value: Value associated with point

Template settings

Options for opts.state.

Overview

title string

Title.

choropleth boolean

Use colour scale to shade land.

points boolean

Plot points.

Colour scale

palette string

Palette. Specify a d3 sequential scheme (such as [[schemeOranges]], [[schemeReds]], [[schemeBlues]] and [[schemeGreens]]) or diverging scheme (such as [[schemeRdYlGn]] or [[schemePiYG]]). See github.com/d3/d3-scale-chromatic for a full list.

reverse_scale_colours boolean

Reverse colours.

scale_min string

Colour-scale minimum value (CSMin). Any values falling below this take on the colour at the bottom of the scale.

scale_max string

Colour-scale maximum value (CSMax). Any values falling above this take on the colour at the top of the scale.

clip_legend boolean

Clip legend. Clip legend to CSMin and CSMax values rather than the data. (Ignored if buckets used.)

bucket boolean

Bucket scale. Use a discrete colour scale. CSMin and CSMax will only be used if they fall inside the range of the data.

custom_thresholds string

Intermediate thresholds. A comma-separated list of (up to 6) thresholds, additional to CSMin and CSMax. Will only be used if both CSMin and CSMax are specified above and one or more entries in the list falls between CSMin and CSMax. If it is used, number of buckets is ignored.

n_buckets number

Number of buckets. From 3 to 9; ignored if using custom thresholds

Min: 3

Max: 9

equal_swatches boolean

Equal-width swatches. Make all bucket swatches the same length in the legend.

no_data_fill color

Missing data colour.

hatch boolean

Show missing data as pattern.

Points

point_scale_factor number

Scale factor. Scale factor to determine size of circles relative to value (large is bigger). Use 0 to autoscale. If values are large (eg in the 1000's) then this number should be small.

point_prefix string

Prefix. Prefix for displayed value

point_suffix string

Suffix. Suffix for displayed value

point_fill_colour color

Colour of point centres.

point_opacity number

Opacity.

Max: 1

point_stroke_colour color

Colour of point outlines (normal).

Appearance

land_colour color

Land colour. Ignored if colour scale used

background_colour color

Background colour.

highlight_colour color

Colour of highlighted items.

legend_text_colour color

Legend text colour.

legend_text_size number

Legend text size.

legend_width number

Legend width.

legend_bottom boolean

Legend at bottom.

Number styles

prefix string

Number prefix. Optional prefix for numbers; useful for currency symbols

suffix string

Number suffix. Optional suffix for numbers; useful for units

multiplier number

Number multiplier. Optional multiplier for numbers

decimals number

Number of decimal places. Decimal places for numbers. Negative values round to positive powers of 10 (eg -2 rounds to nearest 100)

Province borders

province_border_color color

Colour.

province_border_opacity number

Opacity.

Max: 1

province_border_width number

Width.