Configuring the Enhanced Coordinate Map

When you create a new Enhanced Coordinate Map visualization, you can see a range of configuration options on the New visualization screen.

To view the available configuration options, select the Data tab and the Options tab.

Before you begin

The default tilemap server service that is used to display map tiles, tiles.siren.io, has limited features. Particularly in a production setting, it is recommended that you choose another tilemap provider.

You can use either a free tilemap provider, such as such as OpenStreetMap, or a paid provider, such as those listed at Switch2OSM. Or, you can build and serve your own tilemap tiles.

After you have set up the tilemap provider, configure the tilemap settings in the investigate.yml file.

For example, the settings for configuring OpenStreetMap are as follows:

tilemap:
  url: 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'
  options:
    attribution: '© [OpenStreetMap]("http://www.openstreetmap.org/copyright")'
    subdomains:
      - a

The Data tab

Metrics

The default metrics aggregation for a coordinate map is the Count aggregation, which calculates the total number of documents present in the aggregation.

If you select any of the following aggregations, you must also select a field from the dropdown menu that appears. For more information, see Y-axis aggregations.

  • Average

  • Sum

  • Min

  • Max

  • Unique Count: The total number of unique values present in the specified field within the aggregation.

Enter a string in the Custom Label field to change the display label.

The Advanced option opens a field where you can enter JSON input that acts on the field selected for the metrics aggregation. For example, the following JSON argument multiplies the number of employees by 1,000:

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

Buckets

Coordinate maps use the geohash aggregation. Select a field from the dropdown menu.

  • The Change precision on map zoom check box is selected by default. The Precision slider determines the granularity of the results displayed on the map. For more information about the area that is specified by each precision level, see the Elasticsearch documentation about the geohash grid aggregation.

Setting a higher precision level increases memory usage for the browser and also for the underlying Elasticsearch cluster.

  • The Place markers off grid (use geocentroid) check box is deselected by default. The markers are placed in the center of the geohash grid cell. Selecting this option generally provides a better representation of where the underlying documents are positioned within the geohash grid cell. For more information, see the Elasticsearch documentation.

Enabling this option will only work if there are no documents where the field contains an array of values.

As before, you can click Advanced to can enter JSON input.

The Options tab

Aggregation options

Layer Name

A customizable label to appear in the map’s layer view.

Map Collar Scale

A scaling factor for selecting which documents to use for the aggregation. A setting of 1 will select documents within the map extent, 2 will select documents within 2 times the size of the map extent, while a value of 0.9 will scale the selection to be 0.9 times the size of the map extent. The purpose of this feature is to avoid excessive fetches to Elasticsearch or slower performance due to too many results being fetched.

Map type

Select one of the following options from the box.

  • Scaled Circle Markers - Scale the size of the markers based on the metric aggregation’s value.

  • Shaded Circle Marker - Displays the markers with different shades based on the metric aggregation’s value.

  • Shaded Geohash Grid - Displays the rectangular cells of the geohash grid instead of circular markers, with different shades based on the metric aggregation’s value.

  • Heatmap - A heat map applies blurring to the circle markers and applies shading based on the amount of overlap. Heatmaps have the following options:

    • Radius: Sets the size of the individual heatmap dots.

    • Blur: Sets the amount of blurring for the heatmap dots.

    • Maximum zoom: Tilemaps in Siren Investigate support 18 zoom levels. This slider defines the maximum zoom level at which the heatmap dots appear at full intensity.

    • Minimum opacity: Sets the opacity cutoff for the dots.

    • Show Tooltip: Check this box to have a tooltip with the values for a given dot when the cursor is on that dot.

Tooltip Formatter

Select from the following options:

  • Metric Value - A tooltip containing the coordinates and the metric value specified on the Data tab

  • Visualization - The option to add a Visualization as a tooltip. The contents of the visualization will be an aggregation based on the aggregation the tool tip is being applied to.

Close tooltip on mouseout

When mouse is hovered over aggregation a tooltip will appear. When the mouse is moved away from aggregation, the tool tip will disappear if this box is checked; it will remain if unchecked.

Legend Scale

Configuration settings for how the aggregation is displayed on legend +

  • Dynamic - Linear - Each class in the legend has the same size (e.g. values from 0 to 16 and 4 classes, each class has a size of 4)

  • Dynamic - Uneven - Each class will have the same number of documents inside, useful when data is unevenly distributed between the maximum and minimum ranges

  • Static - Manual specification of colors, values and number of classes for the legend scale

Map Options

Scroll Wheel Zoom

When checked, it is possible to use the mouse scroll wheel to toggle map zoom level. (+ and - work toggle zoom regardless of this)

Desaturate map tiles

Desaturates the map’s color to make the markers stand out more clearly.

Synchronize map

Synchronize the map canvas of this visualization with all other visualizations present on a dashboard that also have this option selected

Auto-fit map to data

Automatic zoom to include all Aggregations when filters are altered. This includes time filter. Disabled when panning or zooming.

WMS compliant map server

Check this box to enable the use of a third-party mapping service that complies with the Web Map Service (WMS) standard. Specify the following elements: +

  • WMS url: The URL for the WMS map service.

  • WMS layers: A comma-separated list of the layers to use in this visualization. Each map server provides its own list of layers.

  • WMS version: The WMS version used by this map service.

  • WMS format: The image format used by this map service. The two most common formats are image/png and image/jpeg.

  • WMS attribution: An optional, user-defined string that identifies the map source. Maps display the attribution string in the lower right corner.

  • WMS styles: A comma-separated list of the styles to use in this visualization. Each map server provides its own styling options.

If you need to display custom layers for the Region Map visualization, a geospatial server may provide the solution. For more information, see Configuring GeoServer.
Tooltip action

For larger datasets, tooltips on hover can make it difficult to use the map. The option below will be applied to the Aggregation layer and point layers types from Point of interest, Stored Layer or WFS sources.

  • Show tooltips on hover: The default behavior, tooltips will be displayed when features on the map are hovered.

  • Show tooltips on click: Tooltips will be displayed when features are clicked.

Map Overlays

Point of Interest layers

Add any entity table with a geo_point or geo_shape field as a marker or polygon layer:

  • You can draw geo_point type POI layers by using the Marker Clustering process.

  • You can create geo_shape type POI layers to enable viewing, pop-ups, and to create geo-filters. Geo-filters are applied to aggregations, other POI layers and other visualizations when on the dashboards (see Apply filters below).

    To render a geo_shape field on the map, it is required for an index to also have a geo_point field type.

Configuration options for POI layers:

  • Entity table - Select an entity table from the dropdown menu. Note: The entity table must have a geo point field.

  • Geospatial Field -  Select a geo point field within the entity table.

  • Styling

    • For geo_point - Set the size of the marker to appear for each document

    • For geo_shape - Set color in Hex value form

  • Popup Content - Selecting fields to appear on popup tooltip

  • Limit - The number of markers that are allowed to appear for this Point of Interest layer. The default is 100

  • Apply Filters - Whether or not to include filters from Selection tools or geo_shape type POI layers, a different visualization on the same dashboard or filters from other dashboards applied through the relational navigator.

    You can also create a POI layer when you are in the dashboard view. Simply drag and drop a dashboard that has an entity table with a geo_point field. If the entity table has multiple spatial fields, a modal will appear prompting you to select one.

    The filters from the other dashboard will be applied and can be viewed by hovering over the filter icon in the layer control. Drag and drop layers will not be saved and can be removed at any point by clicking the Remove Layer button in the layer control panel.

    image

WMS layers

Configuration options for the use of a third-party mapping service that complies with the Web Map Service standard. Multiple layers (or layer groups) can be loaded. Many third-party mapping services are available, and some of these are described in Configuring GeoServer.

  • Layer Name - A customizable label to appear in the map’s layer view (image)

  • Url - The URL for the WMS map service

  • WMS Layers - This is where layers or layer groups (see the GeoServer definition) can be specified from a WMS server. There are two options:

    • If you have added a URL to a CORS-enabled WMS server - Investigate will internally run a WMS getCapabilities request and will populate a list of layers that can be added by clicking ①. These can be ordered, by clicking and dragging ② as below. The layer at the top of the list is drawn furthest in the background.

      image

    • If your URL is not a CORS-enabled WMS server - The UI will remain the same. You can order your layers, separated by a comma. The first layer you specify will be drawn the furthest in the background.

      image

      You can still see the available layers for the WMS by running a getCapabilities request. Below is an example from a local instance of GeoServer:

      http://localhost:8080/geoserver/wms?SERVICE=WMS&REQUEST=GetCapabilities

  • CQL Filter - Allows you to query your spatial layers as parameters in WMS requests

  • Min Zoom Level - The minimum zoom level that the WMS request will be visible

  • Max Zoom Level - The maximum zoom level that the WMS request will be visible

  • Max Features - The maximum number of features, up to a maximum of 10,000, to be rendered per tile from the specified layer(s). Note - Max features can be configured in the WMS, which overrides this setting

  • Styles - A comma-separated list of the styles for your layer. If you have access to the WMS server, you can assign defaults for these and it is possible for this field to be left blank. Otherwise, each map server provides its own styling options

  • Output Format - The image format to be returned by the WMS. The two most common formats are image/png and image/jpeg. Default is image/png

  • Non Tiled - The option to send the WMS request as one complete image to fit the map extent, or to send it in multiple tiles

  • Visible On Load - Check this option to draw the layer when the visualization is loaded. Note - this will be over ridden if a user saves their dashboard state

  • Elasticsearch WMS Options - Configuration options for WMS request

    • Aggregation - Allows for the customization of geohash request from WMS using elasticgeo. Example of aggregation WMS request using the company index in Siren’s classic demo (“location” has a Geo_Point field type): { "agg": { "geohash_grid": { "field": "location" } } }

    • Sync Filters - When checked, the WMS response includes the filters made using Selection tools, visualizations in the same and visualizations from other dashboards.

WFS layers

This allows for point, linestring (including multi-linestring) and polygon (including multi-polygon) types to be rendered onto the Enhanced Coordinate Map. To create a geo-filter, click a polygon.

Point layers from WFS sources will not cluster. Instead, single document features are drawn.

See the WMS Layer section above for descriptions of Layer Name, Url and WFS Layers fields.

For information about setting up a WFS server, see Configuring GeoServer.

The following additional fields are specific to editing WFS layers:

  • Styling - Set color in Hex value form and specify the size of the marker to display on map

  • Output Format - The format that your spatial server is capable of responding with. The format for ArcGis Server is GeoJSON, and the format for GeoServer is JSON.

  • Popup Content - To configure a pop-up tooltip, create a comma-separated list of fields in the properties object of your GeoJSON features. For example, the parameter City_name,Pop_est adds the city name and the estimated population fields to each feature that is added to the map. Note: This parameter is case-sensitive.

Vector Basemap Layers

This section allows to add Vector Basemap Layers hosted on Esri ArcGIS to the visualization.

The following field are required for each Vector Basemap Layer:

  • Layer name - The label of the layer that will be displayed in the layer list inside the visualization.

  • Key - The Item ID of the Vector Basemap Layer on ArcGIS.

  • Api Key - The API Key to include in all the requests to ArcGIS.

Vector Tile layers

This section allows to add Vector Tile Layers hosted on Esri ArcGIS to the visualization.

The following fields are required for each Vector Tile Layer:

  • Layer Name - The label of the layer that will be displayed in the layer list inside the visualization.

  • Key - The Item ID of the Vector Tile Layer on ArcGIS.

  • Api Key - The API Key to include in all the requests to ArcGIS.

The following fields are optional:

  • Portal Url - Can be used to set an alternative ArcGIS URL when retrieving tiles that are not hosted on ArcGIS Online.

  • Use Custom Url or Style Path - Select this option when the paths to the layer or style differ from what is declared on ArcGIS.

  • Base Url - The first part of the URL to a custom stylesheet.

  • Style Path - The path to the style following the item ID.

When Base Url and Style Path are set, the stylesheet URL will be computed by concatenating Base Url, Key and Style path.

The order in which Vector Tile Layers render can be ordered by clicking the drag icon in the top right of each layer configuration

Stored Layer Configuration

When a new Enhanced Coordinate Map visualization is created, the Stored Layer Configuration is populated with a default object:

Default stored layers configuration

For more information, see Working with layers.

Feature-level configurations

If any of the icon, size, color, or popupField parameters are specified in a document’s properties object, this field will take precedence. This can be useful if you want to assign different icons within the same layer. For more information, see the detailed example of a stored layer configuration.

After changing options, click Apply changes to update your visualization, or Discard changes to keep your visualization in its current state.

For more information about Geo Centroid and Geohash aggregations, as well as others, see Understanding X- and Y-axis aggregations.