General-purpose static data mapping

This module drives all data-driven choropleth maps not covered under any of the other Map Center modules. It is designed to display category-based and continuous value-based data for any of the available map types, and it includes a variety of useful hooks and overrides in order to be more useful for creating variations on these types of maps relatively quickly.

This module lives in lib/map_center/modules/static_maps.js, and the current data sets used with it live in lib/map_center/modules/static_maps_data/ by convention.

Operation

A page making use of this module must include one additional JavaScript file containing the data to display. As described above, this file should live in lib/map_center/modules/static_maps_data/. That file should define one global variable, nhmcStatic, with a format described below.

Depending on whether the page is intended to show one or multiple data sets, the user may have one or two tabs available; the one that is always available allows the user to select a specific map view, and the one that is available in the case of multiple data sets allows the user to select a specific data set to view.

In either case, the states or counties on the map are colored according to the data provided. The sidebar in this module shows the meaning of each color used on the map, and the tooltips for each state or county shows the specific data value that caused that state or county to receive the color it has.

Configuration options

There are three major configuration options that exist outside the data file itself, all changeable via global variables:

  • nhmcStaticBreakFormatter is a function used for rendering the sidebar entries for each color shown on the map when the data set shown uses continuous values. It accepts six arguments:

    • thisBreak is the break value for this particular sidebar entry.
    • prevBreak is either null or the break value for the sidebar entry before this one.
    • isLastBreak lets the formatter function know this is the last break value to be included in the sidebar.
    • breakPrefix is a string meant to be displayed before a break value. This often is used for currency signs.
    • breakSuffix is a string meant to be displayed after a break value. This often is used for units (points, percent, etc.).
    • breakDecimals is an integer requesting that a break value be rounded to a specific number of decimal places; for example, small dollar amounts might have breakDecimals set to 2 to properly show a number of cents.

    By default, this function renders the sidebar as a list of ranges from one break to the next. This function will execute every time the map view is changed.

  • nhmcStaticFlyouts is an object that determines whether tooltips should be rendered as flyouts. No specific properties need to be defined in this object for flyouts to be enabled; the object just needs to exist. By convention, though, to enable flyouts, the following value is used:

    var nhmcStaticFlyouts = {
        enabled: true
    };
    

    Other properties that get merged with those provided in this object are:

    • corner was intended to be a string value setting a position for the flyout (or null if flyouts should not be used), but now positioning is entirely handled in CSS, so this option should be considered deprecated.
    • strokeHighlight is a hexadecimal color code for the color used to outline the state or county targeted by the tooltip.
    • width is a number stating the number of pixels wide to render the flyout. (This was here in order to support certain animations.) Positioning and formatting are entirely handled in CSS now, so this option should be considered deprecated.
  • nhmcStaticTooltipFormatter is a function used for rendering the content of the tooltips corresponding to each state or county on the map. It accepts five arguments:

    • thisFIPS is a county FIPS code if the tooltip should show data for a county or an empty string if it should show data for a state.
    • thisState is a full state name for the area for which the tooltip should show data. This is included whether the area is a county or a state (since counties do exist within states); therefore, nhmcStaticTooltipFormatter should check the values of the thisFIPS and thisCounty arguments to determine the type of area being touched or hovered over.
    • thisCounty is a full county name if the tooltip should show data for a county or an empty string if it should show data for a state.
    • countyOnly is a Boolean value that, if true, requests that the tooltip show just the name of the county being touched or hovered over as opposed to the name of the county and the name of that county’s state (e.g., Arlington County or Arlington County, Virginia if countyOnly is true or false respectively).
    • currentData is the full data set being displayed (as described in Data structure below).

    This function will execute every time a tooltip is created, but not while that tooltip simply updates its position within the same state or county.

One additional configuration option exists:

  • nhmcStaticDataIndex is an integer with the same interpretation as the data_index parameter in the fragment identifier. It will be ignored if the data_index fragment parameter is set.

Data structure

Two types of data sets can be displayed in a map using this module:

  • Category-based data sets place states and counties in any of a number of categories and color areas that are in the same category with the same color.
  • Continuous value-based data set assign a value to each state and/or county and color those areas based on which of a number of ranges of values happen to include the areas’ values.

As described in Operation above, any page using this module must include a JavaScript file (or <script> block) that defines a variable named nhmcStatic. For a page that uses only one data set, nhmcStatic should be an object with the properties listed in either Categories or Continuous values below; for a page that uses multiple data sets, nhmcStatic should be an array of such objects.

Note

In both of the description sections below, the term “area name” refers to FIPS codes for counties and full state names for states.

Categories

A data set object for category-based data must contain the following three properties:

  • categories is an array of strings containing the names of the categories to use in the data set, listed in the order they should be displayed in the sidebar.
  • colors is an object with category names (as listed in categories) as keys and hexadecimal color codes as values. These colors will be used to fill areas that fall in each category and will be shown next to each category’s name in the sidebar.
  • areaLists is an object with category names (as listed in categories) as keys and arrays of area names as values. Each array should contain the names of all states and the FIPS codes of all counties that fall in that category. Any states or counties that are unlisted in all area lists will remain their default fill color as defined in nhmc.config.defaultAttributes.

See also

For an example of a category-based data set, check out the Patchwork Nation categories map. The page source is located at patchwork_types.html, and the data set source is located at lib/map_center/modules/static_maps_data/patchwork_types.js.

Continuous values

A data set object for continuous value-based data must contain the following three properties:

  • breaks is an array of numbers that represent the greatest value in each group of areas that should be colored identically. The last value in breaks should be at least as great as the greatest value in the data set and may be greater. (The maximum possible value is a good default, such as 100 for percentages.)

    For example, if you are mapping a data set with values ranging from 0 to 100 and want to split it up into five equally spaced groups of 20 each:

    "breaks": [20, 40, 60, 80, 100]
    

    This will define groups of:

    • 0 to 20 (rendered by default in the sidebar as ≤20)
    • 20 to 40
    • 40 to 60
    • 60 to 80
    • 80 to 100 (rendered by default in the sidebar as >80)
  • colors is an array of hexadecimal color codes in the same order as in breaks. Continuing the previous example:

    "colors": ["#000000", "#ffffff", "#ff0000", "#00ff00", "#0000ff"]
    

    would assign the color #ff0000 to the 40 to 60 group.

  • areas is an object with area names as keys and data points (numbers that fall in the ranges defined in breaks) as values. Continuing the previous example:

    "areas": {
        "Missouri": 75
    }
    

    would fill the state of Missouri with #00ff00 (since it falls in the 60 to 80 range).

It also may contain any combination of the following five properties, including none of them or all of them:

  • decimalPlaces is a number of decimal places to which the breaks and data values should be rounded when they’re displayed. This defaults to zero, which rounds everything to the nearest integer.
  • prefix is a string (defaulting to the empty string) that is prepended to the breaks and data values when they’re displayed. This is primarily used for currency indicators such as the $ before dollar amounts.
  • suffix is a string (defaulting to the empty string) that is appended to the breaks and data values when they’re displayed. This is primarily used for units, including percents.
  • seriesName is a string (defaulting to undefined) which, if defined, is used to populate any element with the class static_map_name.
  • sidebarTitle is a string (defaulting to undefined) which, if defined, is used to populate the element with the ID sidebar_title.

See also

For an example of a continuous value-based data set, check out the unemployment rate map. The page source is located at unemployment.html, and the data set source is located at lib/map_center/modules/static_maps_data/unemployment.js.

Fragment identifier

This module makes use of two key-value pairs in the fragment identifier via nhmc.ctrl.hashParams:

  • data_index, if provided, should be set to the index of the data set to display first. This only makes sense if nhmcStatic is defined as an array of objects.
  • map_view, if provided, should be set to the name of the map view to display first. The fragment identifier will update as the map view is changed.

Project Versions

Table Of Contents

Previous topic

Non-primary election results

Next topic

User interface

This Page