GraphTutorial

In this beta cluster tutorial we will create an interactive graph that will display historical fertility rates per country, with a slider to pick the year, and a map to show rate distribution around the world. See also complete Vega documentation. The definition for this graph is here.

Drawing Shapes

We start with drawing a few elements (marks). The graph code is surrounded by the <graph mode=interactive>...</graph> tag, even though the graph is not yet interactive.

Hint: Use "edit source" to copy the graph spec to the Vega Editor for experimentation.

{
  // We want to use Vega 2, and specify image size
  "version": 2, "width": 300, "height": 80,
  // Set padding to the same value on all sides
  "padding": 12,
  // By default the background is transparent
  "background": "#edf1f7",
  "marks": [
    {
      // Draw the year label
      "name": "yearLabel",
      "type": "text",
      "properties": {
        "enter": {
          "x": {"value": 0},
          "y": {"value": 25},
          "fontSize": {"value": 32},
          "fontWeight": {"value": "bold"},
          "fill": {"value": "steelblue"},
          "text": {"value": 2000}
        },
      }
    },
    {
      // Draw a horizontal line
      "name": "scrollLine",
      "type": "rule",
      "properties": {
        "enter": {
          "x": {"value": 0},
          "y": {"value": 40},
          "x2": {"value": 300},
          "stroke": {"value": "#000"},
          "strokeWidth": {"value": 2}
        }
      }
    },
    {
      // Draw a triangle shape with a hover effect
      // naming objects allows us to reference them later
      "name": "handle",
      "type": "path",
      "properties": {
        "enter": {
          "x": {"value": 200},
          "y": {"value": 40},
          // path syntax is the same as SVG's path tag
          "path": {"value": "m-5.5,-10l0,20l11.5,-10l-11.5,-10z"},
          "stroke": {"value": "#880"},
          "strokeWidth": {"value": 2.5}
        },
        "update": {"fill": {"value": "#fff"}},
        // Change fill color of the object on mouse hover
        "hover": {"fill": {"value": "#f00"}}
      }
    }
  ]
}

IsDragging signal

To make our handle object dragable, we first need to figure out if it was clicked or not. For that, lets add a signal that becomes true when an object is clicked (isDragging), and a text mark to show (debug) the result:

"signals": [
  {
    "name": "isDragging",
    "init": false,
    "streams": [
      {"type": "@handle:mousedown","expr": "true"},
      {"type": "mouseup","expr": "false"}
    ]
  },
],

// in "marks"
  {
    "name": "debugIsDragging",
    "type": "text",
    "properties": {
      "enter": {
        "x": {"value": 250},
        "y": {"value": 0},
        "fill": {"value": "black"}
      },
      "update": {"text": {"signal": "isDragging"}}
    }
  }

Handle Position signal

Now that we know when the object is being dragged, we add a mousemove signal that only changes its value when isDragging signal is true We also attach the new signal to the handle's "x" coordinate via "update" section:

// in "signals"
  {
    "name": "handlePosition",
    "init": 200,
    "streams": [
      {
        "type": "mousemove[isDragging]",
        "expr": "eventX()"
      }
    ]
  }

  // add in "marks"
  {
    "name": "handle",
    ...
    "update": {
      "x": {"signal": "handlePosition"},
      ...
    },
  },
  {
    "name": "debugHandlePosition",
    "type": "text",
    "properties": {
      "enter": {
        "x": {"value": 250},
        "y": {"value": 14},
        "fill": {"value": "black"}
      },
      "update": {"text": {"signal": "handlePosition"}}
    }
  }

Scaling Handle Position signal

Having pixel position of the handler is not very good - we would much rather have a position that is meaningful to our graph, e.g. a year. Vega scales provide a useful mechanism for converting between our data (e.g. years) and the screen coordinates, and back (invert). In this step, we add "yearsScale" linear scale for values 1960..2013, mapping it to the whole width of the graph (excluding padding). We also add a new scaledHandlePosition signal that translates from the mouse X position to the meaningful value in years.

// add "scales" root value:
  "scales": [
    {
      "name": "yearsScale",
      "type": "linear",
      "zero": false,
      "domain": [1960, 2013],
      "range": "width"
    }
  ],

// in "signals", add:
    {
      "name": "scaledHandlePosition",
      "expr": "handlePosition",
      "scale": {"name": "yearsScale","invert": true}
    }

  // add in "marks"
    {
      "name": "debugScaledHandlePosition",
      "type": "text",
      "properties": {
        "enter": {
          "x": {"value": 250},
          "y": {"value": 28},
          "fill": {"value": "black"}
        },
        "update": {"text": {"signal": "scaledHandlePosition"}}
      }
    }

Year value cleanup

As you might have noticed, the handle could be moved beyond the length of our graph, producing incorrect results. Also, the scaled value is not an integer that we expect of the year value. To fix this, we can introduce one more post-processing signal called "currentYear" to convert it to an integer and limit it to the needed range. We also initialize it to a reasonable value, and we tie both the "yearLabel" and the position of the handle bar back to this value. Note that the handle's position needs to be in screen coordinates, so we have to use the "yearsScale" to convert the value back:

    // New signal:
    {
      "name": "currentYear",
      "init": 2000,
      "expr": "clamp(parseInt(scaledHandlePosition),1960,2013)"
    }

    // Update yearLabel mark:
    {
      "name": "yearLabel",
      "properties": {
        "update": {"text": {"signal": "currentYear"}}
      }
    },

    // Update handle mark:
    {
      "name": "handle",
      "properties": {
        "update": {
          "x": {"scale": "yearsScale","signal": "currentYear"}
        },
      }
    }

Final cleanup

Now we can remove all the debugging marks. We also don't need separate handlePosition and scaledHandlePosition signals because scaling can happen in the same step:

{
  "version": 2,
  "width": 300,
  "height": 80,
  "padding": 12,
  "background": "#edf1f7",
  "signals": [
    {
      "name": "isDragging",
      "init": false,
      "streams": [
        {"type": "@handle:mousedown","expr": "true"},
        {"type": "mouseup","expr": "false"}
      ]
    },
    {
      "name": "scaledHandlePosition",
      "streams": [
        {
          "type": "mousemove[isDragging]",
          "expr": "eventX()",
          "scale": {"name": "yearsScale","invert": true}
        }
      ]
    },
    {
      "name": "currentYear",
      "init": 2000,
      "expr": "clamp(parseInt(scaledHandlePosition),1960,2013)"
    }
  ],
  "scales": [
    {
      "name": "yearsScale",
      "type": "linear",
      "zero": false,
      "domain": [1960,2013],
      "range": "width"
    }
  ],
  "marks": [
    {
      "name": "yearLabel",
      "type": "text",
      "properties": {
        "enter": {
          "x": {"value": 0},
          "y": {"value": 25},
          "fontSize": {"value": 32},
          "fontWeight": {"value": "bold"},
          "fill": {"value": "steelblue"}
        },
        "update": {"text": {"signal": "currentYear"}}
      }
    },
    {
      "name": "scrollLine",
      "type": "rule",
      "properties": {
        "enter": {
          "x": {"value": 0},
          "y": {"value": 40},
          "x2": {"value": 300},
          "stroke": {"value": "#000"},
          "strokeWidth": {"value": 2}
        }
      }
    },
    {
      "name": "handle",
      "type": "path",
      "properties": {
        "enter": {
          "y": {"value": 40},
          "path": {"value": "m-5.5,-10l0,20l11.5,-10l-11.5,-10z"},
          "stroke": {"value": "#880"},
          "strokeWidth": {"value": 2.5}
        },
        "update": {
          "x": {"scale": "yearsScale","signal": "currentYear"},
          "fill": {"value": "#fff"}
        },
        "hover": {"fill": {"value": "#f00"}}
      }
    }
  ]
}

Drawing a map with some useful data

Now that the slider is working, we can add a map and mix it with the highlighting data. The map is stored as a raw TopoJSON text in wiki markup here. Each country is tagged with a ISO-3 country code. For this example, we will use fertility data that is stored as a CSV text in wiki markup here, copied from WorldBank (license). The CSV contains "country", "id" columns, as well as years 1960..2013, each as a separate column.

  // add data section
  "data": [
    {
      "name": "highlights",
      "url": "wikiraw:///Extension:Graph/Demo/RawData:FertilityByCountryHistoric-csv",
      "format": {"type": "csv"},
      "transform": [
        {
          "type": "formula",
          "field": "v",
          // convert currentYear to a string and use it as a column name. Parse string value as a float.
          "expr": "parseFloat(datum[''+currentYear])"
        }
      ]
    },
    {
      "name": "countries",
      "url": "wikiraw:///Extension:Graph/Demo/RawData:WorldMap-iso3-json",
      "format": {"type": "topojson","feature": "countries"},
      "transform": [
        {
          // map data needs to be converted into paths for the "path" mark
          "type": "geopath",
          "value": "data",
          "scale": 80,
          "center": [-180,125],
          "translate": [0,0],
          "projection": "equirectangular"
        },
        {
          // For each country ID in the map, find a matching entry in the highlights table and attach it as "zipped" value
          "type": "lookup",
          "keys": ["id"],
          "on": "highlights",
          "onKey": "id",
          "as": ["zipped"],
          "default": {"v": null}
        }
      ]
    }
  ],
  // add color scale
    {
      "name": "color",
      "type": "linear",
      "domain": {"data": "highlights","field": "v"},
      "zero": true,
      "range":  ["#ffff65","#cb0000"]
    }
  // add a path drawing mark to show the map
    {
      "name": "map",
      "type": "path",
      "from": {"data": "countries"},
      "properties": {
        "enter": {"path": {"field": "layout_path"}},
        "update": {"fill": {"scale": "color","field": "zipped.v"}},
        "hover": {"fill": {"value": "#989898"}}
      }
    }

Adding Legend

Graph will be more informative if the user sees how colors correspond to numbers. Unfortunatelly Legend placement is a bit broken at the moment and will need to be fixed in Vega, but it tends to work in non-map based graphs.

  // Add this section to the root object
  "legends": [
    {
      // "color" is the name of the scale to show
      "fill": "color",
      "title": "Fertility",
      "offset":-300,
      "properties": {
        "gradient": {
          "stroke": {"value": "transparent"}
        },
        "title": {
          "fontSize": {"value": 14}
       },
      }
    }
  ],

Adding Some Statistics

The map mouseover event does not work in this graph due to the bug in Vega, so the name of the country will not appear until the server update.