API Documentation

Most methods in the mapmap.js API specify only a minimum number of arguments - additional parameters can usually be passed through an options object.

Creating the Map

mapmap(element, [options])

Argument	Value
element	The SVG Element the map should be consturcted with. Either a DOM element, or a String containing a CSS selector expression.
options	An options object.

options

Option	Default	Description
language	'en'	The language code to use. Used for localizing number formatters.

Currently, maps can only be constructed from existing SVG elements. The width and height attributes of the map element must be set to determine the aspect ratio of the map. You can use CSS to size the map independently from its width and height attributes.

Returns a new Map object.

Examples

// creates a new map from the SVG element with id "theMap"
var map = mapmap('#theMap');

// creates a map with some options
var map = mapmap('#theMap', {
    language: 'de'
});

Map methods

Map.geometry(spec, [options])

Argument	Value
spec	A URL to a geometry file, or a Function to generate/transform geometry data.
options	A string specifying the property to use as a primary key, or an options object.

options

Option	Default	Description
key	'id'	The property to use as a primary key to identify the geometry. This is used to merge geometry with data.
layers		A String to be used as the name for the geometry layer, of an Array of Strings specifying which layers to use in case of formats that contain multiple layers (e.g. TopoJSON). If not specified, an automatically generated layer name is used.

Adds geometry data to the map, wrapped in a named layer. GeoJSON is supported out of the box, and TopoJSON can be used if the library is available.

Geometry can be joined with data in a subsequent step. To do this, it must be possible to uniquely identify geometry objects by one of their properties. The property to use for data joining can be specified by passing the key option (default: 'id').

Note that like all asynchronous operations in mapmap, this method returns immediately and manages the loading of the resource internally to make sure the data is loaded before any subsequent operations. This means you can call other methods on the map immediately after calling geometry() with mapmap ensuring that the geometry is available.

Returns the map.

Examples

// Loads geometry from file 'counties.geojson'
// and assigns the value of field 'code' to each feature.
map.geometry('counties.geojson', 'code');

// Adds a layer named 'cities' with geometry loaded from file
// 'cities.geojson' and uses the field 'name' as key 
map.geometry('cities.geojson', {
    key: 'name',
    layers: 'cities'
});

Map.data(spec, [keyOrOptions])

Argument	Value
spec	A URL to a data file, or a Function to generate/transform data.
keyOrOptions	Either a String containing the key that should be used to join the data with geometry, or an options object containing options to set up the process.

options

Option	Default	Description
map	<function assigning the value of the given key field (or, by default 'id') as key of the object.>	The function to be used in the map step of the map/reduce algorithm. The function is passed a data object and an emitter function, and can use the emitter function to map data objects to keys.
reduce	<function emitting the last object of objects with identical keys.>	The function to be used in the reduce step of the map/reduce algorithm. The function is passed a key, an Array of values (as emitted by the map function), and an emitter function, and can use the emitter function to output the final result of the map/reduce algorithm.
geometryKey	'__key__' (The natural key calculated for geometry objects)	The property to use as a primary key to identify the geometry. Usually this has been set when calling map.geometry() and does not need to be modified.

Joins data with geometry. JSON and CSV formats are supported out of the box.

Data is joined with geometry by way of a shared key. Geometry objects with a given key will have the corresponding data object merged into their properties.

The data is processed using the map/reduce paradigm before being joined with the geometry, which allows for powerful data processing by specifiying the two functions used for the map and reduce steps as options.

Note that like all asynchronous operations in mapmap, this method returns immediately and manages the loading of the resource internally to make sure the data is loaded before any subsequent operations. This means you can call other methods on the map immediately after calling geometry() with mapmap ensuring that the geometry is available.

Returns the map.

Examples

// Loads geometry from file 'stat.csv'
// and join with geometries by field 'code'
map.data('stat.csv', 'code');

Map.meta(metadata)

Argument	Description
metadata	An object containing metadata descriptors.

See Programming Guide

The object passed to metadata contains a number of wildcard patterns and their associated metadata descriptors. A metadata descriptor contains information about the field(s) matched by the pattern, such as human-readable name, value ranges and domains for representational attributes. The metadata specification is a central place to store all information about data fields; This information is used in many places where data is transformed into a visual representation.

Metadata Fields

Field Name	Default	Description
label		Full human-readable label for the field, e.g. "Overall Unemployment Rate 2014". If not set, the field name is used.
valueLabel		Shorter field label to use in places where a value is shown, e.g. "Unemployment Rate". If not set, label is used.
valueUnit	null	A unit to print after textual representations of the value, e.g. 'Persons' or 'm²'.
scale	'quantize'	The scale to use for transforming the value. Either the name one of D3's scales or a function transforming an input value into an output value.
domain		Array containing the domain of values for the field. If not set, for numeric scales the min/max values of the actual data are used, for ordinal scales all values present are used as domain.
numberFormat	'.01f'	A specifier string for D3's Number formatting function or a function taking a number and returning a string. (Note that 'd' ignores non-integer values, so if you want to round float values you have to use '0f'.)
colors	Colorbrewer YlGnBu[6]	Array containing the output domain for color values
valueLabels		For ordinal data, one entry for each value in domain. The human-readable representation of the value.
undefinedValue	''	The value of the field if not present in the source data. By default, the field is assigned the empty string as a value; If you want to retain undefined values, set it to null or undefined.
undefinedLabel	'no data' (For en locale)	The textual representation of the field value if its value is equal the undefinedValue. This will be shown in tooltips etc. The default value is taken from the locale's undefinedLabel field, so this will respect the chosen locale.
undefinedColor	'transparent'	The color value to be used if the field is undefined.

Additional metadata fields can be defined and used by applications or plug-ins.

[Documentation in Progress... Use the source, Luke! ]