iXMaps

Theme API Documentation

Thematic maps


iXMaps is a vector graphic mapping framework, based on SVG files generated from shape files and QGIS projects, and a Javascript library to geographically handle these SVG files.

Visualize data with iXMaps

The iXMaps Javascript library enables the map for thematic mapping either by changing properties of the map shapes (choroplethe themes), or creating new SVG graphical objects to visualize the data by various chart types which are positioned either on map items, or by geographical coordinates (latitude, longitude) defined by the data.

Defining themes by grammar

iXMaps defines a high-level visualization grammar for thematic maps. It provides a concise JSON syntax for supporting rapid generation of visualizations from raw data.

At its core, iXMaps theme specifications are JSON objects that describe visualizations as mappings from data to properties of geographical map objects (polygons or lines) or graphical marks (e.g., points, bars, etc ) bound to geographically defined positions or objects on the map.

Customize and share themes

Because with iXMaps themes are 'alive' and not images, every theme can be customized to adapt colors or chart types and sizes. Than if you like, you can share the customized map by generating a new URL containing the customized map and theme parameter

The theme definition object can be serialized and joined as a parameter to an URL. In consequence every thematic map can be represented by a URL which combines the HTML template, the Tile map service, the SVG map and the theme definition.

iXMaps themes are always created from raw data, given by a data URL, so if the data changes, the theme follows. By defining a refresh interval, you can have almost real time data showed in the theme.  

Two different theme types: Choroplethe and charts

iXMaps supports:

  1. choroplethe themes, which change the color property of map items like shapes or lines
  2. symbol/chart themes, which create graphical objects (SVG) like bubbles, bars or pies to represent the theme values on the map

Important!

Choroplethe themes require an 'id' of the map elements to be used for the theme.

Chart themes can be positioned on the map either by the id of map elements or by geographical coordinates, if present in the data.


Quick start

Introduction

Themes are defined by a JSON Object using the iXMaps high-level visualization grammar and realized by a iXMaps API function.

You may define the theme first and call it or define the theme inside the function call. You can also wrap it all together into a HTML link and place the theme function in the 'href' attribute.

Example


// define the theme

var theme1 = {   
    "layer": "com2011_s",
    "field": "Totale complessivo",
    "style": {
        "type": "CHOROPLETHE|EQUIDISTANT",
        "colorscheme": [  "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
        "dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
        "lookupfield": "comune"
    }
}

// put the theme on the map

ixmaps.newTheme("Totale complessivo",theme1,"clear");

This is the minimal definition of a chloroplethe theme based on named shapes within the SVG map. The basic properties are:

Property Type Description
layer string Defines the layer of the map used by this theme. This layer must provide the topology for choroplethe themes or may define points to position charts on. In these cases, the entities of the layer must have IDs generated that correspond to the cell values of the data colums defined in the 'style' parameter "lookupfield".
field string Defines the field (column name) of your data, where to find the values of your theme
style object Defines the type and the layout of the theme in Javascript object notation (JSON);

The 'layer' object

Important!

If you want to use a layer (in ixmaps layer items are SVG groups with unique ID attribute) for choroplethe themes, or as anchor for chart positioning, the layer must be created with appropriate ID's (which correspond to the data field, you define in the theme)

The 'field' object

Note: for chart themes it is possible to position the charts at geografic coodinates defined by latitude and longitude. For this case in the 'lookupfield' you define 2 fields, that will contain the lat/lon pair, separated by "|". Example: "lookupfield": "Lat|Lon"

The 'style' object

Defines the type and the layout of the theme in Javascript object notation (JSON)


{ property1:value, property2:value,... }

A list of all possible parameter you find here

Let's have a look on the definition from the above minimal example:


"style": {
    "type": "CHOROPLETHE|EQUIDISTANT",
    "colorscheme": [  "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
    "dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
    "lookupfield": "comune"
}
Property Type Description
type string defines the type of the theme. This is the graphical representation, which can be a colorized shapes (CHOROPLETHE), or chart objects (bar charts, pies, donuts,...).

A type definition is a string with a combination of type variables, separated by '|'.

Sample: 'type:CHOROPLETHE|EQUIDISTANT'

colorscheme array

defines the colors to be used in the theme (default: momochrome blue)

dbtable string

associate an external (javascript) database table to this theme; value:name of the table (without suffix!) sample: 'dbtable:layerdb'

lookupfield object

define a field of the above external table which values can be used to find the theme shapes; sample: 'lookupfield:statename'

Realizing the theme

The simples way to realize a theme is to define it as a JavaScript object and realize it with the appropriate iXmaps API call ixmaps.newTheme(" ... title ...",themeObj,[flag]).

For the above example this would lead to:


var theme1 = {   
    "layer": "com2011_s",
    "field": "Totale complessivo",
    "style": {
        "type": "CHOROPLETHE|EQUIDISTANT",
        "colorscheme": [  "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
        "dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
        "lookupfield": "comune"
    }
}

ixmaps.newTheme("Totale complessivo",theme1,"clear");

You can also put it all together to a function call


ixmaps.newTheme("Totale complessivo",{  
        "layer": "com2011_s",
        "field": "Totale complessivo",
        "style": {
            "type": "CHOROPLETHE|EQUIDISTANT",
            "colorscheme": [  "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
            "dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
            "lookupfield": "comune"
        },"clear"
    });

or define it all in your HTML within an <a> tag


<a href='javascript:ixmaps.newTheme("Totale complessivo",{
            "layer": "com2011_s",
            "field": "Totale complessivo",
                "style": {
                "type": "CHOROPLETHE|EQUIDISTANT",
                "colorscheme": [  "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
                "dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
                "lookupfield": "comune"
            }
        },"clear"
    );'> Totale complessivo</a>


The iXMaps data visualization grammar

Basic structure


Themes are defined by JSON objects, like in the example shown below, and realized with the appropriate iXmaps API call ixmaps.newTheme(" ... title ...",themeObj,[flag]).


var theme1 = {   
    "layer": "com2011_s",
    "field": "Totale complessivo",
    "style": {
        "type": "CHOROPLETHE|EQUIDISTANT",
        "colorscheme": [  "5","#FFFDD8","#B5284B","2colors","#FCBA6C" ],
        "dbtable": "themeDataObj csv url(http://mysite/mydata/data.csv)",
        "lookupfield": "comune"
    }
}
ixmaps.newTheme("Totale complessivo",theme1,"clear");

There are the following main arguments to define, to describe a theme:

layer string defines the layer of the map to be the reference for this theme. For choroplethe themes this layer will provide the topology to colorize, for charts it may define points to position charts on. In both cases,the entities of the layer must be identified and the ID's must correspond to the values in the data column defined by the 'style' parameter "lookupfield".
field string defines the field (colum name of table) of your data, where to find the values of your theme; this can be only one field, or a sequence of fields (column names) separated by '|'; example: 'col1|col2|col3'
field100 string defines the field of your data, where to find a 2nd values for percent, difference or other value operations
style object defines the type and the layout of the theme in Javascript object notation (JSON)

Fundamental elements of the 'style' object

The last object defines the nearly everything of the theme. Lets have a look on the fundamental objects of the sample theme definition:

The 'style' object must at least have 4 elements to define type, color scheme, data source and lookup field for the theme as you can see in the above example

Property Type Description
type string

defines the type of the theme. This is the graphical representation, which can be a colorized shapes (CHOROPLETHE), or chart objects (bar charts, pies, donuts,...).

A type definition is a string with a combination of type variables, separated by '|'.

Example: 'CHOROPLETHE|EQUIDISTANT'

colorscheme array

defines the colors to be used in the theme (default: momochrome blue)

Example: [ "red","blue","green" ]

dbtable string

defines the data to use by the theme. the value is a sequence of parameter to define:

  1. the name of the data table (arbitrary, but must be unique)
  2. the type of the data source
  3. the url of the data source
  4. [optional] a javascript function call to to prepare the data

Example: 'themeDataObj csv url(http://mysite/mydata/data.csv)'

lookupfield object

define the name of the row of the above defined data table, where to find the values which can be used to identify the layer items (shapes or points) for the theme creation.

Example: 'comune'


Lets have a look on the 4 objects

Reference

type

With the 'type' keywords you define the nature of the theme by basic types and modifyers


there are 2 different theme types
TYPE_ID Type Description
CHOROPLETHE string

defines a theme based on map shapes (polygons) that will be colored by value classes and a color scheme

CHART string

defines a theme visualized by charts positioned on the map


and the following basic CHART types
TYPE_ID Type Description
BUBBLE string

simple circle bubbles with size and color options and optional value display

SQUARE string

rectangulars with size and color options and optional value display

BAR string

bars, barcharts with several bars and stacked bars

POINTER string

bars with a pointing top, usefull if we have ranges from negative to positive values

PIE string

pie chart with one or more parts

DONUT string

a donut chart with one or more parts

SYMBOLS string

a theme visualized by symbols on the map

BUFFER string

a special theme to create one or more buffers around map objects, which can be points, lines or shapes;
the following example draws buffers of 500 meters around every school in the layer 'schools'

}
"layer": "schools",
"style": {
  "type": "CHART|BUFFER|VALUE|NOINFO",
  "colorscheme": ["#ffffff"],
  "buffersize":"500",
  "borderstyle":"dashed",
  "align":"center",	
  }
}

 


these basic types can be used in combination with the following modifier to define the final chart type


I. methods to create the class ranges for color schemes:
TYPE_ID Type Description
EQUIDISTANT string

equidistant value classes

LOG string

logarithmical value classes

QUANTILE string

quantile value classes; same number of members in every class

EXACT string

every value represents a color class

DOMINANT string

with multiple fields, show the color of the field with the highest value 

PERCENTOFMEAN string

with multiple fields, show the color of the field with the deviation from mean (in %) 

DEVIATION string

with multiple fields, show the value with the highest deviation (in standard deviation)

OFFSETMEAN string

with multiple fields and type CHART, show the deviation of all fields by +/- pointers:
example:  'type':'CHART|BAR|POINTER|OFFSETMEAN'

RANGES string

class ranges are defined explicitly by a 'ranges' parameter; example:

"style": {
  "type": "CHOROPLETHE|RANGES",
  "colorscheme": ["5","#FFFDD8","#B5284B","2colors","#FCBA6C"],
  "ranges":"-100,-10,0,10,100"
}

II. defining the value algorithm
TYPE_ID Type Description
DIFFERENCE string

value = [field] - [field100]

FRACTION string

value = [field]/[field100]

PERCENT string

value = [field]/[field100]*100

PERMILLE string

value = [field]/[field100]*1000

RELATIVE string

value = [field]/[field100]*100 - 100

INVERT string

value = 100 - [field]/[field100]*100

CALCVAL string

value = Math.round([field]*[field100]/100)

CALC100 string

value = Math.round([field]*[field100]/100)

PRODUCT string

value = [field]*[field100]

NEGATIVEISVALUE string

allow negative values

ZEROISVALUE string

allow zero values

SUM string

define the aggregation mode; if values are absolute, you may define 'SUM';
if values are in percent, you don't want SUM but MEAN, which is the default


chart size methods
TYPE_ID Type Description
LINEAR string

the size of the chart graphics represents the value

VOLUME string

for 3d charts; the volume of the chart graphic represents the value

SIZE string

for 2d charts; the surface of the chart graphic represents the value

SIZEP4 string

for wider value ranges, this uses power of 4 to flatten the chart sizes

SIZELOG string

use the logarithm of the value to size the chart graphics


dynamic opacity for choroplethe themes
TYPE_ID Type Description
DOPACITY string

dynamic opacity by the value; lower values get transparent

DOPACITYMIN string

dynamic opacity to emphasize the minimum values; higher values get transparent

DOPACITYMAX string

dynamic opacity to emphasize the maximum values; like DOPACITY but you can apply the style variables 'dopacitypow' and 'dopacitypow' to define custom opacity curves

DOPACITYMINMAX string

emphasizes minimal and maximal values; the average values get more transparent

BIPOLAR string

same as DOPACITYMINMAX

DOPACITYLOG string

like DOPACITYMAX, but takes the logarithm of the values to scale the opacity

DOPACITYMEAN string

like DOPACITY, to use with DOMINANT, PERCERTOFMEAN or DEVIANT


chart type modifier
TYPE_ID Type Description
SEQUENCE string

make a composite chart of n BUBBLE, SQUARE, BAR or SYMBOL; this means a chart composed of a sequence of graphics of the defined type, positioned in a defined way relative to the center of the chart; see chart positioning below.
The number of sequenced charts is given by the number of fields defined; with SYMBOLS, the symbol types can be defined by the 'symbols' variable; default is 'circle'.

STARBURST string

PIE or DONUT modifier; make radius variable by value;

3D string

make BAR, PIE or DONUT tree dimensional

SIZE string

with PIE or DONUT, the radius represents the value

HEIGHT string

with PIE or DONUT, the char height represents the value

WIDTH string

with PIE or DONUT like SIZE; with POINTER, makes the pointer width more dynamic by value

VOLUME string

with BAR or PIE; width and height represent the value; bars get cubes


chart positioning and part sorting
TYPE_ID Type Description
CENTER string

the chart, or the single graphics of a composed chart are positioned on the center of the chart position.

LEFT string

the chart is aligned to the left of the chart position.

RIGHT string

the chart is aligned to the right of the chart position.

TOP string

the chart is aligned to the top of the chart position

BOTTOM string

the chart is aligned to the bottom of the chart position

ABOVE string

like TOP

BELOW string

like BOTTOM

HORZ string

BARs and  MULTIPLE or SEQUENCE charts are composed horizontally; default is vertically
example: CHART|BAR|HORZ|UP|CENTER defines something like a pyramid, useful for demographics

STAR string

the single graphics of a composed chart are positioned around the center of the chart position with the first graphic on the center and the following around the first with the radiuses touching each other.

SORT string

the graphics are sorted by their values; default is sort down; if not defined, the graphics are drawn in the order of the field definition

UP string

sort up, the smallest value is on the top

DOWN string

sort down, the biggest value is on the top

RANDOM string

sort the graphics by random; every chart gets its own 'composition', this is useful with STAR charts, to avoid pattern forming  


miscellaneous
TYPE_ID Type Description
AGGREGATE string

aggregate values of the same position before creating the charts; this is useful if you have a dataset with multiple records for the same position.
used with the style parameter 'gridwidth', you can aggregate every theme to a virtual grid, the position of a chart is mapped to the nearest point of the defined grid; the value(s) is/are added to the point.   

DIFFUSE string

only with 'gridwidth': like AGGREGATE, but with a slightly different algorithm; every value is distributed to the nearest 4 points of the aggregation grid; every of the 4 points gets a portion of the value relative to the distance to the original position of the value.  

MULTIPLE string

if you have a dataset with multiple records for the same position, this type modifier adds an offset to every repeated position, so you see every value displayed; normally the offset is added in Y-direction; you can change this by the modifier HORZ.

you can define rows by the style parameter 'gridx'; example: 'gridx':'3' means that every 3 offsets a new row will be started.

VALUES string

add a textual value display to CHOROPLETHE or CHART themes

VALUESBACKGROUND string

create a colorized background for the textual value representation of CHART themes

BOX string

create a background box around every chart; the box can be customized by the style parameter: 'boxopacity', 'boxborder' and 'boxmargin' described below.

MOVABLE string

makes charts movable; this means you can drag the charts on the map to any desired position.

Colorscheme

Property Type Description
colorscheme array

a colorscheme is defined by an array of 1 - n values

the values may define directly 1 - n colors

Example:[ "red", "green", "blue" ]

or a dynamic color scheme defined by:

  1. the number of colors
  2. n color scheme parameter

Example:[ "7", "red", "green" ]

defining colorschemes

The simplest colorscheme is one color definition, like shown below:


"colorscheme": [ "#FF0000" ]

 or defined by RGB notation:

"colorscheme": [ "RGB(255,0,0)" ]

 or the color name:

"colorscheme": [ "red" ]

If you need more colors, you can define them directly:


"colorscheme": [ "#FFFDD8","#FFEBB2","#FED992","#FCBA6C","#F99E5B","#E86144","#B5284B","#952D44" ]
or by a generated color scheme.

"colorscheme": [ "8","#FFFDD8","#952D44" ]

 

Grammar Reference

'style' Parameter

Property Type Description
type string

defines the nature of the theme, for details see description of 'type' above

colorscheme array defines the colors to be used in the theme (default: momochrome blue)

Example: [ "red","blue","green" ]

nodatacolor string

define the color, that will be displayed if there is no value for the item

linecolor string

define the line color of PIE or BAR charts

opacity number

defines the overall opacity of a theme (CHLOROPLETHE and CHART)

autoopacity boolean

if set to TRUE, the opacity of CHLOROPLETHE themes depends on the map actual zoom; zooming in the theme gets more and more transparent (to show details of the base map)

fillopacity number

defines the opacity of surface filling in CHART themes

shadow boolean

if set to TRUE, charts are displayed with a drop down shadow

aggregation string

define the aggregation algorithm: may be 'sum' or 'mean' (default is 'mean')

evidence string

defines how selected items (points, lines, polygons) shall be marked  

dfilter number

define a filter for PERCENTOFMEAN

overviewchart string

defines the 'type' of the overview chart, which is the sum or class chart shown in the theme legend; default: NONE  


define data sources
dbtable string

defines the data source of the themes

dbtableType resource

defines the type of the data source of the themes, (csv, json, FT)

dbtableUrl string

the URL to the data source

dbtableEXT string

a Javascript function to call if data is loaded


define data columns
itemfield string

the field (column name) where to take the value from, alternative to the definition in 'fields'

lookupfield string

the  column/s of the data which cells define the relationship to the map; these can be:
a) an ID which corresponds to the IDs of map elements; in general the name of countries, towns, streets
b) a geographical position given in Latitude and Longitude in one or two data columns.

  • in case of one column the contents of the cells must be two numbers: latitude,longitudeseparated by comma; example:  "lookupfield":"Position" and Position cell values like "44.234653,11.35647858"
  • in case of two columns the first must define the latitude and the second the longitude; example: "lookupfield":"latcol|loncol" and latcol cells like  "44.234653" and loncol cells like "44.234653"
lookuptoupper boolean

if TRUE, lookup cell values are changed toUpper before matching the corresponding ID on the map
example: the data may contain 'London', the map knows only 'LONDON'

lookupsuffix string

if TRUE, the define suffix will be appended to all lookup cell values before matching the corresponding ID on the map

exclude array

you may define map item IDs to exclude from the theme display; example; "exclude" : "Lichtenstein,Monaco"


theme calcolation
ranges string

define value ranges for themes with color classes defined by a colorscheme, you must define n+1 values for n colors

"style": {
  "type": "CHOROPLETHE|RANGES",
  "colorscheme": ["red","orange","yellow","green"],
  "ranges":"-100,-10,0,10,100"
}

in the above example there are 4 ranges with:

"red"	 from  -100 to <-10
"orange" from   -10 to <0
"yellow" from     0 to 10
"green"  from   >10 to 100
rangecentervalue string

for EQUIDISTANT class distribution, you can here define the center of the classes; EQUIDISTANT automatic class definition takes the lowest and the highest value and divides the range into n equal parts. If you define a 'rangecentervalue' the range will be symmetric to this value; this means either  the min or the max value will be adjusted to fulfill this condition.

values array

for EXACT theme types, you may want to define the allowed values or you can use this definition option to give an order to the possible EXACT values; note: EXACT values are strings. 

symbols array

define the symbols for 'type' SYMBOL; this can be IDs of loaded symbols defined in SVG or generic symbol shapes created 'on the fly'. The generic symbols are: circle, square, diamond, triangle, label

The default symbol is 'circle'

align string

define the alignment for CHART themes; possible values are: center, top, bottom, left, right, above, below; you can combine align values; example: "align" : "above|left" 

sizefield string

the name off the data column to use to size the charts

buffersize string

the size of BUFFER charts to draw around points, lines or areas (in meter)

bufferstep string

the amount of buffer size changes (meters)

field100min string

clips the charts drawn by defining a minimum value for the 'field100' values; useful if you want to make a theme with percentages to exclude values based on few items 

fractionscale string

defines a scaling factor for values created with the FRACTION 'type' modifier

minvalue string

minimal value, values below this are not shown

normalsizevalue string

you can define the value that will produce a chart of a normal size, which is 30 pixel

scale string

define a scaling factor (0 >x<100) to scale the chart size

weights string

the values from the theme data cells can be 'weighted' by a floating-point factor; here you can define n factors for n fields (data columns); example: "weights" : "1,1,0.5,1"  will scale the values of the 3. data column by 0.5


texts
units string

give a unit to the value display: example "units":"%" leads to value display like "56 %"

units100 string

also the value100 (e.g. 100% value) can have a unit displayed

sizevalueunits string

if you define a 'sizefield', you can give it a unit within the char info display; example "sizevalueunits" : "residents"  

legendunits string

you may define value units, only used within the theme legend 

xaxis array

for BAR charts with multiple bars, you can define a x-axis description; example you have 3 bars with values for 2012, 2013 and 2014, then yuo can define the x-axis text with: "xaxis" : "2012,2013,2014" 

label array

define legend label, the value label in the theme legend display are preset with the column names you defined to get the data; here you can overwrite them with more readable or sigificant text: "label":"label1,label2,vabel3"

title string

define the title of the theme, to show in the theme legend

snippet string

define a short description to use in the theme legend and in chart info bubbles

description string

define a description to use in the theme legend and in chart info bubbles

infotitle string

define a title for all chart info bubbles

titlefield string

the name off the data column to use as chart info title

snippetfield string

the name off the data column to use as short description in the chart info

labelfield string

the name off the data column to use as chart label

showdata string

show the original data of the chart within the chart info bubble

textplacement string

???


textual value display
valueupper string

define an upper map scale value to suppress value display if you zoom out the map; e.g. "valueupper":"1:100000" shows values only if the map scale is lower than 1:100000

valuescale string

show bigger or smaller value texts

clipvaluesize string

show values only if the dynamic text size (which depends on the chart size) is greater than the defined value (pixel) 

fadevaluepow string

defines the power (x power n) of value display transparency depending on the value size; higher power leads to faster transparancy

fadenegative string

defines the opacity of negative values ( 1 ... 0.1 )


alpha channel (choroplethe themes)
alphafield string

the name off the data column to use to create CHOROPLETHE themes with dynamic opacity

alphafield100 string

the name off the data column to use with 'alphafield' to calculate the value for dynamic opacity;
special variable '$density' to define the density of the value in 'alphafield' as source for the dynamic opacity

dopacityscale string

defines a factor to apply to dynamic opacities calcolated by a dedicated value (see DOPACITY and alphafield)

dopacitypow string

defines the power (x power n) for the dynamic alpha calculation; it is comparable to the contrast for images (see DOPACITY and alphafield)

dopacityramp string

(deprecated) same as dopacitypow


for theme with 'timeline' (CLIP)
clipframes string

the number of frames for CLIP themes

cliplegend string

a text to display while CLIP themes are running

clipparts string

clip the number of parts of a theme


multiple values for the same position (MULTIPLE)
gridx string

a x-axis grid width for MULTIPLE themes


background box for charts ('BOX')
boxopacity string

with type modifier BOX: define the opacity of the chart background box

boxmargin string

with type modifier BOX: define the margin (pixel) of the chart background box

bordercolor string

with type modifier BOX: define the color of the border of the chart background box,
color defined like: '#123456', 'red', or RGB(128,234,255)

borderstyle string

with type modifier BOX: define the border style of the chart background box;
possible styles are :'solid', 'dotted' or 'dashed'

borderwidth string

with type modifier BOX: define the width (pixel) of the border of the background box

borderradius string

with type modifier BOX: define the corner radius (pixel) of the chart background box