Setup and Configuration

You can also watch a screencast presentation about map configuration conducted by Stamen De# August 2015.

Before configuring a new city installation, the city and Stamen will have determined the hosting environment, forked this repository for a specific city installation, created a CartoDB account and loaded initial data there, and made any needed adjustments to header image and background color.

Once that's done, making changes to the overall application setup is quite simple and can be done by anyone with basic ability to use a text editor and maintain formatting.

Each city has an installation file in cityenergy/src/cities/. Below is a simplified example for Philadelphia. Each instance of ellipses (...) means that more of those items can and likely will appear.

The first section sets the city name, URL, basemap tiles, default zoom location/level, source CartoDB account. These would all be optimized at initial setup for each city but are unlikely to need to be changed afterward:

    "url_name": "philadelphia",
    "name": "Philadelphia",

    "tileSource": "http://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}.png",
    "center": [...],
    "zoom": 11,
    "cartoDbUser": "cityenergyproject",
    "property_id": "portfolio_manager_id",
    "property_name": "property_name",
    "building_type": "primary_property_type___epa_calculated",

The next sections are where most of the detail work will happen.

First, we can set the popup fields that appear when you click on a building on the map:

    "popup_fields": [
      {"field": "property_name", "label": ""},
      {"field": "address", "label": "Address: "},
      {"field": "primary_property_type___epa_calculated", "label": "Building Type: "},
      {"field": "year_built", "label": "Year Built: "},
      {"field": "property_floor_area_buildings_and_parking_ft", "label": "Square Feet: "},
      {"field": "energy_star_score", "label": "Energy Star Score: "},
      {"field": "site_eui_kbtu_ft", "label":"Site Energy Use: "},
      {"field": "source_eui_kbtu_ft", "label":"Source Energy Use: "},
      {"field": "total_ghg_emissions_mtco2e", "label":"GHG Emissions: "}
    ],

Next, we can set the filter fields, where each block here defines either a numeric filter field on the left or a category filter menu in the top bar:

  "map_layers": [
      {
          "title": "Energy Star Score",
          "field_name": "energy_star_score",
          "display_type": "range",
          "section": "Energy Efficiency",
          "range_slice_count": 30,
          "color_range": ["#F77156","#DAC04D","#6BB0A5"],
          "description": "Measure of a building's energy performance relative to similar properties nationwide on a scale from 1-100. A score of 50 is the median. Buildings scoring 75 or higher are considered high performing."
      },
      {
          "title": "Energy Use per Sq Ft",
          "field_name": "site_eui_kbtu_ft",
          "display_type": "range",
          "section": "Energy Efficiency",
          "range_slice_count": 30,
          "filter_range": {"max" : 400},
          "color_range": ["#6BB0A5","#DAC04D","#F77156"],
          "description": "Site Energy divided by property size in square feet",
          "unit": "kbtu/ft²"
      },
      ...
  ],

The two items above are numeric fields with display_type of range. These create and set up the histogram filters along the left of the map.

Here's an example of the configuration for the category filters that can be added to the top bar:

        {
            "title": "Building Type",
            "field_name": "primary_property_type___epa_calculated",
            "display_type": "category",
            "section": "Building Info",
            "categories_to_display": 9
        }

Finally, the one section of the configuration that will need ongoing maintenance. Here, when a new year of data has been loaded into CartoDB, we need to specify the years, table name, and default layer. New elements here will automatically appear in the year selector in the top right of the interface.

    "years": {
        "2014": {
            "table_name": "philadelphia_propertiesreported_csv",
            "default_layer": "energy_star_score"
        },
        ...
    }
}

Once you edit the file, we recommend checking the formatting with a service such as http://jsonlint.com/ to confirm that all the commas and brackets are in their correct spots.

Uploading Data to CartoDB

You'll need one dataset to start with, and then one for each year of building data you have available, all with the same set of fields from year to year. The map platform is designed to use CartoDB as its platform, and most installs will work just fine on the free tier until there are a very large number of buildings in the system.

CartoDB has easy and well-documented tools for uploading data, but there are a couple of important notes to keep in mind:

1. Your source file needs to be a well-formatted CSV, which means the first row has the field names, and each building gets one and only one row. No extra headers, footers, or other bits. Excel does fine at saving in CSV, but a person needs to make ensure one-header, one-row-per-record, and nothing-else.

2. Using find/replace in Excel or Google Sheets (or other spreadsheet software), remove all "NA" or "N/A" or other standins from numeric columns. Leave them blanks. As long as there are no strings in numeric columns, CartoDB will do a good job of automatically sensing which columns are numbers and which text.

3. Each time you upload a new dataset, you need to geocode the addresses to assign latitude and longitude to them. Here's the basic documentation on CartoDB's geocoding. Depending on the size of your dataset, you may need to contact CartoDB to purchase geocoding credits. (As of this writing, a free CartoDB account includes 100 geocoding credits per month.) If your dataset doesn't include city or state, that's OK, but make sure you add those as static text in the geocoding menu, which looks like this:

4. If you have a paid CartoDB account, make sure the table you uploaded is public. Learn how to do that here. Free accounts allow only public datasets, so you don't need to worry about permissions with free accounts.

5. Now that the data is available in CartoDB, all that's left is to enable the web map to see the new data. Back in Github, add a new element to the years section at the end of the config file. Copying, pasting, and editing the first year's layer is the easiest way to do that, so it looks like this:

    "years": {
        "2014": {
            "table_name": "philadelphia_propertiesreported_csv",
            "default_layer": "energy_star_score"
        },
        "2015": {
            "table_name": "philadelphia_propertiesreported_2015_csv",
            "default_layer": "energy_star_score"
        }
    }

As mentioned above, any time you edit the JSON config file, it's a good idea to paste it into a validator like http://jsonlint.com, unless the editor you're using has built-in syntax checking (usually only true for web developers).