IMPORTANT: This repository is no longer actively maintained. A more advanced version of the software, rewritten in C++ and still utilizing Gastner et al.'s (2018) fast flow-based method as of 2024-10-06, is now available at https://github.com/mgastner/cartogram-cpp. We highly recommend that users interested in our cartogram generator switch to the updated repository.
We present a fast cartogram generator written in C. It uses the flow-based algorithm devised by Gastner, Seguy & More.
This readme explains how to set up and use this software. In doing so, it uses data from the 2016 United States presidential election. These data are included in the repository.
Note: Any images generated using this software should be referenced to:
Gastner, M., Seguy, V., & More, P. (2018). Fast flow-based algorithm for creating density-equalizing map projections. Proceedings of the National Academy of Sciences USA, 115:E2156-E2164.
BibTeX Entry:
@article{gastner_seguy_more_2018,
title={Fast flow-based algorithm for creating density-equalizing map projections},
author={Gastner, Michael T. and Seguy, Vivien and More, Pratyush},
DOI={10.1073/pnas.1712674115},
journal={Proceedings of the National Academy of Sciences of the United States of America},
year={2018},
volume = {115},
number = {10},
pages = {E2156--E2164}
}
The cartogram generator expects two input files.
a '.json' file containing the cartesian coordinates for the map regions under consideration. For example, for the 2016 US presidential election data we provide usa_contiguous_arcgis.json
(in the sample_data
folder) which includes the coordinates for the boundaries of the different states of the contiguous United States. You will need to obtain the '.json' file and it needs to adhere to the GeoJSON specifications. It also needs to be processed first by using the command cartogram -p [json_file_name]
(Instructions found below). If you do not have a '.json' file, please follow the steps listed here: https://github.com/Flow-Based-Cartograms/go_cart/blob/master/process_map_file.md
a '.csv' file containing the data (such as population) for each region, according to which these will be scaled. For the 2016 US presidential election data we provide usa_contiguous_electors.csv
(in the sample_data
folder) which provides the number of electors for each state. The csv file will be generated by the cartogram generator when you process the '.json' file. You will then need to add in the data to the csv file.
The .csv
file should be in the following format:
Region.Id,Region.Data,Region.Name
1,9,Alabama
2,11,Arizona
3,6,Arkansas
4,55,California
5,9,Colorado
6,7,Connecticut
7,3,Delaware
8,3,District of Columbia
...
You must have Xcode Command Line Tools
and the brew
package manager installed (and updated) on your computer.
No additional dependencies. Your default apt-get
package manager should work fine.
Install Bash for Windows 10 following these instructions. Use this Bash terminal in the build steps.
If you have an earlier edition of Windows you can still build cartogram
:
mkdir build
cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/
make
make install
dos2unix autogen.sh
dos2unix autobuild.sh
./autogen.sh
Use the cygwin terminal in the build steps
Open a terminal, clone the repository, and navigate to its root directory.
Run the provided automatic build script. This will install the required dependencies and run configure and make for you:
./autobuild.sh
The cartogram
executable can be found in the root directory of the repository. To add the generator to your list of binaries, and access it outside this directory, please run the following command:
sudo make install
Once you have installed it, you can run the cartogram generator at the command line by running cartogram
. You should see the following output:
$ cartogram
USAGE:
Process GeoJSON File: cartogram -p json_file_name
Generate Cartogram: cartogram [-dei] -g map_file_name -a area_file_name
OR:
cartogram [-dei] -g map_file_name -s
-d: use Gastner-Newman (i.e. diffusion) method
-e: generate cartogram figure in EPS format
-i: calculate inverse transform
Note: If you run into issues, look at the Troubleshooting section below.
To generate a cartogram, you need a map and the associated statistical data you want to visualize. The cartogram generator accepts maps in GeoJSON and ArcInfo Generate formats, and statistical data in CSV format. To generate a cartogram, you need to:
Process your GeoJSON map file using the following command:
cartogram -p json_file_name
The cartogram will generate 2 new files: a processedmap '.json' file and '.csv' file. Open the CSV file with your preferred spreadsheet program, and fill in the data value for each region under the 'Region Data' column.
Please note that support for the ArcInfo Generate format is provided for backwards compatability with existing maps. New maps should use the GeoJSON format. While you do not need to run a command to process the map file, you need to genenate the CSV file containing the statistical data you want to visualize manually. It should contain two columns:
Region Id
, which corresponds to the region IDs in the map fileRegion Data
, which contains the data for each regionOnce you have processed your map file and generated a CSV file with the data you want to visualize, you can run the following command to generate a cartogram:
cartogram -g processedmap_file_name -a csv_file_name
The generated cartogram will be saved in the same format as the map input in the current working directory with the filename:
cartogram.json
, if the input map is in GeoJSON formatcartogram.gen
, if the input map is in ArcInfo Generate formatFor the 2016 US presidential election data, navigate to the sample_data/
directory.
cd sample_data/
Then run the following command. Note that the sample data has already been processed using cartogram -p
cartogram -g usa_contiguous_arcgis.json -a usa_contiguous_electors.csv
To generate an EPS image of the original map and cartogram, use the -e
option:
cartogram -eg usa_contiguous_arcgis.json -a usa_contiguous_electors.csv
Running this command will produce three files:
cartogram.json
contains the cartogram in GeoJSON formatmap.eps
contains the original map in EPS formatcartogram.eps
contains the generated cartogram in EPS formatOn macOS, you can view EPS files with the command:
open <filename>.eps
On Linux, run the following instead:
evince <filename>.eps
Replace <filename>
with the name of the file (map
or cartogram
) you wish to open.
For our example, map.eps
should look as follows:
cartogram.eps
should look like:
-e
Output an EPS file of the original map (
map.eps
) and the cartogram (cartogram.eps
)
-d
Use Gastner-Newman (i.e. diffusion) instead of fast flow-based method
-i
Print inverse transform to file
-g
Location of file for the original map
-a
Location of the area information file. Cannot be used with -s.
-s
Read the area information from
stdin
, and output the cartogram gen file tostdout
. Cannot be used with -a.
In case you run into problems while building the generator using the automated script, you could try manually carrying out some of the steps.
Install fftw and gcc.
brew install fftw && brew link fftw
brew install gcc
Note down the version of gcc
installed. For example, if gcc-8.1.0
is installed, your version would be 8
(not 8.1.0).
Run autogen and configure, pass it the compiler information
$ ./autogen.sh
$ CC=gcc-[your-version-number] ./configure
Run make
$ make
Make sure everything is up to date. Then install fftw and gcc.
sudo apt-get update
sudo apt-get install libfftw3-3 libfftw3-dev
sudo apt-get install build-essential
Make sure you are in the root directory, and then run the remaining steps.
$ ./autogen.sh && ./configure && make
If you see the following line in your output, you may want to take a look at this solution.
FATAL:/opt/local/bin/../libexec/as/x86_64/as: I don't understand 'm' flag!