Connections globe

A spinnable globe for visualising flows between cities, countries or regions

Updated 2 years ago by Template retirement home

How to use this template

“Connections globe” is a powerful 3D template for visualising flow data such as migration patterns, financial transfers or flights. Each row is represented as an arc drawn from a source location to a destination location, sized according to the value of the flow.

Data requirements

Your spreadsheet must have columns for source, destination and value. Optionally you can also make use of time or category columns to create navigation interfaces such as time sliders, buttons or dropdowns.

To work out of the box, your source and destination columns need to contain three-letter ISO country codes, but you can use any codes or names you like if you update the locations sheet to match (see below).

Locations

To draw each arc, the template uses the latitude and longitude for each location as specified in the second data sheet – which by default is called Locations and uses three-letter country codes. You can edit this sheet or replace it entirely to use whatever location names or codes appear in your main data sheet.

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

template: _49

version: _34

Template data

There are two different formats in which you can supply data to this template. Which one will be more convenient for you likely depends on the source of your data, as described below.

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:

    {
        values: [
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            ...
        ],
        locations: [
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            ...
        ]
    }

... but with the keys being the column headers from your source data instead. To tell the API how these 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: "_49",
    version: "_34",
    bindings: {
        values: {
            src: "ValuesHeader1",
            dst: "ValuesHeader2",
            val: "ValuesHeader3",
            filter1: "ValuesHeader4",
            filter2: "ValuesHeader5"
        },
        locations: {
            code: "LocationsHeader1",
            name: "LocationsHeader2",
            latitude: "LocationsHeader3",
            longitude: "LocationsHeader4"
        }
    },
    data: {
        values: [
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            ...
        ],
        locations: [
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            ...
        ]
    }
}

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

{
    template: "_49",
    version: "_34",
    bindings: {
        values: {
            src: "ValuesHeader1",
            dst: "ValuesHeader2",
            val: "ValuesHeader3",
            filter1: "ValuesHeader4",
            filter2: "ValuesHeader5"
        },
        locations: {
            code: "LocationsHeader1",
            name: "LocationsHeader2",
            latitude: "LocationsHeader3",
            longitude: "LocationsHeader4"
        }
    },
    data: {
        values: [
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            { "ValuesHeader1": ..., "ValuesHeader2": ..., ... },
            ...
        ],
        locations: [
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            { "LocationsHeader1": ..., "LocationsHeader2": ..., ... },
            ...
        ]
    }
}

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

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: "_49",
version: "_34",
data: {
    values: [
        {
            src: ...,
            dst: ...,
            val: ...,
            filter1: ...,
            filter2: ...
        },
        ...
    ],
    locations: [
        {
            code: ...,
            name: ...,
            latitude: ...,
            longitude: ...
        },
        ...
    ]
},
...
}

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

{
template: "_49",
version: "_34",
data: {
    values: [
        {
            src: ...,
            dst: ...,
            val: ...,
            filter1: ...,
            filter2: ...
        },
        ...
    ],
    locations: [
        {
            code: ...,
            name: ...,
            latitude: ...,
            longitude: ...
        },
        ...
    ]
},
...
}

Meanings of the template data keys:

  • values.src: The column containing the code for the arrow's source
  • values.dst: The column containing the code for the arrow's destination
  • values.val: The column containing the values of interest - this specifies the thickness of the arrow
  • values.filter1: The column to use for the first filter control in the visualisation
  • values.filter2: The column to use for the second filter control in the visualisation
  • locations.code: The column containing the location code, as specified in the Source and Destination columns of the Arrows sheet
  • locations.name: The column containing the location name
  • locations.latitude: The column containing the latitude of the location
  • locations.longitude: The column containing the longitude of the location

Template settings

Options for opts.state.

Title & subtitle

title string

Title. Optional title

subtitle string

Subtitle. Optional subtitle

Globe

globe_skin string

The image file for the global surface. Choose a preset skin or provide a URL of jpg (4096×2048 pixels)

Predefined values:

  • world_blue.jpg
  • world_brown.jpg
  • world_blue_white.jpg

distance number

Initial zoom. The distance from the earth, from 350 (closest) to 1000 (farthest away)

Min: 350

Max: 1000

auto_rotate boolean

Auto rotate. Automatically rotate the globe when the focus of the data changes

default_lat number

Default latitude. The latitude to show at the forefront on load. Ignored when Auto rotate is selected and there are arrows on screen.

Min: -90

Max: 90

default_lon number

Default longitude. The longitude to show at the forefront on load. Ignored when Auto rotate is selected and there are arrows on screen.

Min: -180

Max: 180

Arrows & leaderboard

num_arrows number

Number of arrows. Sets a limit on the number of arrows to draw to improve animation performance

num_results number

Maximum number of results. How many countries to show in the results list

arrow_scale_reference string

Arrow scale reference. Should the arrows be scaled relative to the maximum value in the whole dataset or the maximum of the unfiltered values?

Allowed values:

  • all (Whole data set)
  • current (Current visible data)

arrow_scale number

Arrow scale. Multiplier to increase or decrease the width of the arrows

arrow_colour color

Arrow colour. The colour of the arrows

selected_colour color

Selected items colour. The colour of selected arrows and leaderboard labels

leaderboard_country_header boolean

Country as header. When there's only one source or destination in the list, show it as a header.

show_values boolean

Show values. Show the data value for each country in the results

value_prefix string

Symbol or text before value.

value_suffix string

Symbol or text after value.

decimal_places number

Decimal places. Number of decimal places to show in the leaderboard and mouseover popups

Filter 1

f1_initial string

Default primary filter. The primary filter used on initial load. If invalid uses the first filter option in the data.

f1_type string

Type of filter. The type of filter determines how the filter list is sorted and which control to use by default.

Allowed values:

  • categorical (Categories)
  • temporal (Dates/times)
  • numeric (Numbers)

f1_temp_format string

Format string for Dates/times. See www.npmjs.com/package/d3-time-format for a guide to possible formats.

f1_sort_options boolean

Sort filter list. If unchecked, the filter list will follow the ordering in the spreadsheet

f1_control string

Control. Control for primary filter

Allowed values:

  • auto (Default)
  • dropdown (Dropdown menu)
  • slider (Slider)
  • buttons (Buttons)

f1_width number

Width. Width of control in pixels

Min: 30

f1_step_time number

Time between animation steps. Used when pressing the play button on a slider and measured in seconds. Positive values move the slider left to right, negative values move the slider right to left. A value of 0 diables the animation option.

f1_loop_time number

Loop time multiplier. Values bigger than 1 means the animation will spend a larger amount to time at the end point of the slider. Set to zero to disable looping altogether.

Filter 2

f2_initial string

Default secondary filter. The secondary filter used on initial load. If invalid uses the first filter option in the data.

f2_type string

Type of filter. The type of filter determines how the filter list is sorted and which control to use by default.

Allowed values:

  • categorical (Categories)
  • temporal (Dates/times)
  • numeric (Numbers)

f2_temp_format string

Format string for Dates/times. See www.npmjs.com/package/d3-time-format for a guide to possible formats.

f2_sort_options boolean

Sort filter list. If unchecked, the filter list will follow the ordering in the spreadsheet

f2_control string

Control. Control for secondary filter

Allowed values:

  • auto (Default)
  • dropdown (Dropdown menu)
  • slider (Slider)
  • buttons (Buttons)

f2_width number

Width. Width of control in pixels

Min: 30

f2_step_time number

Time between animation steps. Used when pressing the play button on a slider and measured in seconds. Positive values move the slider left to right, negative values move the slider right to left. A value of 0 diables the animation option.

f2_loop_time number

Loop time multiplier. Values bigger than 1 means the animation will spend a larger amount to time at the end point of the slider. Set to zero to disable looping altogether.

Page design

hide_nav boolean

Hide all text and controls.

background_colour color

Background colour. Background colour of the page

grad boolean

Show gradient shade.

accent_colour color

Accent colour. Colour for the leaderboard numbers and slider handles

css text

Custom CSS styles. Custom CSS definitions to override the defaults