Legends

In this section, we will get a fair understanding of how legend work in Muze. There are three retinal encodings channels that Muze uses to assign fields to encode more information to visualization, which are:

  • color
  • shape
  • size

Every time we provide a field to any of the retinal encoding channel, Muze creates a scale internally and then draw a legend form the scale automatically.

Color Legend

Color legend is created when color scale is created by assigning a variable in color encoding channel.

Discrete

A discrete legend is creates when we assign a dimension to color channel. Thus, a categorical (values which can't be interpolated ) domain is created for the scale. Each item in the legend represents a unique dimensional value.

For example, if we needed to see the distribution of Horsepower and Displacement by Origin, and instead of faceting the chart, we could add an encoding for Origin using the color channel.

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(700)
		.height(400)
        .rows(['Horsepower'])
        .columns(['Displacement'])
  		.color('Origin')
  		.detail(['Name'])
		.mount('#chart-container') /* Attaching the canvas to DOM element */

Notice that in order to indicate what each color in the chart represents, a legend is created. Thus the legends act as the references for the color retinal encoding.

Gradient color legend

When a measure field is assigned to the color encoding channel, we get a gradient color legend. A gradient legend maps continuous domain to a continuous range of interpolated colors based on the range of colors provided.

We consider the distribution of Horsepower vs the Weight (in lbs). As such, if we wanted to see how good the mileage on those cars are, we can color them by Miles_per_Gallon, which will give us an indication of the optimal Horsepower and Weights which give efficient Mileage:

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(800)
		.height(400)
        .rows(['Horsepower'])
        .columns(['Weight_in_lbs'])
  		.color('Miles_per_Gallon')
  		.detail(['Name'])
		.mount('#chart-container') /* Attaching the canvas to DOM element */

Notice that the colors of the points start from a whitish color to a deep blue color, indicating the increase in the values of the color field (i.e., Miles_per_Gallon).

Step color legend

The step color legend is a variant of the gradient legend, wherein the range is a discrete set of colors for each step created in the domain. You can specify the number of steps or the stops itself:

We consider the distribution of Horsepower vs the Weight_in_lbs. As such, if we wanted to see how good the mileage on those cars are, we can color them by Miles_per_Gallon. But this time, we'll group the range of mileage in 5 buckets to get a sense of ranges of Horsepower and Weight_in_lbs values which can provide high Miles_per_gallon.

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(800)
		.height(400)
        .rows(['Horsepower'])
        .columns(['Weight_in_lbs'])
    	.color({
  			field: 'Miles_per_Gallon',
  			step: true,
  			stops: 5
		})
  		.detail(['Name'])
		.mount('#chart-container') /* Attaching the canvas to DOM element */

Customizing number of stops and color

For a gradient legend you can specify the stops of a scale and color for those stops

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(800)
		.height(400)
        .rows(['Horsepower'])
        .columns(['Weight_in_lbs'])
  		.color({ 
			field: 'Miles_per_Gallon',
  			stops: 3,
  			range: ['#ff5722', '#009688']
		})
  		.detail(['Name'])
		.mount('#chart-container') /* Attaching the canvas to DOM element */

Alternatively for step legend also you can change the stops

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(800)
		.height(400)
        .rows(['Horsepower'])
        .columns(['Weight_in_lbs'])
  		.color({
  			field: 'Miles_per_Gallon',
  			step: true,
  			stops: [15, 30]
		})
  		.detail(['Name'])
		.mount('#chart-container') /* Attaching the canvas to DOM element */

Shape and size legend

Shape and size retinal encoding also works in the similar way. Only difference is shape retinal encoding channel can't take a measure field as value. Learn more about shape and size retinal encoding here.

Legend Configurations

Legend also has its own set of configurations, which are applicable for all the legend components:

position

We can position the legend to TOP, LEFT, RIGHT or BOTTOM of the canvas:

canvas
    .config({
        legend: {
            position: 'bottom'
        }
    })
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(700)
		.height(400)
        .rows(['Horsepower'])
        .columns(['Displacement'])
  		.color('Origin')
  		.config({
			legend: { 
              	postion: 'bottom',
              	color: { /* for color legend */
              		title: {
                    	text: 'Country'
                    }
              	}
            }
		})
  		.detail(['Name'])
		.mount('#chart-container') /* Attaching the canvas to DOM element */

Apart from the configurations applicable to all the legend components, each legend takes in configurations which are applicable for each legend separately:

show

You can choose to show or hide a particular legend

item

You can customise the width, height, and positions of each text and shape in a legend

margin/border/padding

You can add your own values of margin, borders and padding that will be applied on the legend

title

You can provide a title to a particular legend