D3: Queue.js

D3 often requires large geodata files that can be a burden to load for your browser. Some action has been taken to reduce file sizes (the creation of topojson) but sometimes you just have a dataset that is as small as it can get, yet still pretty large. If you’ve run into this problem, you may have noticed your D3 code running before your file has actually loaded, which pooches the whole thing. [Enter Queue.js] Queue is a lightweight asynchronous helper library. Their words, not mine). To put it nicely:

Queue is a plugin that loads external files into the script and ensures each file is completely loaded before allowing the script to continue running.

It is especially useful to use when you are loading multiple datasets into your code. In the following example, we’ll load two files; one a topojson of US States and one a geojson of US Populated cities. Note it isn’t terribly important to convert the point data to topojson because it is inherently as simple as it can get since point data is uni-dimensional.

Remember to load the queue.js library after your d3 library:

<script src="http://d3js.org/queue.v1.min.js"></script>

Queue has a few parts:

• queue() – initializes Queue.js and your loading queue </span>
• defer() – used for each file to allow them to load separately
• await() – the final piece, which typically runs a function once the data are loaded

The Queue

queue()
    .defer(d3.json, 'states.json') // topojson polygons
    .defer(d3.json, 'cities.json') // geojson points
    .await(makeMyMap); // function that uses files

Call Function

function makeMyMap(error, states, cities) {
    svg.append('path')
        .datum(topojson.feature(states, states.objects.usStates))
        .attr('d', path)
        .attr('class', 'states');
    svg.selectAll('.cities')
        .data(cities.features)
        .enter()
        .append('path')
        .attr('d', path.pointRadius(5))
        .attr('class', 'cities');
}

This loads multiple files before the code is run to preserve any actions or transitions your data may take before they load.