Siren Platform User Guide

Enhanced Coordinate Map

The Enhanced Coordinate Map visualization (beta) displays a geographic area overlaid with circles keyed to the data determined by the buckets you specify.

Note

By default, Siren Investigate uses a demonstration Siren tilemap server Open Street Maps service to display map tiles. This server has limited features and you should update the tilemap settings to another tilemap provider that you have configured, especially in a production setting. To use other tile service providers, configure the tilemap settings in investigate.yml.

Configuration
Configuring external tilemap providers

You can use existing free or paid tilemap providers or build and serve your own tilemap tiles.

After you have setup your own tilemap provider, configure these settings in investigate.yml to have map visualizations render these tiles.

For example, to use an OpenStreetMap default provider, the configuration YAML settings would look like:

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. You can select any of the following aggregations as the metrics aggregation:

  • Count (total number of documents present in the aggregation)

  • Average

  • Sum

  • Min

  • Max

  • Unique Count (total number of unique values present in the specified field within the aggregation)

Note

When you select any of the above aggregations except Count, a Field dropdown is displayed from which you can select a field that is valid for the selected aggregation).

For more information, see Y-axis aggregations.

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

Clicking Advanced opens a field where you can enter a viable JSON input that acts on the field selected for the metrics aggregation. For example, the following JSON 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, typically coordinates, from the box.

  • The Change precision on map zoom check box is selected by default. Clear the check box to switch off this behavior. The Precision slider determines the granularity of the results displayed on the map. See the documentation for the geohash grid aggregation for details on the area specified by each precision level.

Note

Higher precision increases memory usage for the browser displaying Siren Investigate as well as for the underlying Elasticsearch cluster.

  • The place markers off grid (use geocentroid) box is checked by default. When this box is checked, the markers are placed in the center of all the documents in that bucket. When cleared, the markers are placed in the center of the geohash grid cell. Leaving this checked generally results in a more accurate visualization.

You can customize your visualization. For more information, see Customizing aggregations.

The Options Tab
Aggregation options
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 ticked; it will remain if unticked.

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

Geo shape filtering Option

If your index also has a geo_shape field, the Geo_shape filtering option will appear on the options tab:

geoshape.png

Tick the Filter by geo_shape field to include the specified geo_shape field as a filter for all point-of-interest (POI) layers. Note - the POI layers added must contain the geo_shape field name as the filtering geo_shape field.

Note

A valid index for enhanced coordinate map must also have a geo_point type field.

Map Options
Scroll Wheel Zoom

When ticked, 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.

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.

Note

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

Map Overlays
Point of Interest layers

Add any elasticsearch index with a geo_point or geo_shape field as a marker or polygons:

  • Geo_point type POI layers can be viewed and can include popups activated and deactivated on mouseover and mouseout.

  • Geo_shape type POI layers are suitable for viewing, popups and creating geo-filters which are applied to aggregations, other POI layers and other visualizations when on the dashboards (see Apply filters below).

POI_button.png

Configuration options for POI layers:

  • Saved Search - Select any elasticsearch index from the dropdown menu. Note - will need a geo point field

  • Geospatial Field -  Select a geo point field within the Saved Search

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

  • 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 relational Navigator

WMS_button.png

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 Getting started with Geoserver.

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

  • Url - The URL for the WMS map service

  • Layers - This is where layers (or layer groups) 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.

      WMSLayers.png
    • 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.

      WMSLayers2.png

      Note

      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 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

  • Format Options - 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

  • 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 ticked, the WMS response includes the filters made using Selection tools, visualizations in the same and visualizations from other dashboards.

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

Navigating the map

After your tilemap visualization is ready, you can explore the map in several ways using various tools:

Panning the map

  • Click and drag anywhere on the map to move the map center

  • Hold Shift to drag a bounding box across the map to zoom in on a desired extent

  • Viewing extent

    • Click Zoom In/Out (si-zoom.png) to change the zoom level manually.

    • Click Fit Data Bounds (fa-crop.png) to automatically crop the map boundaries to the geohash buckets that have at least one result.

  • Click Set View Location (ViewIcon.png) to manually specify:

    • Whether latitude and longitude are in decimal degrees (dd) or degrees/minutes/seconds (dms) ①

    • The latitude ② and longitude ③ of the centroid of the canvas you would like to display

    • The desired level of zoom ④

    • Whether changes are applied ⑤ or cancelled ⑥

pan_options.png

Selection tools - used to create geo filters

  • Click Draw a Polygon (DrawAPolygon.png), then

    • Click on the map canvas and add vertices; if you add a vertex that you don’t want, click the Delete last point option on the menu that opens to the right when you clicked Draw a Polygon tool.

    • When complete, either click on the first vertex or double click and the polygon will autocomplete. Elasticsearch documents within the drawn polygon will be filtered.
  • Click Latitude/Longitude Filter (fa-stop.png), then drag a bounding box across the map, to create a filter for the box coordinates. Elasticsearch documents within the drawn polygon will be filtered.
  • Click Draw a Circle (DrawACircle.png), then drag a circle and release to select documents. Elasticsearch documents within the drawn polygon will be filtered.

Note

For all selection tools, a geo filter is created. This will appear above the map canvas:

GeoFilter.png

Marking tools

  • Click Draw a Marker (MarkerIcon.png), and select any point on the map to place a marker. You can add multiple markers.

  • After adding at least one marker, the Delete Marker(s) option becomes available

    • Point and click to delete individual markers

    • Remove all of them by clicking Clear All

Viewing detailed information

For information on displaying the raw data, see Visualization Spy.