-
-
Notifications
You must be signed in to change notification settings - Fork 1.8k
Models
Since most (D3) layouts operate on specific data structures (e.g. hierarchies for Bubble Charts or nodes-links for Force-directed Graphs), RAW provides an interface (both logical and graphical) to let users transform the data into the appropriate structure required by the chart. This can be done through models. In short, a model transforms data records into the 'something else' charts need to work with. Differently from the native JavaScript map function (which always creates a one-to-one map), models can return any sort of object (i.e. arrays, objects, numbers, strings...). RAW will create the necessary GUI elements to let the users decide which dimensions using within the transformation process.
raw.model()
Constructs a new model. A model works through a map function and one or more map dimensions. The map function takes the original data (records) in input and transform them into the structure required by the chart. Model dimensions define those transformation variables needed to be exposed to - and controlled by - the user.
model(records)
Applies the model on the data, by running the map function to the records. Within the RAW application there is no need to directly call the model, since it will be automatically called before the chart, passing it the structured data.
model.map([function])
If function is specified, sets the map function to the specified function. If function is not specified, returns the current map function. The map function is invoked for the (whole) input data and can return any value needed by the chart (usually arrays or objects).
The default map function is the identity function and thus returns the input data.
function map(data) {
return data;
}model.dimensions()
Returns the dimensions associated to the model. Dimensions are stored as a d3.map object.
model.clear()
Reset all the dimensions in the model by calling the clear method of each dimension.
model.dimension([name])
Constructs a new dimension. Dimensions are used to expose map variables to the users, allowing them to choose the appropriate column(s) to build the structure. For each dimension in the model, RAW creates a GUI element which allows the user to associate the dimension with one or more columns in the data.
If name is specified, it will be used to identify and retrieve the dimension. Otherwise, a default unique identifier will be created.
dimension(object)
If object is specified, returns the value(s) for the column(s) associated to the dimension. In case of multiple columns, an array containing the corresponding value for each column will be returned.
If object is not specified, returns the column or the columns addociated with the dimensions.
Dimensions are meant to be called within the map function to access the columns chosen by the user and use them within the transformation process.
dimension.multiple([boolean])
If boolean is specified, enables or disables multiple columns accordingly. If boolean is not specified, returns the current multiple value. By default, this option is disabled and each dimension can be associated only to one column. When boolean is true users could associate any number of columns to the dimension.
dimension.types(types...)
If types is specified, forces the dimensions to accept only columns with those data types. Currently, the following data types are available: Number, String, Date. The types need to be listed as built-in Javascript classes (e.g. Number).
If types is not specified, returns the currently accepted types. By default all the previous data types are accepted.
dimension.title([text])
If text is specified, sets the title of the dimension to the specified text. If text is not specified, returns the current title. The default value is "Untitled". The title will be displayed in the GUI.
dimension.description([text])
If text is specified, sets the description to be displayed to the specified text. If text is not specified, returns the current description. The default value is null.
dimension.clear()
Reset the value of the dimension, by clearing its value.
Since most of the layouts share the same structures, RAW comes with some built-in models, ready to be used in new charts. While it is possible to modify these models (like any other model), by changing both their dimensions and their map function, they are meant to be used as they are.
var points = raw.models.points();
var chart = raw.chart()
.model(points)However, since often not all the dimensions in the model are needed by our charts, it is possible to remove them:
var points = raw.models.points();
// removing the color dimension
points.dimensions().remove('color');
var chart = raw.chart()
.model(points)Important! Be aware that removing the dimensions will not change their behavior within the map function but it will simply set their value to null and remove them from the GUI.
This model creates an array of points. Each point is an object with two coordinates (x and y) and three basic properties (size, label and color). This model is useful when the chart needs to work with points within a Carthesian coordinate system (e.g. Scatter Plots or Voronoi Tessellations).
raw.models.points(records)
Creates a new model to transform data records into an array of points.
x
Controls the X coordinate of the points. It can be associated only to a single Number columns.
y
Controls the Y coordinate of the points. It can be associated only to a single Number columns.
size
Controls the size of the points. It can be associated only to a single Number columns.
color
Controls the color of the points. It can be associated to a single column, of any type.
label
Controls the label of the points. It can be associated to one or more columns, of any type.
Movie,Genre,Production Budget,Total Domestic Box Office,Rating IMDB
Avatar,Action,425000000,760507625,"8,0"
Finding Nemo,Adventure,94000000,380529370,"8,1"
Ghostbusters,Comedy,30000000,238632124,"7,8"
Iron Man 3,Action,200000000,396702239,"7,6"
...
"Production Budget" as x
"Total Domestic Box Office" as y
"Genre" as color
"Movie" as label
[
{"x":425000000,"y":760507625,"size":1,"color":"Action","label":["Avatar"]},
{"x":94000000,"y":380529370,"size":1,"color":"Adventure","label":["Finding Nemo"]},
{"x":30000000,"y":238632124,"size":1,"color":"Comedy","label":["Ghostbusters"]},
{"x":200000000,"y":396702239,"size":1,"color":"Action","label":["Iron Man 3"]},
...
]The tree model allows the construction of trees (or hierarchies) data structures. This model can be used for those charts that operates with nested structures (e.g. Treemaps, Circle Packings, Dendrograms). The structure is constructed by defining the sequence of properties to be nested through the hierarchy dimension. Each leaf of the tree can than have a size a color and a label property. Moreover, for each branch and leaf of the tree it is possible to retrieve the corresponding level of nesting, through the class property.
raw.models.tree(records)
Creates a new model to transform data records into a hierarchical structure.
hierarchy
This dimension controls the hierarchy of properties the tree will be constructed through. The order of the columns matters since it defines whether a property is parent or child of the other. This dimension can be associated to one or more columns, of any type.
size
Controls the size of the leaves. Since the nested structure of the tree, this dimension can be used also to get the size of the branches too. It can be associated only to a single Number columns.
color
Controls the color of the leaves. It can be associated to a single column, of any type.
label
Controls the label of the leaves. It can be associated to one or more columns, of any type.
Movie,Genre,Production Budget,Total Domestic Box Office,Rating IMDB
Avatar,Action,425000000,760507625,"8,0"
Iron Man 3,Action,200000000,396702239,"7,6"
Finding Nemo,Adventure,94000000,380529370,"8,1"
Ghostbusters,Comedy,30000000,238632124,"7,8"
...
"Genre", "Movie" as steps
"Production Budget" as size
"Genre" as color
"Movie" as label
{
"children":
[
{
"name":"Action",
"class":"Genre",
"children":
[
{
"name":"Avatar",
"class":"Movie",
"size":425000000,
"color":"Action",
"label":
[
"Avatar"
]
},
{
"name":"Iron Man 3",
"class":"Movie",
"size":200000000,
"color":"Action",
"label":
[
"Iron Man 3"
]
},
...
]
}
...
]
}This model constructs a graph structure. It can be used for charts that works with node-link inputs (e.g. Sankey/Alluvial Diagrams, Force Directed Graphs). The nodes and the links are defined through the steps dimension: nodes are created for each single value in the columns, while links are constructed through the Carthesian product between each dimension and the next one.
The output structure is an object containing two arrays: nodes and links. Each node has a name property corresponding to the single value of the column and a group property which indicates the column it belongs to. Each link has a source property containing the index (position) of the source node in the nodes array and a target property for the target node. Moreover, each link has a value property defining the weight of the link. Such a value can be controlled through the size dimension. By default, the value corresponds to the occurrencies of the source-target pair (i.e. how many times in the data the source and target values appear on the same row).
raw.models.graph(records)
steps
Controls the size of the links. It can be associated to two or more columns, of any type.
size
Controls the size of the links. It can be associated only to a single Number columns.
Movie,Genre,Production Budget,Total Domestic Box Office,Rating IMDB
Avatar,Action,425000000,760507625,"8,0"
Finding Nemo,Adventure,94000000,380529370,"8,1"
Ghostbusters,Comedy,30000000,238632124,"7,8"
Iron Man 3,Action,200000000,396702239,"7,6"
...
"Genre", "Movie" as steps
{
"nodes":
[
{"name":"Action","group":"Genre"},
{"name":"Adventure","group":"Genre"},
{"name":"Comedy","group":"Genre"},
...
],
"links":
[
{"source":0,"target":6,"value":1},
{"source":0,"target":10,"value":1},
{"source":0,"target":11,"value":1},
{"source":0,"target":16,"value":1},
...
]
}