Introducing Crease
A new Ruby gem to give data a narrative context.
We’re pleased to introduce Crease, a Ruby gem that helps give a narrative context to data.
With Crease, you can pass data into English-like Ruby methods, and it will describe the data. For example, increased.by(100)will output “increased by 100”, and an.increase.of(-100).percent will take the negative into account, and return “a decrease of 100%”.
You can also give it starting and ending values, and it will calculate the change for you. For example, increased.by(2, 4).percent outputs “increased by 200%”, and an.increase.of(100, 0) outputs “a decrease of 100”.
Crease is also open-source, and we would like to expand the gem’s capabilities to include cases beyond our own.
Why narrative context matters
In our housing production portal, Housing MA, we use our housing data database to generate a report on housing trends and projections for every city and town in the state. We wanted to be able to set the data in a narrative context, explaining trends to the reader in plain language, using a single, simple template.
For example, we wanted the housing trends report for Boston to have a sentence like:
“Total households in Boston are projected to increase by 50,000 through 2030, an increase of 20 percent from 2010.”
And using the same template, but with data from the small Central Massachusetts town of Rutland, the sentence should read:
“Total households in Rutland are projected to decrease by 2,800 through 2030, a decrease of 100 percent from 2010.” (Emphasis added.)
What we did before Crease
Data-driven narratives before Crease were challenging.
One option was doing conditional math in the Haml or ERb template for each data-driven narrative moment, but this quickly became unmaintainable. We had a long Haml template we were trying to keep legible and navigable, and 45 nested conditionals were not helping with that. While one could argue that this is presentation logic and so belongs in the view, it was very repetitive.
In order to DRY up our code, we created a class to do these calculations. We weren’t trying to implement plain-language syntax at the time — we just wanted to do the math. This led to a class with some pretty clunky syntax, though it certainly got the job done.
By using Crease, anyone can look at the template and see what the narrative is trying to say, because it reads just like English.
Where Crease can take you
Data-driven narratives are becoming more common as open data and civic technology flourish.
We use Crease to help us explain housing data trends so that city and town planners can make informed decisions about the kinds of housing they’ll need to build to help their communities flourish.
Our ultimate goal with Crease is to help you communicate important trends to your readers and use data to drive better decisions. We think it can speed up the creation of data-driven narratives and get your information in front of the people who matter — faster.
