Tag: Slow Roll Chicago

Why the Slow Roll Chicago working group uses GitHub to collaborate

March 25, 2015 / / 0 Comments

When the Slow Roll Chicago project in the transportation breakout group began in December at Hack Night, the emails started flying right away.

This was mainly because there was a lot to say at the start, as we needed to agree on the group’s mission and plan.

Problems using email started immediately, though. Not only were there many emails going back and forth among people listed on the TO and CC fields, there were people who weren’t able to take part in these discussions.

That happened because it was difficult to keep track of who had been added to the discussion and who hadn’t, especially when it came to integrating new members of the group.

I wanted to overcome these problems by using a proper collaboration tool.

Email wasn’t just limiting our discussion quality and member inclusion, it was also limiting file storage, file sharing, and file versioning (which file is the latest?). Email has tended to demand a lot of attention, and there’s a lot of wasted time typing responses. I wanted to use a tool that didn’t have such demands, and that helped organize responses into actionable requests and delegation.

Using email made it impossible to see what tasks people were working on, and the progress they were making at any given moment.

Finally, email tends to be private but our work needed to be public so that it could be independently verified but also replicated for use in other locales.

I believe that it’s easier to train people on how to use a new tool well than to retrain on how to use an existing tool – email – better.

GitHub has solved all of these problems for our group while also creating a secure and versioned programming code storage system for the final outcome: a website.

Hack Night being a tech-oriented meetup is a good reason to use and teach this modern tool widely used by people in technology industries. Many of our members are still learning it but they have support from people within our group and from others who attend Hack Night.

GitHub handles our discussions, task assignments, task progress, notes, and files. Here’s how:

When you want to discuss a new idea, like using dynamic images to show what a building could look like under certain conditions, you would make a new “issue”, titled, “Use dynamic images to show the user some building design possibilities”. Use rich text and images in the issue to describe and visualize the idea.

GitHub has granular notifications settings that alert project members to this new “issue” after which they can respond to your idea. After it’s decided that the issue should be resolved in a specific way, you can assign the issue a desired milestone (a future project version) and project members.

One milestone could be “Preview to the management team” which is a previously-discussed status that should happen in a couple weeks. A second milestone could be “Post-launch” – things to finish after launching the product – that’s defined offline.

Each milestone tracks the issues that you’ve associated with it so you can see progress. When the assigned members finish a task, they “resolve” the issue by closing it.

Need documentation? For many coding or GIS projects, a data dictionary may be necessary and GitHub provides each project repository with a wiki in which you would describe how the project is set up, and what certain fields or values mean.

Finally, GitHub can store files – any kind, and as many versions. If you need to update a CSV file of street addresses for the project, just make the edits in your preferred editor on the desktop and then “commit” your changes with a short description of what you changed. Sync this commit back to the repository so that all project members now have access to the file.

Use Turf to perform GIS functions in a web browser

March 11, 2015 / / 0 Comments
Turf's merge function joins invisible buffers around each Divvy station into a single, super buffer.

Turf’s merge function joins invisible buffers around each Divvy station into a single, super buffer –all client-side, in your web browser.

I’m leading the development of a website for Slow Roll Chicago that shows the distribution of bike lane infrastructure in Chicago relative to key and specific demographics to demonstrate if the investment has been equitable.

We’re using GitHub to store code, publish meeting notes, and host discussions with the issues tracker. Communication is done almost entirely in GitHub issues. I chose GitHub over Slack and Google Groups because:

  1. All of our research and code should be public and open source so it’s clear how we made our assumptions and came to our conclusions (“show your work”).
  2. Using git, GitHub, and version control is a desirable skill and more people should learn it; this project will help people apply that skill.
  3. There are no emails involved. I deplore using email for group communication.*

The website focuses on using empirical research, maps, geographic analysis to tell the story of bike lane distribution and requires processing this data using GIS functions. Normally the data would be transformed in a desktop GIS software like QGIS and then converted to a format that can be used in Leaflet, an open source web mapping library.

Relying on desktop software, though, slows down development of new ways to slice and dice geographic data, which, in our map, includes bike lanes, wards, Census tracts, Divvy stations, and grocery stores (so far). One would have to generate a new dataset if our goals or needs changed .

I’ve built maps for images and the web that way enough in the past and I wanted to move away from that method for this project and we’re using Turf.js to replicate many GIS functions – but in the browser.

Yep, Turf makes it possible to merge, buffer, contain, calculate distance, transform, dissolve, and perform dozens of other functions all within the browser, “on the fly”, without any software.

After dilly-dallying in Turf for several weeks, our group started making progress this month. We have now pushed to our in-progress website a map with three features made possible by Turf:

  1. Buffer and dissolving buffers to show the Divvy station walk shed, the distance a reasonable person would walk from their home or office to check out a Divvy station. A buffer of 0.25 miles (two Chicago blocks) is created around each of the 300 Divvy stations, hidden from display, and then merged (dissolved in traditional GIS parlance) into a single buffer. The single buffer –called a “super buffer” in our source code – is used for another feature. Currently the projection is messed up and you see ellipsoid shapes instead of circles.
  2. Counting grocery stores in the Divvy station walk shed. We use the “feature collection” function to convert the super buffer into an object that the “within” function can use to compare to a GeoJSON object of grocery stores. This process is similar to the “select by location” function in GIS software. Right now this number is printed only to the console as we look for the best way to display stats like this to the user. A future version of the map could allow the user to change the 0.25 miles distance to an arbitrary distance they prefer.
  3. Find the nearest Divvy station from any place on the map. Using Turf’s “nearest” function and the Context Menu plugin for Leaflet, the user can right-click anywhere on the map and choose “Find nearby Divvy stations”. The “nearest” function compares the place where the user clicked against the GeoJSON object of Divvy stations to select the nearest one. The problem of locating 2+ nearby Divvy stations remains. The original issue asked to find the number of Divvy stations near the point; we’ll likely accomplish this by drawing an invisible, temporary buffer around the point and then using “within” to count the number of stations inside that buffer and then destroy the buffer.
Right-click the map and select "Find nearby Divvy stations" and Turf will locate the nearest Divvy station.

Right-click the map and select “Find nearby Divvy stations” and Turf will locate the nearest Divvy station.

* I send one email to new people who join us at Open Gov Hack Night on Tuesdays at the Mart to send them a link to our GitHub repository, and to invite them to a Dropbox folder to share large files for those who don’t learn to use git for file management.