Tutorial: Protovis Part 2: Lines and Labels
Tick marks and labels make it easier for readers to understand the data you are visualizing. But it's also important to make sure they don't overwhelm your graphic. Once you know how to set color and font styles, you can start making templates that you can reuse to make simple charts quickly.
Welcome to part 2 of our Protovis tutorials. In this tutorial we're going to add lines and labels to the bar chart we built in part 1. Since the chart takes up most of the 150 pixel image area, lets start by shrinking and moving the chart.
Change bottom to 15 to move the chart up. Change the height property multiple from 75 to 60 and in the left property, type + 26 at the end of the parenthesis to add empty space on the left.
Changing Bar Size
That moved and resized the chart but we lost a bar. That's because we also need to change the bar size and the left property that creates the gap.
Change width to 15 then in the left property change the multiple from 25 to 20. Perfect. now we're ready to add a baseline rule.
Creating a Comment
Lets start by creating a comment. Comments are notes that you make in your code that don't affect the programming. You can identify what the code is or does so that you can keep it organized. Put your cursor after the semicolon in the bar code. Hit return a couple of times then type 2 forward slashes and the words baseline rule. Hit return again and type example.add (pv Rule).
Getting it lined up
Now we need to line up the rule with the bottom of the chart. Set the bottom to 15, Set left to 24 to describe where the line starts and set right to 6 to describe where it ends. Notice that the lines stick out 2 pixels on either side of the chart.
Next we need to add some tick lines. Tick lines illustrate the scale of the data that the bars represent. Start by adding a comment that notes these are tick lines, then type example.add(pv.Rule).
Adding a data array
Next, we need to add a data array to describe the distribution of the tick lines. in this case we want lines at 0, .5, 1 and 1.5. The tick lines need to be distributed from the bottom so type .bottom(function (d) d * 60 + 15) to start the lines 15 pixels from the bottom. Notice that this is the same function that we used to describe the height of the bars.
Positioning the lines
We want the tick lines to be positioned identically to the baseline, so copy the left and right settings from the baseline and paste them on the end of the tick lines chain. Now type .strokeStyle ("lightgray") to change the color.
Notice that the baseline is covered up by the tick lines. In Protovis, whatever is last in your code is on top of what preceded it. In this case, the bars are in the back, the baseline rule is on top of the bars and the tick lines are on top of the baseline rule and the bars.
To move the tick lines behind the bars, select the tick lines code, cut it and paste it above the bars.
So lets take a look at the tick lines data. It would be very time consuming if you had to manually type in where you wanted your lines. Protovis has a method that makes it much easier.
Delete the data array and and replace it with pv.range. In parenthesis, type 0 for the start point, type 2 for the end point and type .5 for the increment. This is really helpful when working with larger numbers.
Labeling the tick lines
OK. So lets add some labels to the tick lines. Put your cursor after the strokeStyle but before the semicolon and hit return. Type add.(pv.Label) to use the label class.
You can see labels appear in the chart. We need to change the alignment and this can be a little confusing. The nomenclature is the opposite of what it would be in typesetting. Here, the type is aligned to the left property that we defined earlier in the chain.
Type .textAlign("right") and the text shifts so that the left property is to the right of the text. Then type .textBaseline("middle") to vertically align the text to the tick lines.
It's kind of confusing but you'll get used it. Protovis also lets you define simple font changes. Type .font("bold 6pt sans-serif"). Finally, type .textStyle("gray") to change the type color. Now the labels match the tick lines.
Labeling the Bars
Lets add labels to the bars. Put your cursor after the left property but before the semicolon and hit return. Type .anchor("top").
This sets the anchor point of the label to the top of the bars. Now type .add(pv.Label) and you can see the data labels appear just below the top of the bars. Type .textBaseline("bottom") to move the labels above the anchor point.
That's better but all those numbers make the chart harder to read. So lets write something to make only the larges data label visible.
Type .visible(function (d). Then type d >= 1.6. This means d is greater than or equal to 1.6. You can adjust this at any time. For example, change 1.6 to 1.5 to make the lables for the top two bars visible.
Change the font by copying the font property from the tick lines and pasting it after the bar's visible property. Change the point size to 9.
Now lets add labels beneath the bars. Scroll down to below the baseline rule and type example.add(pv.Label). Add a data array for the labels with initials for months. The initials have to be in quotes because they are text and the array must be inside square brackets.
Set the bottom to 0 and the letters show up in the bottom left corner of the graphic.
We want the months to be positioned directly under the bars so copy the left property from the bar and paste after bottom. Change the font by copying the font property from the bars and pasting it after the labels' left property. Change the point size to 7.
Making a label for the top
Finally, we're going to add a label to the top of the chart. Scroll up and above the ticklines, type example.add(pv.Label). Type .text and in parentheses and quotes, add the text that will be displayed in the graphic. Use .top to set the position 12 pixels from the top. Copy the font and textStyle from the ticklines and change the point size to 7. Below is the complete code you need to create the chart.
And there you have it. That was a bit of work but now you have a chart you can reuse. In Part 3 we'll work with variables to make reusing these charts much easier and add interactivity.
Remember to visit the Protovis site for documentation and kdmc.berkeley.edu for additional tutorials.