Budget Visualization Framework

Our 2017 WordPress plugin is available here: https://github.com/goinvo/visualbudget

Open-source budget visualization framework.

Requirements

PHP-enabled webserver
SCSS compiler

Setup

Clone this repository to your local machine and point your webserver root to src/httpdocs, the application should work out of the box, this repository contains some sample data that can be used for testing.

Localized Variables

Set the variables in the localized_variables.php file to your municipality's information. These are global variables used throughout the Visual Budget instance. The file can be found in /src/httpdocs/includes.

Components

Cards

Report statical information about selected entry (src/httpdocs/js/cards.js).

Chart

Shows data change over time (src/httpdocs/js/chart.js).

Treemap

Used as the main navigation component (src/httpdocs/js/treemap.js).

Table

Alternative navigation technique to a treemap (src/httpdocs/js/tables.js).

Component Interface

Each component implements a common interface of 3 calls:

Initialize: called only once, prepares the component to show data
Open: opens a data object and displays its contents using the specified component
Update: refreshes component data (useful when year changes and new values need to be plotted)

Directory Structure

/config: Compass configuration files
/src/httpdocs: Application root directory
- css: compiled SCSS and libraries (bootstrap, introJs)
- data: CSV and JSON data files
  - processing: temporary directory for data conversion
    - processCSV.py: converts CSV file to nested JSON structure
    - update.php: Interface for data update
- img: image assets
- includes: templates and HTML assets
  - localized_variables.php: A collection of global variables specific to a municipaltiy.
  - imports.php: CSS and JS assets imports
  - datafiles.php: json datafiles loaded in each instance (AJAX can be used as an alternative)
  - home.php: homescreen html
  - navbar.php: navigation bar html
  - templates.php: contains Mustache templates (eg. table row templates, cards...)
- js: Javascript assets
  - avb.js: helper functions and initialization routines
  - cards.js: cards component routines
  - chart.js: chart component routines
  - home.js: homescreen routines and introJs based tutorials code
  - statistics.js: functions used to generate statistical info and number formatting functions
  - table.js: table component routines
  - treemap.js: treemap component routines
/src/scss: SCSS files
- print.scss: SCSS applied when printing a Visual Budget page
- global.scss: main SCSS file (imports all the partials defined below)
- partials: SCSS assets
  - _avb.scss: section styles
  - _base.scss: html, body styles, colors and font variables
  - _cards.scss: styles for card component
  - _chart.scss: styles for chart component
  - _home.scss: styles for homescreen
  - _navbar.scss: styles for top navigation bar
  - _table.scss: styles for tabular view
  - _treemap.scss: styles for treemap component

Required Libraries

Bootstrap (grid layout, dropdowns..)
D3 (visualizations)
Jquery Cookie
DetectMobileBrowser
Jquery
Mustache (templates)
IntroJS (required for tutorials)

Sample Datasets

Sample Expenses.json, Revenues.json and Funds.json from Arlington, MA in src/httpdocs/data.

Budget data is kept in JSON and CSV format. The JSON format is actively used for computation while the CSV format is kept for reference and data download.

Data structure

The base data unit is an object with the following fields:

key {string}: entry name
src {url string}: link to data source from where entry data was extracted (optional)
hash {string}: entry id (can be arbitrary)
sub {array of other entries}: subsections that make up current entry
descr {string} : entry description (optional)
values {array of value objects} : entry values over time

A simple value object is defined by:

year : year of value
val : value

This data structure could be changed should it be considered not ideal for future uses.

Data structure sample

The data sample below is partial section of src/httpdocs/data/funds.json.

{
   "key":"Funds",
   "src":"http://www.arlingtonma.gov/",
   "hash":"d42b2bb7",
   "sub":[
      {
         "key":"Tip Fee Stabilization Fund",
         "src":"www.arlin",
         "hash":"68a317f0",
         "sub":[],
         "descr":"The Town of Arlington participated in a regional solid waste consortium, and upon leaving the consortium in September 2005, the Town was entitled to revenue derived from the regional agreement.",
         "url":"",
         "values":[
            {
               "val":1885012.0,
               "year":2010
            },
            {
               "val":1010675.0,
               "year":2011
            },
            {
               "val":562906.0,
               "year":2012
            },
            {
               "val":164000.0,
               "year":2013
            }
         ]
      },
      {
         "key":"Override Stabilization Fund",
         "src":"",
         "hash":"cc5b3ad1",
         "sub":[],
         "descr":"This Fund was created as a result of the 2005 Proposition 2 1/2 override. The Town makes annual appropriations to the fund until the time in which it is necessary to make withdrawals for the purposes of balancing the general fund budget.",
         "url":"",
         "values":[
            {
               "val":1584330.0,
               "year":2010
            },
            {
               "val":0.0,
               "year":2011
            },
            {
               "val":3986819.0,
               "year":2012
            },
            {
               "val":7886125.0,
               "year":2013
            }
         ]
      },
      {
         "key":"Stabilization Fund",
         "src":"",
         "hash":"22772b4f",
         "sub":[],
         "descr":"In accordance with M.G.L. Ch. 40 S. 5B, the Town may appropriate in any year an amount not exceeding, in the aggregate, 10% of the amount raised in the preceding fiscal year's tax levy.",
         "url":"",
         "values":[
            {
               "val":2541858.0,
               "year":2010
            },
            {
               "val":2551951.0,
               "year":2011
            },
            {
               "val":2558551.0,
               "year":2012
            },
            {
               "val":2667328.0,
               "year":2013
            }
         ]
      }
   ],
   "descr":"All accounts which hold money from year to year. For more information, see the Glossary.",
   "url":"",
   "values":[
      {
         "val":8538240.0,
         "year":2010
      },
      {
         "val":5089098.0,
         "year":2011
      },
      {
         "val":8423147.0,
         "year":2012
      },
      {
         "val":18398926.0,
         "year":2013
      }
   ]
}

Data pipeline

Town representatives are likely to be proficient in editing spreadsheets. The Visual Budget application currently uses a pipeline that converts CSV files (created with Microsoft Excel) to nested JSON files used for computation.

A python script src/httpdocs/data/processing/processCSV.py converts a flat CSV file into the nested JSON structure listed above. A php script src/httpdocs/data/processing/update.php orchestrates the entire data update procedure.

For more information about CSV data formats or update procedures check docs/data.

Future upgrades

Decoupling town related assets (budget sections, links, logos, data..) from core visualization techniques
Changing data sections (eg. Replace 'revenues' with 'Town Departments') requires to manually change links (navbar.php), homepage data (home.php), initialization javascripts (avb.js) and update routines (processCSV.py, update.php). This process should be simplified to allow a simpler migration between different types of data.
Grid space. As of now, although each viz component implements a common interface, each visualization is tied to specific div (or html section), the creation of a 'grid' space that allows any visualization to be 'attached' to any area of the screen and would greatly enhance the customization and upgradability of the application.

Core Contributors

GoInvo (Design and Coding)

Lead Developer: Ivan David DiLernia
Creative Director: Juhan Sonin
Lead Designer: Roger Zhu

Town of Arlington (Data Collection and Testing)

Mike Bouton
Andrew Flanagan
Alan Jones
Annie LaCourt

License

Visual Town Budget is licensed under the Apache-2.0 open source license. You can find more information on the Apache-2.0 license at http://www.apache.org/licenses/LICENSE-2.0

goinvo / Visual-Town-Budget