⌫ Home

Dailygraphics Demo Talk

Contained herein are talk notes and links to examples and demonstrations from my March 2017 talk at the Collegiate Web Developers Group at the Ohio State University about NPR's dailygraphics rig. I don't use the dailygraphics rig professionally, but I think it's a really cool tool that people at CWDG may be interested in.

Thus, this talk.

Hi, I'm Ben Keith (@benlkeith), I work for the tech team at the Institute for Nonprofit News, and I build WordPress sites for a living.

You're wondering why I'm doing this talk if I don't usually build front-end stuff. I'm building it because I think this is a really cool tool. If you're a journalist in the audience, please raise your hand. You're probably going to have ideas for three different things you want to build with this by the end of this talk.

What is the dailygraphics rig? An explanation

It's a framework for building small, embeddable things. Charts, tables, histograms, and graphs. there's a lot of options by default.

Read this slide deck by Alyson Hurt, the graphics editor on the Visuals team at NPR. The presenter notes are essential to understanding the slides.

Now is the part where I show off this rig on my computer. Here's a graphic that took me about 30 minutes to make:

Examples on other sites:

See also the archive of graphics by St. Louis Public Radio, and the list of things included by default with the dailygraphics rig.

A demonstration of the dailygraphics rig

Follow along with me as I make a new graphic.

Data source: the $ billion per-department changes in this sheet: https://www.washingtonpost.com/graphics/politics/trump-presidential-budget-2018-proposal/

Things I'm assuming:

Here's the process to make the graphic that follows. Remember that the dailygraphics rig itself lives in dailygraphics/ and the graphics live in graphics/. I'll preface each command with the directory name; I keep each directory open in a separate terminal.

In a third terminal, go to the dailygraphics/ folder and run fab app.

Let's make a new graphic.


dailygraphics/ $ fab add_bar_chart:budget_by_dollar

This will output a bunch of stuff, including a link to a Google Sheet. This sheet is the one used in my graphic.

When you ran fab app, it said something about http://0.0.0.0:8000/. Open a web browser and go there now. You'll see a list of graphics, including the budget_by_dollar that you just created. Click the link to view the graphic.

Your graphic will have some boilerplate content, and will be embedded in a page with some buttons at the top:

A screenshot of some buttons, labeled from left to right: Sidebar (180px), Mobile (300px), Desktop (730px), Fluid (100%), Staging, Production, Spreadsheet

Clicking the "spreadsheet" button will take you to your Google Sheet, which has two tabs: labels and data.

The "Labels" tab is a list of keys and values. The keys correspond to particular areas of text in the template, which is explained under "Connecting to a Google Spreadsheet". If you edit the text, changes will appear in your app as long as you're previewing using the preview URL ending in ?refresh=1 and as long as fab app is running. When you load the page with ?refresh=1 or run fab update_copy:budget_by_dollar, the dailygraphics rig will download the latest copy of the spreadsheet and use it when rendering your graphic.

The "Data" tab is updated the same way, but here you're entering labels and values. When entering numerical values, don't use commas or % or $ or units. Just enter bare numbers, like -15100000000. You can format those numbers in the graphic by using Javascript and D3.js. I'll get into that in a little bit.

Let's copy the department names and dollar-amount changes in budget from this Washington Post story. Remember to copy the numbers without commas or units, and to write out all the zeros in each billion.

Reload the graphic preview page.

At this point, you'll notice that the numbers displayed on the chart are … wrong. Budgets don't change by -15,100,000,000%. So now we need to change how numbers are formatted in the chart. Number formatting is handled by graphics/budget_by_dollar/js/graphic.js, in a couple places. The x axis is made by this function:

/*
 * Create D3 axes.
 */
var xAxis = d3.svg.axis()
	.scale(xScale)
	.orient('bottom')
	.ticks(ticksX)
	.tickFormat(function(d) {
		return d.toFixed(0) + '%';
	});

Let's replace that with one that divides the number d by one billion, then rounds to the nearest billion:

/*
 * Create D3 axes.
 */
var xAxis = d3.svg.axis()
	.scale(xScale)
	.orient('bottom')
	.ticks(ticksX)
	.tickFormat(function(d) {
		return '$' + (d/ 1000000000).toFixed(0) + ' billion';
	});

Here's the change:

--	return d.toFixed(0) + '%';
++	return '$' + (d/ 1000000000).toFixed(0) + ' billion';

Now let's format the numbers that appear in the chart itself. The original code shows the number directly as a percent, as part of a larger function:

/*
 * Render bar values.
 */
chartElement.append('g')
	.attr('class', 'value')
	.selectAll('text')
	.data(config['data'])
	.enter()
	.append('text')
		.text(function(d) {
			return d[valueColumn].toFixed(0) + '%';
		})

Where the variable d was the label before, now d is a more-complex object, of which we only need the valueColumn value to be divided by one billion, rounded down to one decimal point with toFixed, and then appended with a B-for-billion.

/*
 * Render bar values.
 */
chartElement.append('g')
	.attr('class', 'value')
	.selectAll('text')
	.data(config['data'])
	.enter()
	.append('text')
		.text(function(d) {
			return (d[valueColumn]/ 1000000000).toFixed(1) + 'B';
		})

Here's the entire change

--	return d[valueColumn].toFixed(0) + '%';
++	return (d[valueColumn]/ 1000000000).toFixed(1) + 'B';

And that's it.

There is still some work to be done here (you'll note that agency names overlap) but we've created a very simple chart without a lot of work.

Now to copy it off my computer and onto someone else's. Here's the process:

  1. Render the graphic
  2. Copy it to production
  3. Find the production URL and paste it into a blog post

To render the graphic:

dailygraphics/ $ fab render:budget_by_dollar

This bakes out all the stuff that fab app is doing into flat, unchanging files so that they can be hosted on a static web server. If you've heard of static site generators, that's precisely what we're doing.

To copy it to production, you're going to need a production server, and by "production server" I mean a place somewhere on the Internet that will let you upload a bunch of arbitrary files. NPR uses Amazon S3 with some custom commands for fab. I use a cheap shared-hosting site and upload things via git. Someone has probably set up their graphics on GitHub Pages.

First, let's make sure that you're controlling your graphics with Git.

graphics/ $ git status
fatal: Not a git repository (or any of the parent directories): .git

If you got that message, let's create a git repository.

graphics/ $ git init
Initialized empty git repository in /tmp/graphics/.git/
graphics/ $ git status
On branch master

Initial commit

Untracked files:
  (use "git add <file>..." to include in what will be committed)

	budget_by_dollar/

nothing added to commit but untracked files present (use "git add" to track)
graphics/ $ git add budget_by_dollar/

If you run git status, it'll show you all the files in budget_by_dollar/ that are now tracked by git. Commit those changes:

graphics/ $ git commit -m "Adding the budget_by_dollar graphic"
[master (root-commit) ebd7f2b] Adding the budget_by_dollar graphic
 24 files changed, 3029 insertions(+)

But version control is useless without a remote.

Assuming you're using git to deploy instead of fab deploy:

graphics/ $ git push -u origin master

That copies all your changes to the remote. Go to the URL of your remote repository to check out the content. For me, that's f.benlk.com/graphics/budget_by_dollar/child.html

Let's go back to http://0.0.0.0:8000/, to your graphic. There will be two embed codes at the bottom of the preview page; choose the non-Seamus one. Copy the embed code onto your website. Then replace the URL for the graphic with the actual URL of the graphic on your server, if it's different from the NPR URL. (It should be different.)

I've done that here:

_

If you use WordPress, install the Pym Shortcode plugin and then use that to embed your graphic.

To recap, we've:

Guides to using the dailygraphics rig

Setup instructions.

Workflow documentation.

More about Pym.js, the javascript that powers the embeds.

Check out the "Dailygraphics" section of the Visuals team's list of tools. Particularly interesting in understanding the philosophy behind the tool is this Source interview with Alyson Hurt and Chris Groskopf about dailygraphics.

If you don't want to bother with deploying to Amazon S3, you have several options, which were touched on earlier in the demo:

For my graphics, I use git to push changes to f.benlk.com/graphics/

How to choose which type of graphics to make.

If you want to see all the interesting things that journocoders do, one place to start is Source, an OpenNews project that "amplifies the impact of journalism code and the community of developers, designers, journalists, and editors who make it."

For slides and tipsheets from NICAR, Chrys Wu has an excellent roundup.

Corrections and Credits

The CWDG email announcing this talk said I work for NPR. I don't. I work for the Institute for Nonprofit News. My connections to NPR are through work that INN has done for NPR and friends I've made who work for NPR. NPR does awesome stuff and has a bunch of cool tools, many of which are built by the NPR Visuals Team.

This talk and blog post are brought to you in part by INN, which paid for my travel to NICAR 2017, the conference that inspired this talk.

Changelog:

March 31, 2017:

March 30, 2017:

March 29, 2017:

March 28, 2017:

Dailygraphics Demo Talk - March 28, 2017 - Ben Keith