iXMaps

API documentation

THEMES

iXMaps is a vector graphic mapping framework, based on SVG files generated by an iXMaps tool, and a JavaScript library to geographically handle these SVG files.

The iXmaps vector layer is usually displayed on top of an HTML Tile Map powered by Leaflet.

Visualize data with iXMaps

The iXMaps JavaScript library enables the map also for thematic mapping by giving the user the possibility to either 

  1. change properties of the map shapes (choropleth themes), or
  2. create new SVG graphical objects to visualize the data by various chart types
    the SVG chart objects can be positioned
    • either on existing map items (e.g. point of interest) or
    • by geographical coordinates (latitude, longitude)

Defining themes

iXMaps provides a high-level visualization grammar for thematic maps. It defines 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 of 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.

Example:

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

Two different theme types: choropleth and charts

iXMaps supports:

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

Important!

choropleth 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 in the data.

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 and shared by a generated URL.

The theme definition object is serialized and joined as a parameter to an URL. Every thematic map can be represented by a URL which defines the user interface, 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.


Quick Start

 

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


// define the theme

var theme1 = {   
    "layer": "com2011_s",
    "field": "Totale complessivo",
    "style": {
        "type": "CHOROPLETH|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 choropleth 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 choropleth 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 columns 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 a unique ID attribute) for choropleth themes, or as an 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 geographical coordinates 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": "CHOROPLETH|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 (choropleth), or chart objects (bar charts, pies, donuts,...).

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

Sample: 'type:CHOROPLETH|EQUIDISTANT'

colorscheme array

defines the colors to be used in the theme (default: monochrome 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 simplest 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": "CHOROPLETH|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": "CHOROPLETH|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": "CHOROPLETH|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 below

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

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 choropleth 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 (column name of the data 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 the 2nd value 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 'style' object defines the nearly everything of the theme. Let's have a look at the fundamental objects of the sample theme definition:

The 'style' object must at least have 4 elements to define the type, a color scheme, a data source and the 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 (choropleth), or chart objects (bar charts, pies, donuts,...).

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

Example: 'CHOROPLETH|EQUIDISTANT'

colorscheme array

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

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

dbtable string

defines the data to use by the theme. the value is a sequence of parameters 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 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: 'lookupfield' : 'state'


Let's have a look at these 4 properties

string type

With the 'type' property you define the nature of the theme by basic types and modifiers.

The 'type' property is composed of one or more type values joined by '|' characters.

Example:

"type": "CHOROPLETH|QUANTILE"
"type": "CHART|PIE|DONUT|VALUES"

 

The 'type' property must be composed by at least one of the following basic theme types and in case of CHART also the basic chart type.


basic theme types
TYPE_ID Type Description
CHOROPLETH 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


basic CHART types

TYPE_ID Type Description
BUBBLE string

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

SQUARE string

rectangles with size and color options and optional value display

BAR string

bars, bar charts with several bars and stacked bars

POINTER string

bars with a pointing top, useful if we have a range 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

logarithmic 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; shows the color of the field with the highest value 

PERCENTOFMEAN string

with multiple fields; shows the color of the data field with the highest deviation from the fields mean value (in %) 

DEVIATION string

with multiple fields; shows the color of the data field with the highest deviation (in standard deviation)

OFFSETMEAN string

with multiple fields and type CHART; shows 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": "CHOROPLETH|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 the power of 4 to flatten the differences in the chart sizes

SIZELOG string

use the logarithm of the values to size the chart graphics


dynamic opacity for choropleth themes
TYPE_ID Type Description
DOPACITY string

dynamic opacity by the value; lower values get more transparent

DOPACITYMIN string

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

DOPACITYMAX string

dynamic opacity to emphasize the maximum values

like DOPACITY but you can apply the style variables 'dopacitypow' and 'dopacityscale' 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 type

creates 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

BAR,  MULTIPLE or SEQUENCE charts are by default composed vertically; with this modifier you change the direction to horizontally
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 radius 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; each of the 4 points gets a portion of the value relative to the distance to the original position of the value.  

RECT string

modifier for AGGREGATE
aggregate by a rectangular grid (default is a hexagonal grid)

RELOCATE string

modifier for AGGREGATE
position the chart with the aggregated value to the center of gravity of the aggregated values instead of the center of the aggregation grid.  

MULTIPLE string

if you have multiple records for the same position, this 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 adding the modifier HORZ.

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

MULTIGRID string like MULTIPLE but with a fixed offset for all values of the same position, defined by the biggest value.
MULTIQUAD string like MULTIGRID but without fixed grid width (defined by 'gridx');
the chart will grow like a square
VALUES string

add a textual value display to CHOROPLETH or CHART themes

VALUESBACKGROUND string

create a color 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.

array Colorscheme

Property Type Description
colorscheme array

a color scheme is defined by an array of 1 - n string 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 color schemes

The simplest color scheme 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" ]


You can also define a colorscheme by giving 3 colors:

"colorscheme": [ "8","#FFFDD8","#952D44", "3colors", "#884455" ]

string dbtable

Property Type Description
dbtable string

defines the data source

this can be realized by one string which contains the arguments:

name, type and URL

Example:

dbtable : "themeDataObj csv url(http://mysite/mydata/data.csv)"


or by 3 properties 

Example:

dbtable : "themeDataObj",
dbtableTyle: "csv",
dbtableUrl: "http://mysite/mydata/data.csv"

string lookupfield

Property Type Description
lookupfield string

defines the name of the data column which values shall be used to find the shape to use for choropleth themes or to position the chart theme elements on the map.

The values of the lookup column may define a map shape ID

Example:

lookupfield : "city name"

or a geographic position given by latitude and longitude:

Example:

lookupfield : "geocoords"
lookupfield : "LAT|LON"

Description of all 'style' properties

Grammar Reference

style object properties

{  
    "layer": "com2011_s",
    "field": "Totale complessivo",
    "style": {
        "type": "CHOROPLETH|EQUIDISTANT",
        ...
    }
}

The style property defines the representation type and style of a theme as well as the source of the data.

Property Type Description
type string

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

colorscheme array defines the colors to be used in the theme (default: monochrome 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 all charts

linewidth number

define the width of lines within all 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 area fill opacity of CHART themes

shadow boolean

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

aggregation string

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

evidence string

defines how selected items (points, lines, polygons) are marked

value method
'isolate' show only selected class
'isolate_gray' show selected class with color
'highlight' evidence by highlight color

markclass number

defines a distribution class to evidence (see above)

markclasses array

define more than one class to evidence by an array

dominantfilter string

define the filter type for DOMINANT theme value selection

value method
'min' the dominant value must be the strongest of the item
'mean' the dominant value must be the strongest of the item and above the mean of all values

dominantdfilter number

define a % filter for DOMINANT theme value selection

example:
'dominantdfilter' : '30'

the dominant value must be 30% higher than the minimum or  mean value of all items

clipparts number

clip the number of parts of a theme; for example to show only the 3 highest values in a SYMBOL|SEQUENCE chart

filter string

defines a filter string to apply on data loading

it can be a simple string to be matched to the data or a real query string with a simplified SQL syntax

Examples
"filter":"july"
"filter":"WHERE \"month\" is \"july\""

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 a name for the data object 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

defines a JavaScript function to call if data is loaded

datacache boolean

if set to FALSE, the data will be loaded on every theme activation

if set to TRUE, the data will be used from the JavaScript object with the name defined in 'dbtable' if the object already exist


define data columns
itemfield string

the field (column name) where to take the value from; an 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, longitude separated by a comma; example: 
    "lookupfield" : "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":"lat|lon"
    (columns named "lat" or "lon" and cells like  "44.234653")
lookuptoupper boolean

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

lookupdigits number

defines the number of digits to for the lookup value. This useful when the map shape ID's are with leading blanks like '002345' but the data values available are without (like '2345').

defining 'lookupdigits' : '6' will resolve the above problem.

lookupsuffix string

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

exclude array

you may define lookup ID's to exclude from the theme.

Example: "exclude" : "Lichtenstein,Monaco"


theme calculation
ranges string

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

"style": {
  "type": "CHOROPLETH|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 define the center of the classes here.

EQUIDISTANT class distribution normally 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 the condition.

values array

for EXACT theme types, you may want to define the accepted values or give an order to all the discrete values of the data column

note: EXACT values are strings. 

symbols array

define the symbols for CHART type SYMBOL

This can be IDs of loaded symbols defined in SVG or generic symbol shapes.

The generic symbols are: 'circle', 'square', 'diamond', 'triangle', 'label', 'hexagon' or 'cross'

The default symbol is 'circle'

align string

define the alignment for CHART themes; possible values are: 'center', 'top', 'bottom', 'left', 'right', 'above' or 'below'

you can combine align values; example: "align" : "above|left" 

sizefield string

the name of the data column 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 too 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 a value that will produce a chart of a normal size (ca.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":"%" defines a 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 can define a unit used only for the theme legend 

xaxis array

for BAR charts with multiple bars and PLOT charts, you can define an x-axis description.

Example
if you have 3 bars with values for 2012, 2013 and 2014
you can define the x-axis by: "xaxis" : ["2012","2013","2014"] 

label array

define labels to be displayed in the legend

the labels of the theme legend display are preset with the data column names; here you can overwrite them with more readable or significant text.
Example: "label":["Women","Men"]

title string

define the title of the theme to be shown in the theme legend

snippet string

define a short description of the theme to be shown in the theme legend and in chart info bubbles

description string

define a verbose description for the theme legend

infotitle string

define a title for all chart info bubbles

titlefield string

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

snippetfield string

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

labelfield string

the name of the data column to use as chart label

showdata string

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

textplacement string

actually not used


textual value display
valueupper string

define an upper map scale value to suppress value display on large map scales (if you zoom out)

Example:
"valueupper":"1:100000" shows values only if the map scale is below 1:100000

valuescale number

> 1 shows bigger, <1 smaller chart 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 more dynamic fading

fadenegative string

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


alpha channel (in combination with DOPACITY)
alphafield string

the name of the data column to be used for the calculation of the opacity of the shape or the chart

alphafield100 string

the name of the data column to use along with 'alphafield' to calculate the value for dynamic opacity;
special value '$density' (only with CHOROPLETH): defines the density of the value in 'alphafield' as measure for the dynamic opacity

dopacityscale number

defines a factor to apply to the calculated dynamic opacity
(see DOPACITY and alphafield)

dopacitypow number

defines the power (x power n) for the dynamic alpha calculation; (0.1 < value < 10)

the effect is comparable to the contrast for images, but higher values lead to lower contrast
(see DOPACITY and alphafield)

dopacityramp number

(deprecated) same as dopacitypow


for themes with 'timeline' (CLIP)
clipframes string

the number of frames for CLIP themes

clipframerate string

the number of frames per second for CLIP themes

cliplegend string

a text to display while CLIP themes are running


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: defines the opacity of the chart background box

boxmargin string

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

bordercolor string

with type modifier BOX: defines 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 (in pixel) of the border of the background box

borderradius string

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