Region Map

Region maps are choropleth maps in which vector polygons are colored using a gradient. Higher-intensity colors indicate larger values, and lower-intensity colors indicate smaller values.

regionmap

Configuration

To create a region map, you configure an inner join that joins the result of an Elasticsearch terms aggregation and a reference vector file based on a shared key.

You can add your own custom polygon vector layers by using the regionmap setting in the Investigate.yml file. Then, after restarting Siren Investigate, you configure the inner join between your Elasticsearch index and your polygon vector layer.

You can configure a custom GeoJSON. For more information, see regionmap in Configuring Siren Investigate.

If you need to display custom layers for the Region Map visualization, a geospatial server may provide the solution. See Configuring GeoServer.

The Data Tab

Metric values

To specify the metric type that will be used for the choropleth, select any of the supported Metric or Sibling Pipeline Aggregations.

  • Aggregation - A variety of techniques can be used to summarize or aggregate your Date, String, Numerical or Geo data:

    • Metric values:

      • Count - The count aggregation returns a raw count of the elements in the selected index pattern.

      • Average - This aggregation returns the average of a numeric field. Select a field from the drop-down menu.

      • Sum - The sum aggregation returns the total sum of a numeric field. Select a field from the drop-down menu.

      • Min - The min aggregation returns the minimum value of a numeric field. Select a field from the drop-down menu.

      • Max - The max aggregation returns the maximum value of a numeric field. Select a field from the drop-down menu.

      • Unique Count - The cardinality aggregation returns the number of unique values in a field. Select a field from the drop-down menu.

      • Standard Deviation - The extended stats aggregation returns the standard deviation of data in a numeric field. Select a field from the drop-down menu.

      • Top Hit - The top hits aggregation returns one or more of the top values from a specific field in your documents. Select a field from the drop-down menu, how you want to sort the documents, and choose the top fields and how many values should be returned.

    • Sibling Pipeline Aggregations - You must provide a metric for which to calculate the sibling aggregation. You also need to provide a bucket aggregation, which will define the buckets on which the sibling aggregation will run.

      • Average Bucket - The avg bucket calculates the (mean) average value of a specified metric in a sibling aggregation.

      • Sum Bucket - The sum bucket calculates the sum of values of a specified metric in a sibling aggregation.

      • Min Bucket - The min bucket calculates the minimum value of a specified metric in a sibling aggregation.

      • Max Bucket - The max bucket calculates the maximum value of a specified metric in a sibling aggregation.

    • Custom label- The user-specified label that will be used in the tooltip.

  • Advanced mapping features

  • JSON Input - A text field where you can add specific JSON-formatted properties to merge with the aggregation definition. Below is a viable JSON input for the companies index in metrics on the data tab. Note: Count cannot be included as it is not an aggregation.

    {"script" : "doc['number_of_employees'].value * 1000"}

The entire request, including the Advanced settings, can be viewed by selecting the upward arrow icon in the bottom-left of the map canvas and selecting Request from the dropdown menu.

Buckets

The Shape field is where the parameters of the join between the polygon vector map and the Elasticsearch index are specified.

  • Aggregation - Specify the Terms aggregation. The term is the key that is used to join the results to the vector data on the map.

  • Field- Specify the Elasticsearch document field to be used for joining to the polygon vector layer.

  • Order By - The field or metric to order the Elasticsearch query by.

  • Order - Specify whether to sort the Order By field in ascending or descending order.

  • Size - Specify the number of polygons that should be rendered on the map. This is inclusive of the Group other values in separate bucket and Show for missing values options below.

  • Group other values in separate bucket - An option to represent documents not displayed in the choropleth. These may not be displayed due to the Size specification.

    • Label for other bucket - If you would like the other values to appear on the map, specify a valid Field value that isn’t already displayed on the choropleth.

  • Show for missing values - The option to show documents missing a value for the specified Field.

    • Label for missing values - If you would like the other values to appear on the map, specify a valid Field value that isn’t already displayed on the choropleth.

Advanced mapping features

You can use the Exclude and Include fields to specify the features of the Region map layer to exclude or include in the resulting choropleth.

Both fields use Regular Expression Format syntax. For example, using World Countries (one of Siren’s default layers, which can be selected in the Options tab), joined on companies country code, GBR in the include field would just display Great Britain on the resulting choropleth. Similarly, USA|CAN in the exclude field would remove USA and Canada from the resulting choropleth.

JSON input - You have the option to add or edit the attributes of the Terms field of the Elasticsearch request body. For example, to specify the minimum number of documents for the aggregation to be displayed on the choropleth, you could enter the following syntax:

{ "min_doc_count": 60 }

The entire request, including the advanced settings, can be viewed by selecting the upward arrow icon in the bottom left of the map canvas and selecting request from the drop-down menu.

Options

Layer settings

  • Vector map: select from a list of vector maps. This list includes the maps that are hosted by the Elastic Maps Service, as well as your self-hosted layers that are configured in the config/investigate.yml file. To learn more about how to configure Siren Investigate to make self-hosted layers available, see the regionmap configuration settings.

  • Join field: this is the property from the selected vector map that will be used to join on the terms in your terms-aggregation. When terms cannot be joined to any of the shapes in the vector layer because there is no exact match in the vector layer, Siren Investigate will display a warning. To turn off these warnings, go to Management → Advanced Settings and set the visualization:regionmap:showWarnings parameter to false.

Style settings

  • Color Schema: the color range that is used to color the polygons.

Basic settings

  • Legend Position: the location on the screen where the legend will be rendered.

  • Show Tooltip: indicates whether a tool tip should be displayed when hovering over a shape.