Setting Up a CSV File

First Things First

Introduction

Popcharts takes a column-major delimited file as input. Headings (column titles) are optional but encouraged. In this short tutorial we will create such a file, from scratch, for animating two point along a square path.

Column-Major Delimited & File

Although CSV stands for "Comma Separated Values", you can use either a comma, a semi-colon, a TAB or a pipe character as the delimiter. For our example file we will use the semi-colon. A column-major layout means that all the values for a variable are stored in a column. This is just what you'd normally expect from a delimited file. So let's create a file with some data in it. We will assume our points are moving along a square where each side measures 100 meters in length.

Point;X;Y;Time
Point-A;0;0;0
Point-A;1;100;0
Point-A;2;100;100
Point-A;3;0;100
Point-A;4;0;0
Point-B;0;100;100
Point-B;1;0;100
Point-B;2;0;0
Point-B;3;100;0
Point-B;4;100;100

More often than not, the delimited file will have been generated for you. Whether it's by exporting it from Excel or another program or by stitching one together from a bunch of other sources, you typically won't be creating it from scratch like we are here.

Order is Not Important

In the above example, our data is already sorted by point and then by time. That's only because it was easier for us to do so. But it's by no means necessary. Popcharts needs to sort the data internally anyways so data can be in any order within your file. The following file would be equivalent. Note that the headings must still be on the first line.

Point;X;Y;Time
Point-B;1;0;100
Point-A;0;0;0
Point-A;1;100;0
Point-A;4;0;0
Point-B;2;0;0
Point-B;0;100;100
Point-B;3;100;0
Point-A;3;0;100
Point-A;2;100;100
Point-B;4;100;100

RFC 4180 Geek Stuff

Popcharts follows RFC 4180 when parsing your input file. This means that you can use quotes around your values. When your fields are quoted (using double quotes) and you want to include a double quote character in a string then use two consecutive double quote characters. Don't forget to close your quotes though. The following file would be equivalent to the above:

"Point";"X";"Y";"Time"
Point-B;1;0;100
Point-A;0;0;0
"Point-A";1;100;0
Point-A;4;0;0
Point-B;2;"0";0
Point-B;0;100;100
Point-B;3;100;0
Point-A;3;0;"100"
Point-A;"2";100;100
Point-B;4;100;100

That's It"

As you can see, creating an input file for popcharts is really not that difficult.

Gap Minder Fans

For the Gap Minder fans out there (including me), Data file are usually row-major format. See tutorial showing on how to stitch together a bunch of Gap Minder files to use as input to popcharts.