Creating scatter plots

Note: Where possible, use qlik-embed and qlik/api rather than this framework.

The scatter plot uses bubbles or dots to represent values of two or three measures over a dimension. The first measure is for bubble’s position on the horizontal axis, the second measure is for the bubble’s position on the vertical axis, and the third measure (if any) is for the bubble’s size. The scatter plot is normally used to observe relationships among measures.

Learn more about the scatter plot chart, or review the scatter plot chart API specification.

// Configure nucleus
const nuked = window.stardust.embed(app, {
  context: { theme: "light" },
  types: [
    {
      name: "scatterplot",
      load: () => Promise.resolve(window["sn-scatter-plot"]),
    },
  ],
});
// Rendering a scatter plot on the fly
nuked.render({
  type: "scatterplot",
  element: document.querySelector(".scatterplot"),
  fields: [
    "Alpha",
    "=Sum(Expression1)",
    "=Sum(Expression2)",
    "=Sum(Expression3)",
  ],
  options: {
    direction: "ltr",
    freeResize: true,
  },
  properties: {
    color: { mode: "byDimension" }, // overrides default properties
  },
});

Options

direction - ltr/rtl
freeResize - in conjunction with snapshotData on layout, lets the chart ignore size set on snapshotData

Requirements

Requires @nebula.js/stardust version 2.3.0 or later.

Installing

If you use npm: npm install @nebula.js/sn-scatter-plot. You can also load through the script tag directly from https://unpkg.com.

More examples

Color bubbles by an expression

nuked.render({
  element: document.getElementById("object"),
  type: "scatterplot",
  fields: ["Alpha", "=Sum(Expression2)"],
  properties: {
    qHyperCubeDef: {
      qMeasures: [
        {
          qDef: {
            qDef: "Sum(Expression1)",
          },
          qAttributeExpressions: [
            {
              // Insert color expression
              qExpression:
                "if(sum(Expression2) > 0.0096*sum(Expression1), 'red', 'green')",
              id: "colorByExpression",
            },
          ],
        },
      ],
    },
    color: {
      auto: false,
      mode: "byExpression",
      expressionIsColor: true,
    },
  },
});

nuked.render({
  element: document.getElementById("object"),
  type: "scatterplot",
  fields: ["Alpha", "=Sum(Expression1)", "=Sum(Expression2)"],
  properties: {
    navigation: true,
  },
});

Binned data is turned on automatically if there are more than 1000 data points

When zoomed in or panned outside of the home view, the chart shows an interactive mini map and home button to help with navigating and resetting the view.

nuked.render({
  element: document.getElementById("object"),
  type: "scatterplot",
  fields: ["TransID", "=Sum(Expression1)", "=Sum(Expression2)"],
  properties: {
    compressionResolution: 2, // queryLevel of bins, smaller number <-> more points per bin
  },
});

Best fit line can be turned on

Supported types:

Linear
Average
Second degree polynomial
Third degree polynomial
Forth degree polynomial
Exponential
Logarithmic
Power

const nuked = window.stardust.embed(app, {
  context: { theme: "light" },
  types: [
    {
      name: "scatterplot",
      load: () => Promise.resolve(window["sn-scatter-plot"]),
    },
  ],
  flags: { BEST_FIT_LINE: true }, // Still experimental
});

nuked.render({
  element: document.getElementById("object"),
  type: "scatterplot",
  properties: {
    qHyperCubeDef: {
      qDimensions: [
        {
          qDef: {
            qFieldDefs: ["Alpha"],
          },
        },
      ],
      qMeasures: [
        {
          qDef: {
            qDef: "Sum(Expression1)",
          },
        },
        {
          qDef: {
            qDef: "Sum(Expression2)",
          },
          qTrendLines: [
            {
              qType: "LINEAR",
              qXColIx: 1, // The column in the hypercube to be used as x axis.
              style: {
                autoColor: true,
                dashed: true,
                lineDash: "8, 4",
              },
            },
          ],
        },
      ],
    },
  },
});

Scatter plot plugins

A plugin can be passed into a scatter plot to add or modify its capability or visual appearance. A plugin needs to be defined before it can be rendered together with the chart.

// Step 1: define the plugin
const pointPlugin = {
  info: {
    name: "point-plugin",
    type: "component-definition",
  },
  fn: ({ layout, keys }) => {
    const componentDefinition = {
      key: keys.COMPONENT.POINT,
      type: "point",
      settings: {
        strokeWidth: "2px",
        stroke: "black",
        size: (d) => getSizeInLogarithmScale(d, layout),
        fill: (d) => getColorBasedOnMedian(d),
      },
    };
    return componentDefinition;
  },
};

// Step 2: passing the plugin definition into the render function
nuked.render({
  type: "scatterplot",
  element: document.querySelector(".scatterplot"),
  properties: chartProperties,
  plugins: [pointPlugin],
});

The plugin definition is an object, with two properties info and fn. The fn returns a picasso.js component. To build this component, some important chart internals are passed into the argument object of fn.

// Structure of the argument object of fn
const pluginArgs = {
    layout,
    keys: {
      SCALE:
        X,
        Y,
      },
      COMPONENT: {
        X_AXIS,
        Y_AXIS,
        POINT,
      },
    },
  };

With plugins, you can either add new components or modify existing components of the scatter plot.

Add new components

For example, a line component can be added on top of a scatter plot to highlight the slopes between data points.

// Definition of the line plugin
const linePlugin = {
  info: {
    name: "line-plugin",
    type: "component-definition",
  },
  fn: ({ keys }) => {
    const componentDefinition = {
      key: "new-linecomp",
      type: "line",
      data: {
        extract: {
          field: "qDimensionInfo/0",
          props: {
            x: { field: "qMeasureInfo/0" },
            y: { field: "qMeasureInfo/1" },
          },
        },
        sort: (a, b) => (a.x.value > b.x.value ? 1 : -1), // sort ascending
      },
      settings: {
        coordinates: {
          minor: {
            scale: keys.SCALE.Y,
            ref: "y",
          },
          major: {
            scale: keys.SCALE.X,
            ref: "x",
          },
        },
        layers: {
          line: {
            stroke: "red",
            strokeWidth: 3,
          },
        },
      },
    };
    return componentDefinition;
  },
};

Modify existing components

As an example, the positions and the appearance of the axes can be modified completely by plugins.

To override an existing component, fn should returns a picasso.js component that has the same key as the existing component (keys.COMPONENT.X_AXIS in this example)

// Definition of the x-axis plugin
const xAxisPlugin = {
  info: {
    name: "x-axis-plugin",
    type: "component-definition",
  },
  fn: ({ keys }) => {
    const componentDefinition = {
      type: "axis",
      key: keys.COMPONENT.X_AXIS,
      layout: {
        dock: "top",
      },
      settings: {
        labels: {
          fontFamily:
            'Cambria, Cochin, Georgia, Times, "Times New Roman", serif',
          fontSize: "15px",
          fill: "red",
        },
        line: { stroke: "green", strokeWidth: 2 },
        ticks: { stroke: "blue", strokeWidth: 2 },
      },
    };
    return componentDefinition;
  },
};

// y-axis plugin can be defined with similar code
// ...

More details can be found in the examples folder of the sn-scatter-plot repository: https://github.com/qlik-oss/sn-scatter-plot

Plugins disclaimer

The plugins API is still experimental.
It is not guaranteed that the chart is compatible with all different settings, especially when modifying existing components.

Options
Requirements
Installing
More examples
Scatter plot plugins