Scatter Charts

Overview

Scatter Chart Types

Create a standard, horizontally-oriented, or trellis scatter chart.

Scatter Chart

Add a type attribute to your chart object and set the chart type to scatter. Without further modification, a scatter chart with a single dataset looks like this:

{
  type: "scatter",
}

Horizontal Scatter Chart

A horizontal scatter chart is specified by the hscatter value. With this chart type, the axes are switched so that the x-axis runs vertically and the y-axis runs horizontally. They are especially useful when working with our horizontal mixed charts.

{
  type: "hscatter",
}

Trellis Scatter Chart

To create a trellis scatter chart, create a graphset array and place each dataset in its own chart object. You can adjust the spacing between your axis line(s) and plotted data using the offset-start and offset-end attributes. Simply add them to your scale-x and/or scale-y objects (discussed further in Scales section below), and provide a pixel value.

{ //shortened for brevity- click on following scatter trellis chart demo for full configuration 
  graphset: [
    {
      type: "scatter",
      height: "50%",
      width: "50%",
      x: "0%",
      y: "0%",
      'scale-x': {
        'offset-start':5,   //To adjust the spacing between your axis line and beginning plotted data.
        'offset-end':5,     //To adjust the spacing between your ending plotted data and axis line.
        values: "0:10:1"   //To set your minimum, maximum, and step scale values.
      },
      'scale-y': {
        'offset-start':5,
        'offset-end':5,
        values: "0:100:50"
      },
    },
    {
      type: "scatter",
      height: "50%",
      width: "50%",
      x: "50%",
      y: "0%",
      'scale-x': {
        'offset-start':5,
        'offset-end':5,
        values: "0:10:1"
      },
      'scale-y': {
        'offset-start':5,
        'offset-end':5,
        values: "0:100:50"
      },
    },
  ]
}

Data

Scatter charts support single or multiple datasets, all contained inside the series array. Each dataset is configured as an array of arrays where users specify both their x- and y-axis values. The scatter chart displayed below contains five datasets.

{ //shortened for brevity- click on following scatter chart demo for full configuration 
  series: [
    {
      values: [
        [1,9],
        [2,15],
        [3,21],
      ]
    },
    {
      values: [
        [0.9,3],
        [2.1,13],
        [3.5,25],
      ]
    },
  ]
}

Chart-Specific Properties

Once you've set up your chart's type and series data, you can next select your desired markers or incorporate a trendline to further clarify your scatter chart's data.

Cluster

Use the clustered attribute to set the entire plot to be placed within one key scale. The clusterIndex attribute sets which key scale to place the plot in. To offset the margin of the cluster, use clusterOffset. These attributes can be used within the plot or series object.

{
  plot: {
    clustered: true,
    clusterOffset: 10,
  },
  series: [{
    clusterIndex: 0,
  }]
}

Markers

Marker customization is useful for differentiating your datasets or adding emphasis to a particular one. We provide our own ZingChart markers for you to choose from, and also provide the functionality for you to create your own scatter chart markers.

ZingChart Markers

Create a marker object, add a type attribute, and specify your marker type. To apply globally, make your changes inside a plot object. To apply locally, make your changes inside of your desired series data object.

{
  plot: {
    marker: {
      type: "square"   /*specify your marker type globally
    }
  },
  series: [
    { /*specify your marker type locally in individual series objects/*
      //marker: {
        //type: "square" 
      //}
    }
  ]
}

ZingChart has over thirty different marker types, which you can toggle through in the following chart:

Custom Markers

You can also create your own custom markers. To do so, you'll need to add a background-image attribute to your markerobject and provide an image link to your custom marker contained in quotes.

You'll also need to add the following styling attributes:background-color (set to none), border-color (set to none), background-repeat (set to no-repeat), and shadow (set to false). You can also adjust the size of your markers by adding a size attribute.

{
  series: [
    {
      marker: {
        'background-image': "https://www.zingchart.com/resources/target.png", //Provide an image link for custom markers.
        'background-color': "none",
        'border-color': "none",
        'background-repeat': "no-repeat",
        shadow: false,
        size: 12
      }
    }
  ]
}

Trendlines

We provide users the functionality to incorporate trendlines into their scatter charts. There are two ways to add them: with a markers array or by creating a mixed scatter/line chart.

markers Array

Add a markers array to your scale-x and/or scale-y objects. In the array, create an object. You'll need to add a type attribute and set the value to line. You'll also need to add a range array, where you'll specify the beginning and ending points for your trendline. While a trendline can be drawn based on a visual estimate, you can also use your own functions or formulas to calculate your start and stop values.

{
  'scale-x': {
    markers: [
      {
        type: "line",
        range: [0,10],
        'line-style': "dashed"
      }
    ]
  },
  'scale-y': {
    markers: [
      {
        type: "line",
          range: [0,100],
          'line-style': "dotted"
      }
    ]
  },
}

Mixed Scatter/Line Chart

You can also add a trendline by creating a mixed scatter/line chart. With a scatter/line mixed chart, the advantage is that you can use the aspect attribute to specify your line type (e.g., to make a curved trendline with our spline value). You can also turn off the visibility of your line chart markers by adding a marker object, adding a visible attribute, and setting the value to false. Style your trendline using line styling attributes such as: line-width, line-style (solid, dotted, or dashed), and line-color.

{ //shortened for brevity- click on following line/scatter mixed chart demo for full configuration 
  type: "mixed",
  series: [
    {
      type: "scatter",
    },
    {
      type: "scatter",
    },
    {
      type: "line",
      aspect: "spline",
      marker: {
        visible: false
      },
      'line-width': 1,
      'line-style': "solid",
      'line-color': "black",
    }
  ]
}

Further Customization

You can next configure your scatter chart's scales, style your markers, and customize the appearance of your value boxes, tooltips, and legend.

Scales

Scatter charts generally have quantitative scales on both axes. Linear, logarithmic, and time-series scales are the most common, and we explain the basics on setting up those scale types below.

Linear Scale

Linear scales are ZingChart's default scale type. Your starting (or minimum), ending (or maximum), and step scale values are automatically calculated based on the data you provide. You can specify what you want your minimum, maximum, and step scale values to be by adding a values attribute to your scale-x and/or scale-y object. Provide your min/max/step inside a string separated by colons.

{
  'scale-x': {
    values: "0:10:1",    //To specify your minimum, maximum, and step scale values.
    decimals:1
  },
  'scale-y': {
    values: "0:100:50",
  },
}

Logarithmic Scale

Logarithmic scales are also commonly used with scatter charts, typically on the y-axis (scale-y object). This scale type is useful when working with very large data ranges. Create one by adding a progression attribute to your scale object and setting the value to log. Next, add a log-base attribute. Your base value can be Math.E (Euler's number, i.e., the base of natural logarithms) or 10.

{
  'scale-y': {
    progression: "log",
    'log-base':10,
    'thousands-separator': ", "
  },
}

Time-Series Scale

Time-series scales are typically displayed on the x-axis (scale-x object) on scatter charts. This scale type is used to display increments of time, which can range from milliseconds to years. To create one, add a min-value attribute, step attribute, and transform object to your scale object.

For the min-value and step, you'll need to specify your minimum and step scale values in Unix time, in milliseconds. (You can calculate your Unix timestamps with online conversion tools such as Epoch Converter.)

The transform object will then convert your Unix timestamps into a readable format. Insert a type attribute, and set the value to date. Next, add an all attribute. You can specify how you want your scale formatted by using our ZingChart tokens contained in a string.

{
  utc: true,
  timezone: -8,
  'scale-x': {
    'min-value':1425196800000,
    step: "2day",
    transform: {
      type: "date",
      all: "%m/%d/%y"
    }
  },
}

Marker Styling

You can style your scatter chart's markers by modifying their color, size, width, and more. In your marker object, use styling attributes such as background-color and size to modify your marker fill's color and size. You can also modify your border's color and width with the border-color and border-width attributes. Apply these changes globally in your plot object or locally in the appropriate series object.

{
  plot: {
    marker: { //Apply marker styling globally.
      'background-color': "#00FFFF",
      size:7,
      'border-color': "#009999",
      'border-width':2,
      'line-color': "#009999",
      'line-width':2,
    }
  },
  series:[
      {
        marker: {  //Apply marker styling locally.
        type: "diamond",
        'background-color': "#FF0066",
        size:15,
        'border-color': "#FFFF66",
        'border-width':3
        }
      },
  ]
}

Value Boxes

Value boxes are not visible on scatter charts by default. To include them in your chart, add a value-box object to your plot object. You can style and format them, as well as incorporate rules to force certain value boxes to show under certain conditions (e.g., to highlight outliers, notable data points, or minimum/maximum values).

In the example chart below, rules were used to display values greater than or equal to 90 and less than or equal to 10.

{
  plot: {
    'value-box': {
      rules: [
        {
          rule: "%v >= 90",
          'font-color': "green"
        },
        {
          rule: "%v >10 && %v < 90",
          visible: false
        },
        {
          rule: "%v <= 10",
          'font-color': "red"
        }
      ]
    }
  },
}

Tooltips

To enable and style tooltips, add a tooltip object to your chart object. You can turn their visibility on or off with a visible attribute. Set the value to true (default) or false.

Specify what text appears with a text attribute. Place your desired text inside a string. ZingChart tokens, such as %v and %t, can be used here. Style your tooltips (font, background, borders) with attributes such as font-color, font-family, background-color, border-color, border-width, and more.

{
  tooltip: {
    text: "%t: %v",
    'font-color': "black",
    'font-family': "Georgia, serif",
    'background-color': "white",
    'border-color': "black",
    'border-width':2
  },
}

Legend

Include a legend in your scatter chart by adding a legend object to your chart object. Not only do legends help users better understand your chart data, it allows them to interact with that data. You can toggle plots on and off by clicking on the legend marker that a plot is associated with (see our example chart below).

Specify the layout and position of your legend using the layout and position attributes; style your text within an item object; and style your legend markers within a marker object.

{
  legend: {
    layout: "5x1",
    position: "97% 73%",
    item: {
      'font-color': "brown",
      'font-family': "Georgia"
    },
    'background-color': "white",
    alpha: 0.5,
    'border-color': "none",
    shadow: false,
    marker: {
      type: "inherit"
    }
  },
}