@chartshq/muze

v2.0.0

Published

3 years ago

Composable visualisation library for web with a data-first approach

Downloads

0High
0Medium
0Low

charts.com

muze svg vector graphics data-visualization visualization renderer relational algebra relation webassembly

What is Muze?

Muze is a free data visualization library for creating exploratory data visualizations (like Tableau) in browser, using WebAssembly. It uses a layered Grammar of Graphics (GoG) to create composable and interactive data visualization for web. It is ideal for use in visual analytics dashboards & applications to create highly performant, interactive, multi-dimensional, and composable visualizations.

It uses a data-first approach to define the constructs and layers of the chart, automatically generates cross-chart interactivity, and allows you to over-ride any behavior or interaction on the chart.

Muze uses an in-browser DataModel to store and transform data, and control the behaviour of every component in the visualization, thereby enabling creating of complex and cross-connected charts.

Features

🍗 Build complex and interactive visualizations by using composable layer constructs.
🔨 Use rich data operators to transform, visualize and interact with data.
👯 Define custom interactions by configuring physical behavioural model and side effect.
✂️ Use css to change look and feel of the charts.
☀️ Have a single source of truth for all your visualization and interaction controlled from data.
🔩 Integrate easily with your existing application by dispatching actions on demand.
🚀 Uses WebAssembly for handling huge datasets and for better performance.

Installation

CDN

Insert the muze build and the required CSS into the <head>:

<link href="https://cdn.jsdelivr.net/npm/@chartshq/[email protected]/dist/muze.css" rel="stylesheet">
<script src="https://cdn.jsdelivr.net/npm/@chartshq/[email protected]/dist/muze.js" type="text/javascript"></script>

NPM

Install muze from NPM:

$ npm install @chartshq/muze

Then you need to add a webpack plugin copy-webpack-plugin to copy some required muze files to your output dist or build folder.

npm install [email protected] --save-dev

And then within your webpack configuration object, you'll need to add the copy-webpack-plugin to the list of plugins, like so:

const path = require("path");
const CopyWebpackPlugin = require('copy-webpack-plugin');

module.exports = {
  plugins: [
    new CopyWebpackPlugin([
      {
        // Provide your node_modules path where @chartshq/muze
        // package is installed.
        from: path.resolve("<your_node_modules_path>", "@chartshq/muze/dist"),
        to: '.'
      },
    ]),
  ]
}

You also can checkout our muze-app-template to try out the Muze quickly through a boilerplate app.

Getting Started

Once the installation is done, please follow the steps below:

Prepare the data and the corresponding schema:

// Prepare the schema for data.
const schema = [
  {
    name: 'Name',
    type: 'dimension'
  },
  {
    name: 'Maker',
    type: 'dimension'
  },
  {
    name: 'Horsepower',
    type: 'measure',
    defAggFn: 'avg'
  },
  {
    name: 'Origin',
    type: 'dimension'
  }
]

// Prepare the data.
const data = [
   {
    "Name": "chevrolet chevelle malibu",
    "Maker": "chevrolet",
    "Horsepower": 130,
    "Origin": "USA"
  },
  {
    "Name": "buick skylark 320",
    "Maker": "buick",
    "Horsepower": 165,
    "Origin": "USA"
  },
  {
    "Name": "datsun pl510",
    "Maker": "datsun",
    "Horsepower": 88,
    "Origin": "Japan"
  }
]

Import muze as follows:

If you are using the npm package, import the package and its CSS file.

import muze from '@chartshq/muze';
import "@chartshq/muze/dist/muze.css";

If you are using CDN, use it as follows:

const muze = window.muze;

Create a DataModel and a basic chart:

// As the muze and DataModel are asynchronous, so we need to
// use async-await syntax.
async function myAsyncFn() {
  // Load the DataModel module.
  const DataModel = await muze.DataModel.onReady();
  
  // Converts the raw data into a format
  // which DataModel can consume.
  const formattedData = await DataModel.loadData(data, schema);

  // Create a new DataModel instance with
  // the formatted data.
  let dm = new DataModel(formattedData);
  
  // Create a global environment to share common configs across charts.
  const env = await muze();
 
  // Create a new canvas instance from the global
  // environment to render chart on.
  const canvas = env.canvas();

  canvas
  .data(dm) // Set data to the chart.
  .rows(["Horsepower"]) // Fields drawn on Y axis.
  .columns(["Origin"]) // Fields drawn on X axis.
  .mount("#chart"); // Specify an element to mount on using a CSS selector.
}

myAsyncFn()
  .catch(console.error.bind(console));

Documentation

You can find detailed tutorials, concepts and API references at our Documentation.

What has changed?

Muze 2.0.0 is now powered by WebAssembly bringing in huge performance improvement over the previous versions. The JavaScript version has been deprecated and no active development will take place in that version - but we'll fix critical bugs as and when raised in GitHub.

This version of Muze brings in power of WebAssembly for handling large datasets with ease, along with frictionless interaction and rendering. In addition, the data loading part in WebAssembly version is asynchronous, as opposed to being synchronous in the JavaScript version. Further, the WebAssembly version is free but only available as a compiled binary, whereas the JavaScript version is free and open-source (MIT).

You can visit the deprecated JavaScript version here https://github.com/chartshq/muze-deprecated

Migrating from previous versions of Muze

Now the Muze became asynchronous as opposed to being synchronous in the previous JavaScript version.

Changed APIs

Creating Env

Muze deprecated version:

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

Latest version:

(async function () {
  const env = await muze();
  const canvas = env.canvas();
})();

dispatchBehaviour

Muze deprecated version:

canvas.firebolt().dispatchBehaviour('highlight', {
  criteria: {
    Maker: ['ford']
  }
});

Latest version :

In the current version, the identifiers needs to be passed in dimensions object or range object if it is measure or temporal field.

// Dispatch highlight behaviour on data plots having maker as ford
canvas.firebolt().dispatchBehaviour('highlight', {
  criteria: {
    dimensions: {
      Maker: ['ford']
    }
  }
});

// Dispatch highlight behaviour on data plots having Acceleration
// between 20 and 50.
canvas.firebolt().dispatchBehaviour('highlight', {
  criteria: {
    range: {
      Acceleration: [20, 50]
    }
  }
});

Support

Please raise a Github issue here.

Roadmap

Please contribute to our public wishlist or upvote an existing feature at Muze Public Wishlist & Roadmap.

License

Custom License (Free to use)