Wormtrails CSV is a Common Lisp library for generating streamgraphs that resemble Zach Beane‘s famous movie box office visualizations. It provides a wrapper around Beane‘s Wormtrails library to allow graphs to be generated from simple CSV files.
Examples of Wormtrails CSV’s output can be found in my blog post, “Visualizing US city and state growth with Wormtrails“. Other examples of “wormtrails”-style streamgraphs can be found on Zach Beane‘s movie box office charts microsite.
Wormtrails CSV is a Quicklisp-based ASDF system. If you know what that means you’re probably already familiar with Common Lisp and have a working environment. Otherwise, if you’re new to Lisp, I wrote a blog post, “Setting up a Common Lisp environment on OS X with Sublime Text 3”, that will get you started on OS X by setting up a development environment and the SBCL compiler.
Besides Wormtrails CSV itself, you will need to manually clone or download a copy of Beane’s Wormtrails and Geometry libraries and place them somewhere Quicklisp/ASDF will look for them. By default, Quicklisp looks for local libraries in
cd ~/quicklisp/local-projects git clone firstname.lastname@example.org:/itafroma/wormtrails-csv.git git clone email@example.com:/xach/wormtrails.git git clone firstname.lastname@example.org:/xach/geometry.git
All other dependencies should be handled automatically when Wormtrails CSV is loaded through Quicklisp using
The main functionality can be accessed through the
(ql:quickload "wormtrails-csv") (wormtrails-csv::generate "/foo/data/states.csv" "/foo/output/states.png" :scale 0.00001 :height 100 :label "10M PEOPLE" :top-n 25)
For more information about what parameters and options can be set, check out the files in the
examples folder. The files there can also be run run as-is:
cd ~/quicklisp/local-projects/wormtrails-csv sbcl --load examples/states.lisp --quit sbcl --load examples/cities.lisp --quit
The example implementations should be easily modifiable to work with most other CSV use cases. Just copy one and edit it to your liking.
Copyright and license
data folder contains a number of spreadsheets and CSV files containing US census data. Facts generally do not receive protection under US copyright law, and even if they did, the individual data points were created by US census workers acting in their official capacity, thereby placing them in the public domain. Because it is trivially easy to recreate the files in the
samples folder with that data, the files themselves are also placed into the public domain and any automatic copyright I may have on them is forsworn.
All other files copyright © 2014 Mark Trapp where applicable. They are licensed under the MIT license: a copy can be found in the
LICENSE file. All other rights reserved.
- Zach Beane, for the original concept, the Wormtrails library, and Quicklisp
- Kevin Fox, for the prompt that led to the creation of this library
Comments and feedback are welcome and appreciated. Need help on your next project? Let's talk.