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)

A single combination of keys and values for a pair of variable-year is a d3.map. A mapper can be constructed from different data representations such as array, d3.map, or another d3.atlas.mapper and generally gives back a d3.map with specific coordinates that you can build your visualization with. A mapper is not a static object and can be updated over time.

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 of objects representation. The array can be for instance produced by d3.csv. Each object is a row containing all variable year combinations for a specific key:

[
  {
    "variable_year": value,
    "variable_year": value,
    "variable_year": value,
    "id": "key"
    },
  {
    "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".

# mapper.keys()

Returns an array of string keys for every entry in this mapper. The order of the returned keys is arbitrary. Keys are shared by all variable year combinations in the mapper.

# mapper.variables()

Returns an object of all variable year combinations in this mapper, in the form:

{
  variable1: [year1, year2, year3],
  variable2: [year1, year2, year3],
  variable3: [year1, year2, year3]
}

# mapper.get(variable[,year])

Returns a d3.map containing all values for the specified variable and year. If year is unspecified, return the d3.map for the null year.

# mapper.menu()

Returns the (d3.mapper.menu)[Menu] object attached to this mapper. The menu object allows two-way binding between UI's select elements and this mapper.