Creating your first visualisation with Muze

Muze enables you to create composable, complex & interactive data visualizations for web easily.

In this tutorial, we'll guide you step-by-step on how to create your first few charts using Muze.

Prerequisite

You need to have muze installed before going ahead with this document. Refer this section for muze installation.

Steps to create a visualization

To create a visualization using Muze, the following steps are involved:

  1. Load your data in Muze DataModel
  2. Retrieve canvas from muze
  3. Provide fields in rows & columns for canvas which gets translated to visualization.

Preparing and providing data to Muze

Muze recognizes DataModel as first class source of data. To use Muze, you need to load your data and provide to DataModel in one of the 3 formats:

  • Delimited data (e.g., CSV or TSV)
  • Flat JSON structure
  • JavaScript 2D Arrays

In this article we will be using cars.json data for illustration purpose.

You can load this JSON data via a network call (AJAX etc.) or by importing an existing dataset present in your JavaScript source file. For instance, we are using the loadData to load the data. This function is written by us and only available in this page.

DataModel needs a data and schema. Schema identifies variables from data and defines characteristics of the variables. Variables are nothing but the columns in a tabular data format. If you see cars.json data, you will see there are 10 variables (columns in tabular format) present in the data (for a FlatJSON format, those columns becomes keys of an object).

Here's how the loaded DataModel looks like, when converted to a table

main
run-button
run-button
reset-button
Promise.all([loadData('/static/cars.json'), loadData('/static/cars-schema.json')]).then((resp) => {
  	const data = resp[0];
  	const schema = resp[1];
  	const DataModel = muze.DataModel;
	const dm = new DataModel(data, schema);
  
  	printDM(dm);
})
logo

Utility methods are available in the page only

Methods like loadData, printDM are utility method we created for ease of use. These methods are available only in muze's documentation and example page only.

logo

Field, variable, column are same

Through out the document we talk about different variables from data getting assigned to x-axis, y-axis, color-axis etc. Sometime variables, fields and columns are used interchangeably.

Variables are from raw data which gets translated to fields in DataModel. But all of these are just columns of a tabular data format.

Setting up a canvas

To create a visualization using Muze, you first need to create an environment, and then a canvas. A canvas is a logical container for your visualization, and needs to provided a width and height. The code for same is shown below:

const env = muze(); //Initialize the Muze environment
const canvas = env.canvas(); //Create a container canvas
canvas
    .width(600) //Specify width of visualization (canvas) in pixels
    .height(450) //Specify height of visualization (canvas) in pixels

Creating the visualization

Now that we've a canvas and instance of DataModel ready, we will begin visualizing this data. Muze provides constructs for you to assign variables from data to encodings channels for visualization.

logo

Encoding channels

Encodings are nothing but x-axis, y-axis, facets, color-axis, shape-axis, size-axis. You can assign variables from data (fields from DataModel) in encoding channel. Like you can assign Miles_per_gallon to x-axis, and Year to y-axis to get a Mileage vs Year chart

Muze expects fields from DataModel to be provided to the canvas as either rows or columns. In addition, it needs a DOM node where you want your visualization to be mounted.

Let's create the chart below. The code for it is present after the chart.

main
run-button
run-button
reset-button
// DataModel instance is created from https://www.charts.com/static/cars.json data,
// https://www.charts.com/static/cars-schema.json schema and assigned to variable dm.

const env = muze();
const canvas = env.canvas();

canvas
  		.data(dm)
		.width(600)
		.height(400)
		.rows(['Miles_per_Gallon']) /* Gets plotted on y-axis */
		.columns(['Year'])  /* Gets plotted on x-axis */
		.mount('#chart-container') /* Attaching the canvas to DOM element */

One thing you may be wondering is - how did Muze plot a line chart, when you didn't specify anything? Well, Muze understands the possible options for the set of fields provided and based on that, it automatically renders the most viable chart for it, in this case, since Year is a temporal field, it's best to plot a line chart (to show trend across time). You can also change plot type, if you want to override system defined plot type. This tutorial explains more about rendering different plot types.

Configure a visulization

Once you create your first visulization, configuring a visualization is just tweaking different encoding channels with different variable.

Changing the above chart to a multi-series chart (adding another encoding)

We can transform our previous chart (single-series) into a multi-series line chart by adding the color encoding. It accepts a field from the DataModel instance by which it colors the lines, as shown below:

main
run-button
run-button
reset-button
// DataModel instance is created from https://www.charts.com/static/cars.json data,
// https://www.charts.com/static/cars-schema.json schema and assigned to variable dm.

const env = muze();
const canvas = env.canvas();

canvas
  		.data(dm)
		.width(600)
		.height(400)
		.rows(['Miles_per_Gallon'])
		.columns(['Year'])
  		.color('Origin') /* Field using which the lines will be colored */
		.mount('#chart-container')

Notice how we get three lines (one for each coutry), each line representing an Origin in the multi line chart.

Changing chart from multi-series to multi-variable

Instead of coloring each series by Origin, we could even split our visualization by a particular field into multiple rows (panels). Check out the code right after the visualisation to see how to do it.

main
run-button
run-button
reset-button
// DataModel instance is created from https://www.charts.com/static/cars.json data,
// https://www.charts.com/static/cars-schema.json schema and assigned to variable dm.

const env = muze();
const canvas = env.canvas();

canvas
  		.data(dm)
		.width(600)
		.height(450)
		.rows(['Origin', 'Miles_per_Gallon']) /* The viz gets faceted by Origin field */
		.columns(['Year'])
		.mount('#chart-container')

What we have done is called faceting. The above is an example of faceting by rows.

Let's add one more variable to chart

Let's add one more variable, Cylinders, to the chart, to see how Muze handles it. We are going to take the above example and going to add a color encoding by Cylinders. This will create a multi-panel + multi-series line chart for each of the splits made in the rows:

main
run-button
run-button
reset-button
// DataModel instance is created from https://www.charts.com/static/cars.json data,
// https://www.charts.com/static/cars-schema.json schema and assigned to variable dm.

const env = muze();
const canvas = env.canvas();

canvas
  		.data(dm)
		.width(600)
		.height(450)
		.rows(['Origin', 'Miles_per_Gallon'])
		.columns(['Year'])
  		.color('Cylinders')
		.mount('#chart-container')

So you just saw how easy it is to create complex visualizations with Muze, without having to change anything in your visualization code. All you had to do was map the right fields from instance of DataModel to right encoding channels of Muze .

Wrapping up

We learnt how to make a simple chart using two fields from the data. Then, we added retinal encodings (color) to the plot to create a multi series chart. Then, we added fields to canvas which created multi panel visualizations.

All these are just the tip of the iceberg. Muze has the power to do a lot more besides changing plot types or adding encodings.

In order to fully understand the power of data driven visualisations, you can go through the concepts of Muze. If you wish to understand the DataModel and what other formats it supports or how it operates, read about the DataModel concepts.

From here you can read how you can get started with Muze using different data formats. You can also checkout the examples and then see here how you can use those examples in your application.