Geographical and 3D Stream Panels

s-Dashboard features two panels that let you display data on a map, as well as a panel that lets you display multiple datasets of bubbles.

Panel Benefits
Pan & Zoom panel Offers more options for both map and marker appearance.
World Events panel Greater flexibility in terms of displaying specific states, countries, or regions.Ability to develop a choropleth map.
3D Bubble Chart Lets you display two datasets at once in a bubble chart.

Both panels require that you have latitude and longitude values in your data. The name of the latitude column needs to start with “lat”. The name of the longitude column needs to start with “lon” or “lng”.

Pan & Zoom Map

You can change preferences for the panel by clicking the Panel Preferences icon in the upper right corner of the panel.

Preferences include:

  • Whether or not to cluster events. If you deselect this option, all events appear individually.
  • Diameter Formula. Here you can use the name of a column, or use that column in a mathematical formula, such as value10.
  • Diameter Is. Here you choose pixels or meters for the Diameter Formula.
  • Display Mode. Choose from the following
    • Show all events displays all events up to the maximum defined in Maximum Events, no matter how old.
    • Show all events and trail displays all events, along with a line connecting an event to its previous location. This is useful for moving vehicles, for example.
    • Show most recent event displays only events within the maximum time.
    • Show most recent and trail displays only events within the maximum time, along with a line connecting an event to its previous location. This is useful for moving vehicles, for example.
  • Event Label lets you customize the labels for your map. To do so, enter any text and include column values by enclosing the name of your columns between <%= %>, such as <%= title %>.
    • This example shows the default label:
      Lat: <%= lat %> Lon: <%= lon %>
      
    • Each <%= %> can take any valid javascript expression, for example:
      <%= speed %> kph, <%= parseInt(speed * 5/8) %> mph
      
    • As well including text, and data from your stream columns, you can also embed HTML elements including bullets, line breaks, tables, formatting and hyperlinks. For example the Sydney Buses StreamApp uses:
      Driver: <%= name %><br/>Speed: <%= speed %> kph (<%= speed_cat %>). <%= highway %><br/>Lat: <%= lat %> Lon: <%= lon %>
      
    • This could be enhanced into a table format:
      <table><tr><td>Driver</td><td><a href="http://sqlstream.com"><%= name %></a></td></tr><tr><td>Speed</td><td><%= speed %> kph  <%= speed_cat %></td></tr><tr><td>Highway</td><td><%= highway %></td></tr><tr><td>Lat</td><td><%= lat %></td></tr><tr><td>Lon</td><td><%= lon %></td></tr></table>  
      
  • Key Color Map lets you customize how events, markers, and trails appear. The entries in this table select the color of the marker for an event, the circle surrounding it, and the trail it leaves behind, for each value of the key column. An entry with an empty key value sets the default.

Customizing Icons for the Pan and Zoom Map

In preferences for the Pan and Zoom map, you can select Custom for Marker Icons. When you do, several additional fields appear in the Preferences dialog box.

The most important of these is called Icon URL. Here, you can specify a location for your custom icons, and use variables so that this URL changes depending on the current row.

To do so, you set up a template that is evaluated for each row to create the URL for the custom icon. In other words, you can use columns from a stream, such as columns with lists of colors or numbers, to determine the icon that appears for a particular row. You reference column values using <%= column_name %>. For example, to reference a column called “bearing”, you would write <%= bearing %>. You can use any accessible location for these icons, but if you use your own location, it must begin with http:// or https:// and be served by a web server. A value called <%= builtin_path %> points to a directory with pre-installed custom icons. This location corresponds to <StreamLab installation dir>/StreamLab/static/js/sand/panels/geo_v2/tiled/images Another variable, <%= key_map_color %>, lets you reference the color for the current key map–the one that you set up in the Preferences dialog box. This is the color the map would use if you selected flags instead of custom.

Setting the Path for Custom Icons

StreamLab ships with a set of built-in icons. These are a set of arrows for showing bearing on the map. We will use these icons to walk you through the process of setting up custom icons.

To use the arrow icons, for example, you will need to write a template that generates a URL that looks like this:

<%= builtin_path %>/arrows/large/blue/45.gif

That would select a large blue arrow pointing northeast.

To begin, make sure that you have

  • Selected Custom for Marker Icons.
  • Selected None under Circle for Key Color Map.
  • Deselected Cluster Events.

Taking these steps will ensure that you only see custom icons on the map.

Setting Up Columns for the Incoming Stream

In order to create a URL that changes for each row, you need to have columns with meaningful information. If you are using StreamLab, you can use the Categorize Analytic to set these up. For example, you could duplicate a column called Speed, and then use Categorize to create a column with sizes: small, medium, large, extra large. Otherwise, you will need to work with a SQL programmer to make sure these columns are available.

For this demonstration, you will need three columns:

  • size: one of small, medium, large, xlarge
  • color: one of black blue brown cyan green orange pink red violet white yellow
  • bearing: an integer in [0..360], 0 is north

Creating the Icon URL

You can use these to create an Icon URL that fully selects the arrow’s size, color, and direction.

  1. Once you have set up the three columns (with these exact names), enter the following into the Icon URL field: <%= builtin_path %>/arrows/<%= size %>/<%= color %>/<%= bearing %>.gif
  2. Click Update. The map should show arrows of varying sizes as data streams. Each row will evaluate to something like the following:
<StreamLab-installation-dir>/StreamLab/static/js/sand/panels/geo_v2/tiled/images/arrows/small/violet/145.gif

Using Other Settings

The rest of the settings for custom icons select the image size and anchor point. For the arrows, the width and height are 100 and the anchor point is in the center, x = 50 and y = 50.

We recommend providing the true (unscaled) size of the image files and the center as the anchor.

Serving Custom Icons

If you are using custom icons, you need to be able to serve them, preferably without interfering with the StreamLab / s-Dashboard installation.

There are several approaches to serving custom icons. You could serve them from the same server that StreamLab / s-Dashboard is running on, or from somewhere else.

  1. If you have Python installed you can serve the contents of a directory using python -m SimpleHTTPServer <port number>. The SQLstream Docker images and trial VMs all have python installed. Make sure the selected port is open.
  2. The sqlstream/complete image has the lighttpd web server installed, and it’s easy to add to sqlstream/slim (apt-get install -y lighttpd) taking around 1MB.
    • Create a directory under /var/www/html - just don’t clash with the img directory used by the SQLstream coverpage (if present).
    • Either physically create the directory, or mount a volume there. For example use /var/www/html/i as the image root
    • Set Icon URL to http://localhost:/i/\<your-image-file>.png (or .ico or .jpg)
    • The SQLstream images use port 80, but you can configure lighttpd to use a different port (see /etc/lighttpd/lighttpd.conf)
  3. You can use either of the above (or any web server) installed on a remote server
  4. It is possible to store the icons in a cloud storage service like AWS S3 - as long as you make them public.
  5. You can store icons in a Github repository. Assuming the account is OwnerName:
    • Store the images in a repo - here called icons; in my case in the top level directory
    • The normal view of the image is at (for example): https://github.com/OwnerName/icons/blob/master/fast.png
    • This shows the image inside the github UI. To see the raw image use: https://github.com/OwnerName/icons/blob/master/fast.png?raw=true
    • This redirects immediately to: https://raw.githubusercontent.com/OwnerName/icons/master/fast.png
    • So, assuming the icon name is passed in a column called speed_cat you can use that by setting Icon URL to: https://raw.githubusercontent.com/OwnerName/icons/master/<%= speed_cat %>.png

In all cases using a remote server or cloud service, make sure that the icon server can be seen by the StreamLab or s-Dashboard client, both when you are developing the dashboard and then later when you deploy it into ptoduction.

World Events Map

This panel features data marked on a world, regional, country, or US state map. These maps appear as blocks of color, but you can change the color scheme. The World Events map below displays Australia only, with data events occurring near Sydney.

For the World Events panel, you can use Panel preferences to change the color scheme, and, more importantly, to choose the specific country, US state, or region that you want to display. Areas can be colored according to a value (choropleth map) by providing a key column containing text that matches the IDs used by the map, and a corresponding value column.

Developing a Choropleth Map with the World Events Panel

Key values should list ids for the map. When a row is sent to the map, it looks at the key. If it matches an id on the map, the value (0..100) is used to select the color for that area.

You can choose which map to display from the Panel Preferences. The options are:

Group Map Description
Regions World Contains all countries, using the ISO-3166 3 character code
USA 50 States All US states + DC and Puerto Rico; see state IDs
USA 48 States Only the continental 48 states plus DC; excludes AK/Alaska, HI/Hawaii and PR/Puerto Rico
USA, Canada, and Mexico USA is divided by state - see state IDs - plus ‘CAN’ for Canada and ‘MEX’ for Mexico
Africa All countries in the continent of Africa
Asia All countries in Asia
Eurasia All countries in Eurasia
Europe All countries in Europe
North America USA, Canada, Mexico and the Carribean
Oceania All countries around Australasia and the Pacific
South America All countries in the South American continent
Western Europe All Western European countries
US States Alabama to Wyoming One state map divided by county for each of the 50 states + DC and Puerto Rico. Use the county name as the key column - so for Cook County, IL use ‘Cook’ as the key. See County Names by US state
Countries Afghanistan to Zimbabwe, grouped as A-C, D-H, I-L, M-P, Q-S, T-Z Each map represents a single country without subdivision. Use the 3 letter ISO-3166 country code as key

Using Blackboard with Geographical Stream Panels

s-Dashboard has a simple messaging system, known as the blackboard, for panels to communicate with each other implemented as a blackboard containing JSON messages. You can use the Blackboard to change the output for a panel by modifying that panel’s query template. Both geographical stream panels let you send click information to Blackboard. For Pan & Zoom, you can send event clicks only; for World Events, you can send events and region clicks.

See Using the Inter Panel Blackboard for more details.

Using the 3D Bubble Chart

The 3D Bubble Chart draws overlapping bubbles in multiple sets. It requires three columns formatted as follows: _x, _y, and _z, as well as ROWTIME.

A simple example would be the following:

  • n_x
  • n_y
  • n_z
  • m_x
  • m_y
  • m_z

The z values determine the radius of a bubble drawn at (x,y). Each set of three columns with the same prefix becomes a separate dataset. So in the above examples, a set of bubbles will be drawn for n and for m.

You need to format the names of these columns before you open this chart in s-Dashboard or StreamLab.