Progress® Telerik® Reporting R2 2017

How to: Setup a Choropleth Using the Map Wizard

In this how-to article we will show you how to use the Standalone Report Designer to create a Choropleth map. The map will show the world population for each country, coloring its area depending on the population density value. We will use a CSV Data Source for the analytical data and a ESRI Shapefile for the spatial data. The analytical data is obtained from the following Wikipedia article: List of sovereign states and dependent territories by population density.

Creating a simple choropleth map using CSV data source and a Shapefile

  1. Start the Map Wizard:

    • If you create a new report, select the Choropleth Wizard icon from the Available Templates page.

      Choropleth How To Simple Select Choropleth Wizard
    • If you want to add the Map item to an existing report, you have to select the Choropleth item from the Insert menu. This will bring up the Choropleth Wizard which will guide you through the creation process.

  2. Add new CSV Data Source and name it populationData. This data source will hold the information about the countries, their area, population and density along with some additional data.

    1. Although you can copy the data directly from the Wikipedia page mentioned above, for your convenience we have prepared a CSV file that you can pass to the CSV data source.

      Download the PopulationData.csv file , save it locally and insert its path into the Select a file to import textbox or paste it in the Enter CSV as text tab.

    2. The file uses semicolon (;) as a separator, but the comma (,) is used as thousand separator. Thus tick the semicolon checkbox and untick the comma checkbox on the Configure the separators page.

    3. Press Next until you get to the CSV Headers page. Note that the CSV file has headers, so you should check the The CSV has headers checkbox.

    4. On the Map columns to type page set the column types to match the actual data they represent, as shown below.

      Choropleth How To Simple CSV Map Columns To Type
    5. When you click Parse CSV... on the next page, you should see the result of the parsed file.

      Click Finish when you are ready.

  3. In the Available data sources list you should see the datasource you've already created. Select it and click Next.

  4. In the next page you have to select the source that will provide the spatial data to your choropleth. In this example we will use a Shapefile which can be downloaded from the following link: ShapefileWorld.zip.

    • Extract the contents of the ZIP archive in a directory of your choice.

    • Select the Binary file in ESRI Shapefile format radiobutton.

    • Browse to the directory where your Shapefile is placed or paste the path to the file in the textbox.

    • As soon as the path to the Shapefile is set, you can create the relations between the fields in the analytical (CSV) data set and the fields from the world.dbf file, which is part of the Shapefile bundle.

      Click the New button on the relations control. A new row will appear. From the Analytical Field column select Fields.Country. Match it with the Fields.CNTRY_NAME field from the Shapefile Field column.

    Your Choose a spatial data source page should look like the one shown below:

    Choropleth How To Simple Choose Spatial Data Source

    Once the mandatory fields are set up, the Next button will get enabled and you can go to the next page.

  5. On the following page you will set the fields that are specific to the choropleth map. Please note that in the Available fields you will see the the fields from both analytical and spatial data sets.

    1. Select the Density (pop./km2) field and drag it to Color data field: box, where it will be transformed to Sum([Density (pop./km2)]). You can omit the aggregate operator, since every country is on a separate row in the data set, and the Sum operator will aggregate only one row.

    2. Select EqualDistribution as a Range grouping method, which will distribute the data points evenly in groups/clusters.

    3. Set a proper value to the Colors count property, which will define in how many clusters the color data values will be distributed. For this example we picked 8.

    4. Set appropriate colors for the Start color and End color properties. They will be used to create a GradientPalette, which will distribute graded colors among the data points. The data points that have lower color values will receive colors from the palette start, and vice versa - the data points with the higher color values will receive colors from the palette end.

    5. When you are done, your Choropleth setup page should look like this:

      Choropleth How To Simple Choropleth Setup
  6. When you click the Finish button, the map will display the choropleth map. After adding some formatting to the title and the legend, it should look like the one shown here:

    Choropleth How To Simple Layout 1

Additional information

  • You will notice that some areas (countries) on the map are transparent. These areas represent shapes that have no match with the analytical data set fields. The choropleth displays all the shapes that are available in the spatial data set, but the data points are created only when the field from the analytical data set is matched with a field from the spatial data, using the MapRelationPairCollection.

    In our example we use a Shapefile for all the countries in the world, but we have analytical data for the 100 most populated countries. This means that some of the shapes will never be matched with the analytical data set and therefore will not be colored, because they don't have a valid population value.

    Another reason for having transparent areas is simple mismatching the fields that are used in the Relation Pairs. Take a look at the following screenshot, showing a part of Africa:

    Choropleth How To Simple Layout 2

    For this screenshot we made the data point labels visible and set the following expression to them: = Format('{0} {1}', Fields.CNTRY_NAME, Sum(Fields.[Density (pop./km2)])). Note that in the expression we used the fields from both spatial and analytical data set. As a result we see that the choropleth displays Congo, DRC as a country name, but does not display a valid population value for it. Since we bind the countries by name, the engine tries to find a country named Congo, DRC in the analytical data set, but fails, because in our CSV data source this country is named Democratic Republic of the Congo (Pos. 79). If you edit the CSV data and rename the country to Congo, DRC, you will see that the both records are matched, the country area is now colored and a valid population value (29.6) is displayed.

In this example we demonstrated how to create a simple choropleth map using data from analytical and spatial data sources without writing a single line of code.

You can download this example report as a .trdx definition from the following link: How to: Setup а Choropleth using the Map Wizard.