Cart: Computer software for making cartograms


This page contains documentation for cart, a computer program and software library for creating density-equalizing maps or "cartograms."

Installation

If you simply wish to run the complete program "cart" to make cartograms from your own data, you can compile the source code as provided. For this you'll need a C compiler, such as Visual C++ or GCC. The program also makes use of the FFTW Fourier transform library, version 3 or later. If you don't already have this library on your computer you will need to download both the library itself and the appropriate header files for compilation, for instance from here. (It's a free download.)

When you have everything ready, you should unzip the downloaded source code file for the cart program, which will create a folder or directory with the source code in it. Compilation itself is simple. For instance, on my Linux computer I just pull up a terminal, switch to the appropriate directory, and type:

  gcc -O -o cart cart.c main.c -lfftw3 -lm
Although I don't know much about Windows and Macs I assume it's similarly simple on those platforms. If you get the program to compile and run successfully on your Windows or Mac machine, please drop me a line.

If you wish to make more sophisticated use of this software, such as incorporating it into one of your own programs, then you should read this page, which describes the workings in detail.

There are also three other versions of the program included in the download files, called cart2, cartv, and cart2v. These are more memory-efficient versions of the original, but they all have some drawbacks too. If you have enough memory to run the basic cart program, you should do so: it is the fastest and most accurate version. On the other hand, if you are doing large cartograms and you are running out of memory then the others may be useful. The program cart2 uses about 60% as much memory as cart, but is less accurate. It still gives a typical accuracy of better than one grid square in most applications, so the difference probably doesn't matter too much. The program cartv uses about half as much memory as cart and is just as accurate, but it is slower, taking up to twice as long to calculate a given cartogram. And cart2v is both slower and less accurate, but uses very little memory – typically only a third as much as the original cart. Here's a table summarizing the differences:

ProgramSpeedAccuracyMemory use
cartfastaccurate100%
cart2fastless accurate60%
cartvsloweraccurate50%
cart2vslowerless accurate30%

All versions of the program are used in exactly the same way. The parameters are the same and the inputs and outputs are the same. They are also compiled in the same way. For instance, to compile cart2 under Linux I type:

  gcc -O -o cart2 cart2.c main.c -lfftw3 -lm

Using the cart program

The program cart (or any of the alternative versions cart2, cartv, or cart2v) takes a matrix of densities that you provide and generates the corresponding cartogram. The cartogram is specified by the transformation of a complete grid of points from a rectangular grid to the cartogram. This grid of points can then be used to transform map features such as boundaries or coastlines to the cartogram using interpolation.

To use the program you need to have a file containing the density distribution that you want to use to make your cartogram. This should take the form described in our paper, with the area of interest surrounded by a generous border of "sea" that is given a density equal to the mean density of the land. An example density file is provided with the source code so you can see the format. This file, called uspop.dat, represents the population density of the lower 48 United States, state by state on a 1024x512 grid, taken from the 2000 US Census. The format of the file is a set of rows each containing density data for one row of the grid in simple ASCII format.

Note that the program is agnostic about what cartographic projection you use. It works entirely in the coordinates of the grid used to specify the density. You can use whatever projection you like to create the grid, and the cartogram will be generated using the same projection. You don't need to tell the program what projection you are using.

Once you have your density grid, running the program just requires a single command. Suppose, as with the example file uspop.dat, our density grid has size 1024 horizontally by 512 vertically. Pull up a terminal (on Mac OS or Linux) or a "DOS prompt" (on Windows) and type

  cart 1024 512 uspop.dat output.dat
The four parameters here are the horizonal and vertical size of the grid, the file containing the grid, and the name of the file into which you want the result of the calculation placed.

The program will work for a short while – typically somewhere between a few seconds and a couple of minutes, depending on the speed of your computer and the size of the cartogram – and when it finishes the file output.dat will contain the results. The output file has the form of a set of pairs of coordinates, which are the positions on the cartogram of an initial grid of points that coincides with the grid used to define the density. Once you have this grid, you can use it to find where any point on the map ends up on the cartogram, just by interpolation between the grid points. Simple bilinear interpolation works well in most cases. An example program is provided called interp that will perform interpolation of this sort. To use it, it should first be compiled. For example, under Linux I type

  gcc -O -o interp interp.c
Then the program is run with a command of the form
  interp 1024 512 output.dat
where the first two parameters are the size of the grid and output.dat is the output file produced by cart. Then you simply type pairs of coordinates representing positions on the original map (in the same coordinates as you used for your population grid) and the program will print out the corresponding points on the cartogram. The program is designed to be used as a "filter": you can feed it a long set of coordinates by piping them from a file and pipe the results back into another file, which you can then use to make your map. For instance, you might have a file containing the coordinates of points on the boundary of a country or region. The program would transform these to the correct boundary for the country or region on the cartogram. Lines that don't begin with a numeric character or space and blank lines are copied as-is to the output, so you can include comments and other things in your filter text if you want.

As an example, here is a population cartogram of the United States, made by interpolating between the grid points produced by cart for the input file uspop.dat, exactly as above:

This cartogram took about 30 seconds to calculate on my desktop computer.


Last modified: November 9, 2006

Mark Newman