## What is a map?

before we start looking at the code it may be a good idea to think of the best way to represent a country.
Countries are areas of land surrounded by borders, which are imaginary (or sometimes physical) lines going through a set of points. Some countries are made of one of such surfaces, but many countries are not one contiguous territory (they may include islands for instance) so they could be made out of several disjointed polygons. .

Now let’s put on our protovis hat. Let’s suppose we want to draw a map where each country could be colored differently (choropleth). What kind of data structure should be use to represent that?
First there should be a sort of array of countries. Each country should be an item in that array, so they can be indexed and assigned an individual color and various data points.
Then, at the lowest level, we would be drawing polygons, which are treated as pv.Line in protovis. For each polygon, we would require an array of coordinate pairs. To draw a country, we would need a list (array) of those polygons.

So the data structure we are looking at is:

```var world=[  // an array of countries
[ // an array of polygons
[ // an array of pairs of coordinates
[x0, y0], // coordinates of the first point
[x1, y1], // coordinates of the next one
...
[xn, yn],
[x0, y0]  // coordinates of the first point to close the polygon
]
...              // another polygon, but maybe not.
],
[                    // next country
...
]
...
]```

## the map projections example Can be found here: http://vis.stanford.edu/protovis/ex/projection.html

```/*
* A diverging color scale, using previously-computed quantiles of population
* densities; in the future, we might use a quantile scale here to do this
* automatically. Map colors based on www.ColorBrewer.org, by Cynthia A. Brewer,
* Penn State.
*/
var fill = pv.Scale.linear()
.domain(140, 650, 1900)
.range("#91bfdb", "#ffffbf", "#fc8d59");

/* Precompute the country's population density and color. */
countries.forEach(function(c) {
c.color = stats[c.code].area
? fill(stats[c.code].pop / stats[c.code].area)
: "#ccc"; // unknown
});

var w = 860,
h = 3 / 5 * w,
geo = pv.Geo.scale("hammer").range(w, h);

var vis = new pv.Panel()
.width(w)
.height(h);

/* Countries. */
.data(countries)
.data(function(c) c.borders)
.data(function(b) b)
.left(geo.x)
.top(geo.y)
.title(function(d, b, c) c.name)
.fillStyle(function(d, b, c) c.color)
.strokeStyle(function() this.fillStyle().darker())
.lineWidth(1)
.antialias(false);

/* Latitude ticks. */
.data(geo.ticks.lat())
.data(function(b) b)
.left(geo.x)
.top(geo.y)
.strokeStyle("rgba(128,128,128,.3)")
.lineWidth(1)
.interpolate("cardinal")
.antialias(false);

/* Longitude ticks. */
.data(geo.ticks.lng())
.data(function(b) b)
.left(geo.x)
.top(geo.y)
.strokeStyle("rgba(128,128,128,.3)")
.lineWidth(1)
.interpolate("cardinal")
.antialias(false);

vis.render();
```

In addition there are two arrays of the following shape:
First, stats which is an associative arrays of associative arrays, and which associate each 2-letter country code with values of population and area:

```var stats = {
'AG': {pop:83039, area:44},
'DZ': {pop:32854159, area:238174},
...
'US': {pop:299846449, area:915896},
...
};
```

Then, countries, which is an array of associative arrays.

```var countries = [
{code:'AG', name:"Antigua and Barbuda",
borders:[ // an array of one or several areas,
[ // an array of coordinates,
[ // a pair of the form longitude, lattitude
...
]
]
]}
...
]```

Now this second data structure looks a lot like the one we’ve drafted in the prologue. All the geographic information is tucked in a property called “borders”. The array has other properties for comfort.
Because the data is put in the right shape and order, this script can produce a very good map with a remarkable economy of code.
This example has been put together to showcase the various map projections of protovis (identity, mercator, and so on.). These projections have zero impact on the way data should be assembled for making maps, so we’ll just treat them as “magic”.

```/*
* A diverging color scale, using previously-computed quantiles of population
* densities; in the future, we might use a quantile scale here to do this
* automatically. Map colors based on www.ColorBrewer.org, by Cynthia A. Brewer,
* Penn State.
*/
var fill = pv.Scale.linear()
.domain(140, 650, 1900)
.range("#91bfdb", "#ffffbf", "#fc8d59");
```

This part creates a color scale which will return a color according to the value passed to it. The color returned will be somewhere between the ones specified in the range, depending on where the value is relatively to the values specified in the domain. So a value of 140 will result in a color of #91bfdb (bluish), it will go towards the grey as the value moves up to 650, and towards #fc8d59 (redish) as the value goes up to 1900.

```/* Precompute the country's population density and color. */
countries.forEach(function(c) {
c.color = stats[c.code].area
? fill(stats[c.code].pop / stats[c.code].area)
: "#ccc"; // unknown
});```

As the remark says, this will precompute the country’s color once and for all.
The forEach() method goes to every element of the countries array.
the c.color = statement will add a color key to each element of that array (which, as you may recall, already has values for the code, name and borders keys.
What it does is that is retrieves the country code of that element of countries, c.code, and uses that to find out whether we have an area value for that country code (this is stats[/c].area?).
If this is the case, we are going to compute the color that should be attributed to the country, by passing the population divided by the area to the color scale we just made. Else, we just use light grey.

The next few lines are standard constants that will shape the vis.
Note however

`geo = pv.Geo.scale("hammer").range(w, h)`

This is a geographic scale, which will be used to convert longitudes and latitudes to X and Y coordinates on the screen.

```/* Countries. */
.data(countries)
.data(function(c) c.borders)
.data(function(b) b)
.left(geo.x)
.top(geo.y)
.title(function(d, b, c) c.name)
.fillStyle(function(d, b, c) c.color)
.strokeStyle(function() this.fillStyle().darker())
.lineWidth(1)
.antialias(false);```

This is where it all happens.
First, we create a series of panels, one for each country. So, we pass the countries array as data.
Then, we are going to create another series of panels for every country, that is, with as many panels as there are independent areas in the country. For instance, if there are islands, we are going to need extra panels to represent them. If the country is one contiguous mass of land, there will be just one panel here.
This time, we use function(c) c.borders as data. That is, we go into the borders array.

Finally, we are going to create a filled polygon for each of these independent areas. This is achieved by adding a pv.Line to the previous panels. Likewise, we use (function(b) b) as data, meaning that we go yet another level into the borders array. Now, we are accessing the pairs of longitude + latitude numbers.

geo.x and geo.y convert this pair of numbers to X and Y coordinates on the screen.
For the next two lines, title and fillStyle, we need to go back to the country level.
so, we use a function of the form function(d,b,c). d is the current item (pair of longitude, latitude), b its parent (individual area) and c, its grand-parent (the country).
so, function(d,b,c) c.name retrieves the country name, and function(d,b,c) c.color retrieves the color we had computed for that country to begin with.

For the color of the border, we wish to use a darker version of the fill color. This is what the this.fillStyle().darker() does.

The rest of the vis is longitude and latitude ticks, using the built-in properties of the scale.