See it, believe it: The Web Visualization Library

Have you ever looked at a health graph and felt pride (or shame!) about what you saw?

Or confusion?

Or maybe curiosity?

Whether we are looking for better insights, or just some motivation, visualization is a time-tested way of bringing data to life. But to help us stay inspired and focus on what matters, we need tools that help us quickly generate meaningful visual aides.

In this post, I will explain why we built the Open mHealth Web Visualization library, how we made some key design and engineering decisions, and why we believe it is a good solution to our community’s needs.

Relevant Visualizations, Minimal Effort

Our thinking at the start of this project went something like: wouldn’t it be great if people in our community could build relevant visualizations of Open mHealth data with minimal effort?

So our high-level goals were:

Share the UX/UI lessons we learned from creating Linq, a responsive web app that helps doctors and patients make better clinical use of mobile health data
Make it easy for even a novice developer to visualize OmH data
Meet the specific visualization needs of our growing community

But there are countless visualization and graphing libraries on the web, and certain kinds of visualizations are better suited to mHealth data than others. So starting this project was both exciting and daunting. Yes, we were excited to have so many options; but we had to do a lot of research to find the best fit.

Discovering the Range of Needs

The user research that went into building the Web Visualization library falls roughly into two categories: what our medical community needs, and what our development community needs.

We spoke to clinicians…

In early 2015, we began beta testing Linq, our first mHealth webapp, at the Stanford Preventative Cardiology clinic. Using Linq, patients and doctors can create a shared tracking plan together, set smart-goals, and use the information they collect to answer the health questions that matter to them.

While designing Linq, the Open mHealth team interviewed about half a dozen cardiologists at Stanford and Columbia. We also tested our work with them once we had a prototype. Although many of the topics we covered were only directly applicable to the Linq use-case, some basic core concepts about visualization emerged.

Clinicians should be able to see ‘at a glance’ if a data point is outside the goal range
On interaction with a data point (like hover, or tap) it is helpful to see a date and timestamp, whether the point was in- or out-of range, and information about the data source
Basic x- and y-axis numbers and units should be visible
In general, it is helpful for information relating to ‘time’ to be visually associated with the x-axis
Graphs that deal with multiple data streams and scales may need multiple y-axes (like with ‘steps’ and ‘minutes of activity.’)
It is important to understand the density of data on a graph; in other words, to be able to quickly understand where there is and is not data

You can find a summary of our findings about what metrics clinicians want to see for key digital health measures in the documentation section of our website. This research became the foundation of our library’s UI.

…and we spoke to developers.

Several months later, at our first Open mHealth Summit in San Francisco, we discussed our design strategy and asked the community to tell us what they needed. By distributing a survey and holding an informal Q&A session, Katie and I learned about some common needs:

The library should work well on any web-enabled device
Flexibility, ease of use, and elegant design are all important
The visualizations will be used in many contexts—at home, in the clinic, and in research. They will be viewed by the general public, patients, and clinicians
The visualizations will be used to help people understand health trends that are unfolding over time
Showing goals along with the data is an important feature
Technical barriers, time constraints, and visual design issues prevent our community members from writing this code
Many are attracted to Open mHealth because it is free and open source, so any visualization library dependencies should also be free and open source
D3, in particular, is attractive because it is free, open-source, and extensible, but…
D3 is also unattractive because it is very complex, and some find it hard to debug

Exploring the Existing Technology

Once we had some awareness of our community’s needs, it was time for me to survey the field of web visualization tools and find a library to extend and customize. Since our visualizations would be used primarily for exploring trends and tracking goals over time, I focused the search on libraries that graph time-series data.

First, I revisited some excellent libraries that we had used in our implementation of Linq:

I also asked around in our community (thanks sherbit!) and found:

Lastly, I did my own research into free, open-source chart libraries and noticed, in particular:

As well as a number of great high-level resources for making the decision:

And the winner is… Plottable! But why?

Seeing all of these libraries in action, our requirements began to crystalize. Ideally our library would meet the following criteria:

Built on D3, but easier to work with
No commitment to a big “MVW” framework like angular
Good out-of-the-box UX design and interactivity
Simple and attractive
Customizable using CSS (SVG based)
Flexible layouts
Mobile/tablet-ready
Active developer community
Well documented

As fate would have it, my search came to an end here. This page, a scrappy transcript of Dan Mane’s 2014 JSConf EU presentation on Plottable.js, struck a chord. There are just too many libraries out there, and development teams find themselves alternately reinventing the wheel or jumping ship to try a new solution. The full video of his talk is available here.

This excerpt from the Plottable.js git repository is a great summary of what plottable does to address the problem:

Plottable.js is a library of chart components for creating flexible, custom charts for websites. It is built on top of D3.js and provides higher-level pieces, like plots, gridlines, and axes. As such, it’s easier to quickly build charts than with D3, and the charts are much more flexible than standard-template charts provided by charting libraries. You can think of Plottable as a “D3 for Charts” – it is not a charting library but a library of chart components.

In particular, I liked Dan’s point during his presentation about enabling developers and designers to work well together. While building Linq, there were times when we changed the design, wrote workarounds, or even switched libraries in order to meet our design specification. That’s why we found Plottable’s core philosophy–Composition over Configuration–very attractive. Their modules offer just the right level of abstraction, so countless UI/UX designs can be implemented with minimal effort.

For example, a big bonus we get with Plottable is the beautiful time axis with pan/zoom interaction–and the ability to customize it. Since time is the critical parameter in the majority of tracking work that clinicians and patients do together, it is exciting to see the thought that Palantir has put into the axis. And, thanks to their composition philosophy, we are able to make tweaks to the axis and add features as needed.

So, on top of all the other benefits we were seeking, Plottable makes our visualization library flexible. That is why I believe it will be useful to developers with a variety of needs and skill levels.

Getting Started with Our Code

In a future blog post, we will provide a deeper look into using the Open mHealth Web Visualization library. If you would like to get started now, though, keep reading for an overview and some links to our code.

As a developer using our library, you have three different options when building a chart:

Just create a new chart and let our default settings take care of the features and appearance
Create your chart with some configuration information, to add customizations
Create a chart, and then use Chart.getComponents() to access the resulting Plottable components for deeper customization, as in Dan Mane’s Chartographer.

We have created these three different entry-points to meet a range of needs. We provide default chart properties for developers who want a quick solution, a configuration parameter for those who need to make some slight alterations, and access to the Plottable components for those who wish to alter the composition of the chart’s UI.

To start writing code and playing around with the library, I would suggest that you first try out this live demo. It’s a great place to test out our instructions on how to configure and render a chart.

To start using the library in your own project, head over to Github, where you can download the software and read a primer. Definitely check out our example code, feel free to submit issues, and by all means, contribute! Over the next few months, we will be adding features and building out a set of unit and integration tests, so we would love any help you can offer.
We hope the Open mHealth Visualization library meets your needs and sparks some inspiration. Enjoy!