Mapper

Wiki ▸ API Reference ▸ Mapper

A mapper is a serialized collection of d3.map that allows asynchronous manipulation and built-in operations between maps. Think of a d3.map as a table with only two columns, keys and values. A d3.atlas.mapper is an extension that allows to create and delete columns dynamically, and adds a time or numerical series dimension to each column.

A mapper is a cube of data, in three dimensions:

• keys (object ids)
• variables (strings)
• years (numerical dimension)

Managing data with a mapper offers two advantages:

1. Asynchronous data loading. Interactive visualization with data series in d3 can result in long loading time. The typical way of loading data with d3 is to load everything before starting to visualize. This approach works for small datasets, but is too time consuming for large datasets. With d3.atlas.mapper, it is possible to load only the necessary data to start the visualization, and load the rest of the data series in the background while the first data is visualized. The data visualization appears more quickly in the browser. It is even possible to load new pieces of data on-demand, and update or get rid of obsolete parts of the data.
2. Between maps operations.

Create a mapper object with mapper = new d3.atlas.mapper()

# mapper.add(d3.map, variable,[, year])

Add a d3.map object to the mapper. The d3.map to add to the mapper and the variable (column) name variable (string) are required. If unspecified, year will default at null. Variable names are unique but can accept several year. year can take any numerical value. If the mapper is already populated in some way, the map.keys()must correspond to the existing mapper.keys().

# mapper.mergeWith(d3.atlas.mapper)

Merge the mapper with another mapper object, i.e. combine all their maps. If variable-year commbination exists in both mappers, the old map will be replaced by the new.

# mapper.array(array)

Add a series of maps to the mapper object, constructed form an array representation. The array can be for instance produced by d3.csv.

[
  0: {
    "variable_year": value,
    "variable_year": value,
    "variable_year": value,
    "id": "key"
    },
  1: {
    "variable_year": value,
    "variable_year": value,
    "variable_year": value,
    "id": "key"
    }
]

If they differ from default values, set the variable year separator and the id column name beforehand, like this:

mapper.ySeparator('mySeparator')
  .idColumn('myIdColumn')
  .array(myArray);

# mapper.ySeparator(string)

Set the variable year separator substring, when importing an array or a d3.map. The default variable year separator is "_".

# mapper.idColumn(string)

Set the id column name, when importing an array. The default id column name is "id".