Home
MetricsGraphics.js is a library optimized for visualizing and laying out time-series data. It provides a simple way to produce common types of graphics in a principled and consistent way.
We're encapsulating what we see as best practices for effective data presentation, of which charts are one component. We're not aiming to be competitive with libraries that already exist, but to make a library that meets our needs. We also happen to think that the world needs a principled data presentation library, and that many of our needs are the same as other people's.
The API is simple. All that's needed to create a graphic is to specify a few default parameters and then, if desired, override one or more of the optional parameters on offer. We don't maintain state. In order to update a graphic, one would call MG.data_graphic on the same target element.
The library is data-source agnostic. While it provides a number of convenience functions and options that allow for graphics to better handle things like missing observations, it doesn't care where the data comes from.
The library now depends on D3 4. The impact on MG users is minimal, though if you do use D3 for other work, here is the list of changes from 3.x to 4.x. Please refer to the release notes for further details.
- The library is now namespaced.
data_graphicis nowMG.data_graphic,convert_datesis nowMG.convert.date,cloneis nowMG.clone,button_layoutis nowMG.button_layoutanddata_tableis nowMG.data_table. We added a new convenience function calledMG.convert.number. - The
rollover_callbackoption has been renamedmouseoverand expanded in order to make it more consistent with other libraries. We now have three callback functions available: mouseover, mouseout and mousemove. - CSS rules have been prefixed and in some cases updated for consistency.
active_datapointfor instance is nowmg-active-datapoint.
- Download the latest release.
- Follow the examples here and here to see how graphics are laid out and built. The examples use JSON data from examples/data, though you may easily pull data from elsewhere.
The library depends on D3. If you wish to enable tooltips or use buttons, please include jQuery as well. Versions of MG older than v2.10 depend on D3 3, whereas MG v2.10 onwards depend on D3 4.
If you would like to help extend MetricsGraphics.js or fix bugs, please fork the library and install Node.js. Then, from the project's root directory install gulp:
install gulp
Then, install the library's dependencies:
npm install
To build the library from source, type:
gulp build:js
To run tests, type:
gulp test
In order to request or faciliate deployments to metricsgraphicsjs.org, please contact Natalie Haywood (nhaywood@mozilla.com).
You might also be interested in writing addons for the library, in which case, have a read through this page.
- Examples
- Interactive demo
- List of options
- Convenience functions
- Hooks
- Chart types
- Developing addons
- Building a button layout
The download package includes everything that you see on metricsgraphicsjs.org. In order to use the library in your own project, the only files that you'll need are the ones under dist. Remember to load D3 and jQuery. If you don't care about tooltips or the button layout, you won't need the latter. If your project uses Bootstrap, make sure you load MetricsGraphics.js after it.
What does MetricsGraphics.js do that library x doesn't do?
If library x works for you, you should keep using it. We're not aiming to be competitive with libraries that already exist. We're aiming to make a library that meets our needs. We also happen to think that the world needs a principled data presentation library, and that many of our needs are the same as other folks'.
I only see the first five lines in my chart, what gives?
The colors for the first five lines, areas and legends are defined in the stylesheet for the light and dark themes. For a sixth line, you would add the follow CSS rules:
.mg-line6-color {
stroke: steelblue;
}
.mg-area6-color {
fill: steelblue;
}
.mg-hover-line6-color {
fill: steelblue;
}
.mg-line6-legend-color {
color: steelblue;
}If you're plotting more than five lines in the same chart and using color to encode some dimension of the data, then you probably need to rethink the chart.
I get an error when I load MG alongside library x
If your project uses Bootstrap, make sure you load MetricsGraphics.js after it. If your project uses jQuery UI, load it after MetricsGraphics.js.
Feel free to add your addons and websites to this list.