scatterplot properties

Note: STABLE.
This API is reliable and breaking changes are unlikely.

scatterplot()

These are the properties used by Qlik Sense scatter charts.

Version history

Introduced 2.2

Properties

showTitles

Type: Boolean

Show title for the visualization.

Default: true.

showDetails

Type: Boolean

Sets if visualization details should be shown.

Default: false

title

Type: String | qStringExpression

Visualization title shown if "showTitles": true.

subtitle

Type: String | qStringExpression

Visualization subtitle shown if "showTitles": true.

footnote

Type: String | qStringExpression

Visualization footnote shown if "showTitles": true.

qHyperCubeDef

Type: Object

The hypercube definition used by most visualizations.

A subset of the properties available in the qHyperCubeDef is presented here. For complete documentation of all available properties, see Engine API: HyperCubeDef.

Properties

Name Type Description
qDimensions Array

Extends NxDimension, see Engine API: NxDimension.

Additional properties

Name Type Description
qDef Object

Extends NxInlineDimensionDef, see Engine API: NxInlineDimensionDef.

Additional properties

Name Type Description
autoSort Boolean

Set to automatically sort the dimension.

Default: true

cID String ID used by the client. Must be unique within the current chart.
othersLabel StringExpressionContainer
qAttributeDimensions Array

Extends NxAttrDimDef, see Engine API: NxAttrDimDef.

Additional properties

Name Type Description
id String

One of:

  • colorByAlternative: colors the chart using different dimensions. Can be used together with color.mode="byDimension" for attribute dimensions.
  • colorByExpression: used together with color.mode="byExpression".
qMeasures Array

Extends NxMeasure, see Engine API: NxMeasure.

Additional properties

Name Type Description
qDef Object

Extends NxInlineMeasureDef, see Engine API: NxInlineMeasureDef.

Additional properties

Name Type Description
autoSort Boolean

Set to automatically sort the measure.

Default: true

cID String ID used by the client. Must be unique within the current chart.
numFormatFromTemplate Boolean

When enabled, the number format to use can be selected from multiple predefined formats based on the desired type: number or date.

Default: true

isCustomFormatted Boolean Set to true to toggle off the default client formatting.
othersLabel StringExpressionContainer
qAttributeExpressions Array

Extends NxAttrExprDef, see Engine API: NxAttrExprDef.

Additional properties

Name Type Description
id String

One of:

  • colorByAlternative: colors the chart using different dimensions. Can be used together with color.mode="byDimension" for attribute dimensions.
  • colorByExpression: used together with color.mode="byExpression".
qLayoutExclude Object

 

customErrorMessage Object

Set to define custom error messages.

Name Type Description
calcCond String

Deprecated. Use qCalcCondition.qMsg instead.

Set to customize the calculation condition unfilled message.

refLine

Type: Object

Reference line settings for scatter charts. Can be set on X-axis and Y-axis separately.

Properties

Name Type Description
refLinesX Array

Properties

Name Type Description
show Boolean

Set to true to display this reference line.

Default: true

label String Reference line label.
color Integer

Deprecated. Use paletteColor instead.

Color.

Default: 3

paletteColor Object

Color information structure. Holds the actual color and index in palette.

Properties

Name Type Description
index Integer

Index in the palette. If a custom color, not in the palette, is being used, set index ti -1.

Default: 6

color String

Color as HEX string.

Mandatory if "index": "-1".

refLineExpr String
Name Type Description
label StringExpressionContainer Expression for the displayed value.
value ValueExpressionContainer Expression for the value used in the visualization.
cId String ID used by the client. Needs to be unique within the array of reference lines.
refLinesY Array

Properties

Name Type Description
show Boolean

Set to true to display this reference line.

Default: true

label String Reference line label.
color Integer

Deprecated. Use paletteColor instead.

Color.

Default: 3

paletteColor Object

Color information structure. Holds the actual color and index in palette.

Properties

Name Type Description
index Integer

Index in the palette. If a custom color, not in the palette, is being used, set index ti -1.

Default: 6

color String

Color as HEX string.

Mandatory if "index": "-1".

refLineExpr String
Name Type Description
label StringExpressionContainer Expression for the displayed value.
value ValueExpressionContainer Expression for the value used in the visualization.
cId String ID used by the client. Needs to be unique within the array of reference lines.

dataPoint

Type: Object

Data point settings for scatter plots.

Properties

Name Type Description
bubbleSizes Integer

Bubble size.

Min: 1, Max: 20, Default: 5

rangeBubbleSizes Array Bubble sizes. Represented as an array of two integers where the first index is the from-size, and the second is the to-size. From-size should always be smaller than the to-size.

labels

Type: Object

Label settings.

Properties

Name Type Description
mode Integer

Set to display labels. Can be one of:

  • 0: show labels
  • 1: auto
  • 2: hide labels

Default: 1

gridLine

Type: Object

Grid line settings.

Properties

Name Type Description
auto Boolean

Set to use automatic grid line spacing.

Default: true

spacing Integer

Grid line spacing. Used only when auto is set to false. One of:

  • 0: no lines
  • 1: wide
  • 2: medium
  • 3: narrow

Default: 2

compressionResolution

Type: Integer

Scatter plot resolution settings for compressed data.

Default: 5

color

Type: Object

Most color options for visualizations are set in the color object in the options. You activate custom coloring by setting "auto": false which turns off auto-coloring.

If "auto": true, no other properties need to be defined in the color object.

The following parameters can be set in the color object:

Name Type Description
auto Boolean

Set to use automatic coloring.

When "auto": true, color settings are based on the visualization used and the number of dimensions and measures, that is, the settings are not fixed, but are dependent on the data input.

Default: true

mode String

Sets the coloring mode for the visualization when auto-coloring has been switched off ("auto": false). Can be one of:

  • primary: a single color (by default blue) is used for all items in the chart. In visualizations that do not benefit from multiple colors (bar charts with one dimension and scatter plots), single color is the default setting.
  • byDimension: coloring is based upon the amount of dimension values. Details are set in the byDimensionDef property.

    Note: byDimension can only be used in conjunction with an attribute dimension on the dimension to color by, as shown in the example below.
    { "qDef": { "qFieldDefs": [ "NetScoreName" ] }, "qAttributeDimensions": [ { "qDef": "NetScoreName", "id": "colorByAlternative", "label": "Year" } ] }
  • byExpression: coloring is based on an expression, which in most cases is a color code. Details are set in the expressionIsColor, expressionLabel and colorExpression properties.

  • byMeasure: coloring is based on the measure value. Details are set in the byMeasureDef property.
  • byMultiple: can be used when more than one measure is used. By default, 12 colors are used for the dimensions. The colors are reused when there are more than 12 dimension values.
useBaseColors String

Only applicable when "mode": "primary" or "mode": "byMultiple" has been defined.

Use colors encoded in master items. Should only be defined when a master dimension or master measure used in the visualization has a color assigned to it.

One of:

  • off
  • measure: use colors encoded in master measure.
  • dimension: use colors encoded in master dimension.

Default: off

singleColor Integer

Deprecated. Use paletteColor instead.

Set to use single color.

Default: 3

paletteColor Object

The paletteColor object is used to define the color when you color by single color ("mode": "primary"). It has the following properties:

Name Type Description
index Integer

Index in the palette.

The default Qlik Sense color palette:

  • -1: set to use custom color that is not in the palette.
  • 0: No color
  • 1: White, HEX: #ffffff
  • 2: Light green, HEX: #46c646
  • 3: Green, HEX: #276e27
  • 4: Light blue, HEX: #b6d7ea
  • 5: Blue, HEX: #7db8da
  • 6: Dark blue, HEX: #4477aa
  • 7: Purple, HEX: #8e477d
  • 8: Yellow, HEX: #ffcf02
  • 9: Orange, HEX: #f8981d
  • 10: Red, HEX: #f93f17
  • 11: Brown, HEX: #633d0c
  • 12: Light gray, HEX: #b0afae
  • 13: Gray, HEX: #7b7a78
  • 14: Dark gray, HEX: #545352
  • 15: Black, HEX: #000000

Default: 6

color String

Color as HEX string.

Mandatory if "index": "-1".

persistent Boolean

Set to true to use persistent colors on data points between selection states. Only applicable when using one dimension and when "mode": "byDimension" or when "mode": "byMultiple".

Default: false

expressionIsColor Boolean

Set to true to define whether the result of the expression is a valid CSS3 color.

Only applicable when "mode": "byExpression".

Default: true

expressionLabel String

Defines the label on tool tips when using a coloring expression. Only applicable when "mode": "byExpression" and only used if "expressionIsColor": false.

colorExpression Value Expression Container

Sets the color expression to be used when "mode": "byExpression" is defined.

Supported formats:

  • RGB
  • ARGB
  • HSL

Example:  

"colorExpression": "=if(sum(Sales)<avg(Total aggr(sum(Sales),Product)),rgb(255,0,0),RGB(0,255,0))"
measureScheme String

Color scheme when "mode": "byMeasure". Can be one of:

  • sg: (sequential gradient) the transition between the different color groups is made using different shades of colors. High measure values have darker hues
  • sc: (sequential classes) the transition between the different color groups is made using distinctly different colors.
  • dg: (diverging gradient) used when working with data that is ordered from low to high, for instance, to show the relationship between different areas on a map. Low and high values have dark colors, mid-range colors are light.
  • dc: (diverging classes) can be seen as two sequential classes combined, with the mid-range shared. The two extremes, high and low, are emphasized with dark colors with contrasting hues, and the mid-range critical values are emphasized with light colors.

Default: sg

useMeasureGradient Boolean

Set to true if you want to apply the colors defined for library measures when used. Only applicable if "mode": "byMeasure".

Default: true

dimensionScheme String

Color scheme when "mode": "byDimension" or "mode": "byMultiple". Can be one of:

  • 12: 12 colors where all can be distinguished by people with vision deficiency.
  • 100: 100 colors where not all can be distinguished by people with vision deficiency

Default: 12

useDimColVal Boolean

Set to true if you want to apply the colors defined for library dimensions when used. Only applicable if "mode": "byDimension".

Default: true

reverseScheme Boolean

Set to true to reverse the color scheme.

autoMinMax Boolean

Set to false to define custom color range. Custom color range is only applicable when coloring is by measure ("mode": "byMeasure") or by expression ("mode": "byExpression").

When coloring is by expression, "expressionIsColor": "false" must be set for custom color range to work.

Default: true

measureMin Value Expression Container

Set the min value for the color range.

Only applicable if autoMinMax: false. Can be used in conjunction with measureMax or by its own.

measureMax Value Expression Container

Set the max value for the color range.

Only applicable if autoMinMax: false. Can be used in conjunction with measureMin or by its own.

legend

Type: Object

Legend settings.

Properties

Name Type Description
show Boolean

Set to show the legend.

Default: true

dock String

Sets the legend position. Can be one of:

  • auto
  • right
  • left
  • bottom
  • top

Default: auto

showTitle Boolean

Show the legend title.

Default: true

xAxis

Type: Object

X axis settings.

Properties

Name Type Description
show String

Set to display the labels and titles. Can be one of:

  • all
  • labels
  • title
  • none

Default: all

dock String

Sets the axis docking position. Can be one of:

  • near
  • far

Default: near

spacing Number

Set the axis scale:

Default: 1

autoMinMax Boolean

Set to use automatic min/max for measure color.

Default: true

minMax String

Set custom max/min. Can be one of:

  • min
  • max
  • minMax

Default: min

min ValueExpressionContainer
max ValueExpressionContainer

yAxis

Type: Object

Y axis settings.

Properties

Name Type Description
show String

Set to display the labels and titles. Can be one of:

  • all
  • labels
  • title
  • none

Default: all

dock String

Sets the axis docking position. Can be one of:

  • near
  • far

Default: near

spacing Number

Set the axis scale:

Default: 1

autoMinMax Boolean

Set to use automatic min/max for measure color.

Default: true

minMax String

Set custom max/min. Can be one of:

  • min
  • max
  • minMax

Default: min

min ValueExpressionContainer
max ValueExpressionContainer

navigation

Type: Boolean

Set to true to display navigation UI.

Example using Visualization API

Tip: For more examples of how to create scatter plots on the fly, see Mashups: Creating scatter plots.

In this example we create a basic scatter plot, containing one dimension and two measures. The measures have basic number formatting applied and a title is added to the scatter plot.

app.visualization.create(
  'scatterplot',
  [
    {
      "qDef": {
        "qFieldDefs": [
          "=[Date.autoCalendar.YearQuarter]"
        ],
        "qFieldLabels": [
          "Year and Qtr"
        ]
      },
      "qNullSuppression": true
    },
    {
      "qDef": {
        "qLabel": "FIR%",
        "qDef": "Avg(FwHit)",
        "qNumFormat": {
          "qType": "F",
          "qnDec": 2,
          "qUseThou": 0,
          "qFmt": "0.0%",
          "qDec": ".",
          "qThou": ","
        }
      }
    },
    {
      "qDef": {
        "qLabel": "GIR%",
        "qDef": "Avg(GIR)",
        "qNumFormat": {
          "qType": "F",
          "qnDec": 2,
          "qUseThou": 0,
          "qFmt": "0.0%",
          "qDec": ".",
          "qThou": ","
        }
      }
    }    
  ],
  {
    "showTitles": true,
    "title": "Fairways hit vs. Greens hit relation"
  }
).then(function(vis){
  vis.show("QV01");
});

Did this information help you?

Thanks for letting us know. Is there anything you'd like to tell us about this topic?

Can you tell us why it did not help you and how we can improve it?