Geographical Stream Panels

<< Click to Display Table of Contents >>

Navigation:  Using s-Dashboard > Working with Panels >

Geographical Stream Panels

Previous pageReturn to chapter overviewNext page

s-Dashboard features two panels that let you display data on a map:



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.

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

Using the Pan and Zoom Panel

Customizing Icons on the Pan and Zoom Panel

Using the World Events Panel

Developing a Choropleth Map with the World Events Panel

Using Blackboard with Geographical Stream Panels

Using the Pan and 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 value*10.

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 add a custom label to your map. To do so, enter the name of one of your columns enclosed in a <%= %>, such as <%= title %>.

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.

Note: if you have Python installed you can serve the contents of the current directory with python -m SimpleHTTPServer <port number>.

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

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.

Using the World Events Map

This map features data marked on a world, regional, country, or US state map. These maps are 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

For countries and states, all ids appear in Appendix A: Map IDs for Cloropleth. Ids for state counties are in a zip file called To use the choropleth feature, the stream should have "key" and "value" columns.

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.

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.