The Choropleth lets you compare values by geographic region.

Features Quantity Notes
Required Dimensions 1 Geographic dimension of Countries, States in the United States, or Counties in the United States.
Required Measures 1-2 Measure 1 = color.

Choropleth comes from the Greek choros (area) and pleth (value). Immerse colors the map regions based on the measure. You can compare colors from your chosen palette to understand the relative value of one region to another.

Use a Choropleth to compare aggregate values across regions. Choropleths are useful for spotting outliers, but are not intended to provide detail on the values within a region. (For detailed, point-level geographic information, consider using a Pointmap.)

When you assign a map overlay, the region names in the dataset column you select must match the names in the overlay. The column you choose can spell out the name of the region, or use a standard abbreviation, but cannot use both.

For countries, you can use a dataset column with the two- or three-character abbreviation, or one that spells out the full name. See Country Names and Abbreviations.

For US states, you can choose a column with either the full name or the two character abbreviation. See United States State Abbreviations.

The list of supported US county names is provided in the file United States Counties.

Choropleth Example

Create a new Choropleth. Choose a Data Source. This example graphs employment statistics for all 50 United States for the years 1980-2015. The data is available at the University of Kentucky website.

Set the Dimension to state_name and the Color measure to average Employment. Set GEO JSON JOIN to US State to overlay the defined geojson shapes onto the map.


Choropleth Geo Example

The following example uses flights data to display average flight departure delay time, by state.

  1. In a new or existing Dashboard, create a new Choropleth chart.
  2. Choose the Data Source. Here, the flights database is selected.
  3. Set the Dimension to specify the column in the table used for the geojoin. If only one valid geospatial column exists, it is autoselected by default. Here, the origin_state dimension is selected. Currently, only one dimension is supported.
  4. Specify the column used for the positions of the shapes on the map in the Geo measure. The Geo measure includes columns from both the data source and any GeoJoin table. Options might not appear in the selector until a GeoJoin has been specified. If only one column is valid for the selector, that column is automatically selected. Only POLYGON and MULTIPOLYGON types are supported.
  5. Set the Color measure (optional). Only numerical and time columns are supported.
  6. Select the Geo Join data source that corresponds with the geo-related data in the dimension field. Here, with origin_state selected in the dimension field, mapd_states is selected as the Geo Join data source. If the primary datasource has geospatial data, the Geo Join is not required.
  7. Select the column to use for the join; in this case, abbr.