SAIL Design System guidance available for Charts Every chart should tell a story. What does yours say? Learn how to build rich reporting dashboards that provide users with visualizations of their data.

Function

a!scatterChartField(data, label, instructions, xAxisTitle, yAxisTitle, yAxisMin, yAxisMax, xAxisMin, xAxisMax, referenceLines, showDataLabels, showTooltips, showLegend, allowDecimalAxisLabels, labelPosition, helpTooltip, accessibilityText, showWhen, colorScheme, height, xAxisStyle, yAxisStyle, refreshAlways, refreshInterval, refreshOnReferencedVarChange, refreshOnVarChange, refreshAfter, primaryGrouping, secondaryGrouping, xAxisMeasure, yAxisMeasure, sort, dataLimit, link)

Displays the relationship between two numerical data points. Use a scatter chart to compare multiple values, visualize trends over time, and spot outliers.

See also:

• Configure Charts Using Records

Parameters

Configuration

The data for a scatter chart is any record type with data sync enabled or a database-backed record type without data sync enabled. When you set the data parameter, Appian will perform the necessary query; select a primaryGrouping, xAxisMeasure, and yAxisMeasure; and display the results directly in the chart.

See Configure Charts Using Records for details on using a record type as the source. See Build Reports from Records for examples of reports created with different charts.

Usage considerations

Select a record type

The record type in the data parameter is the central concept you want to compare in the chart. You can use record fields or related record fields in your groupings and measures. However, groupings cannot use related record fields from a one-to-many relationship because you cannot combine two or more values into a single data point.

Imagine you are building a scatter chart to analyze your sales team's performance. In your app's data model, each salesperson is related to one or more orders.

If you use the Sales Person record type as the source of the chart, you could not group by fields from the related record type Order.

Instead, you should use the Order record type as the source of your chart so you can group by the salesperson's name. Because each order has only one salesperson associated with it, the chart shows each order as its own data point.

Use the sort parameter

Sorting only applies when the chart has a secondary grouping, the sort field is the secondary grouping's alias, and the legend is shown. The sort order determines if the legend items are shown in ascending or descending order.

In this chart, the secondary grouping is the salesperson's region. Sorting on this field lets you display the legend in alphabetical order.

Chart refresh behavior

• You can define a!refreshVariable parameters directly in the chart without creating local variables. The only exception is refreshOnVarChange, which refreshes the chart after a specific local variable has changed.
• It's recommended to use the refresh parameters in the chart instead of using local variables and the a!refreshVariable() function. This is because the refresh behavior will automatically apply to the fields specified in the data parameter of the chart.

Select a primary grouping

The scatter chart requires a primary grouping. This grouping appears as the title in your chart's tooltips to help users understand each data point.

If you want to show users unique values, use a primary grouping field with unique labels (such as order number or item name). Set the xAxisMeasure and yAxisMeasure to use the average of the fields you want to measure.

For example, if you want to examine information about individual employees, your User record type may have a field like userId or fullName that is unique to each person. Selecting this field for grouping would display unique data points for each individual in your chart.

If you want to show aggregate data, use a primary grouping field with common values (such as customer or item color). Then, use the appropriate aggregation to summarize the data.

Instead of grouping by a unique value like fullName, you could select a field like department or jobTitle to view data for groups of users that have a matching attribute.

Work within the data limit

Scatter charts are limited to 5000 data points, but it is important to include as many unique values as possible to ensure you do not omit relevant information and construct a misleading chart. Setting up measures using the AVG function is a good way to balance the goals of including enough data and maintaining performance.

Because production datasets can be large, we recommend using the default limit of 5000 even if your development dataset is smaller.

Examples

The following example data is from the Appian Retail application, available for free in Appian Community Edition. To follow along with this example, log in to Appian Community and register for Appian Community Edition.

Scatter chart with one grouping

This example shows a comparison of the number of items in an customer's order and the order total. The primary grouping, the customer's name, is shown as the title of the tooltip. A positive correlation is expected in this case. Any outlier points are customers that either purchased a few expensive items or many inexpensive items.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
a!scatterChartField(
  data: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}Order',
  primaryGrouping: a!grouping(
     field: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}Order.relationships.{35d1f7f4-442e-471f-8583-ecf70127f1ed}customer.relationships.{ab3f9d64-6b2e-4bd6-9289-a03dc5e7d386}person.fields.{120551bc-43ca-4057-8d03-dd69fcd018ed}fullName',
     alias: "fullName_primaryGrouping"
  ),
  xAxisMeasure: a!measure(
    label: "Order quantity",
    function: "SUM",
    field: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}Order.relationships.{0bde4028-fd7a-411f-97ad-7ad5b84e0d18}orderDetail.fields.{8e3748dd-bbaf-4ece-b9d6-b6108a93da40}orderQty',
    alias: "orderQty_sum_measure1"
  ),
  yAxisMeasure: a!measure(
    label: "Average of Total Due",
    function: "SUM",
    field: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}Order.fields.{f4f2ef33-2a2b-4947-a6f2-11603994ed9f}totalDue',
    alias: "totalDue_sum_measure1",
    formatValue: "DOLLAR"
  ),
  label: "Average order total by order quantity"
)

Displays the following:

Scatter chart with two groupings

This example shows a comparison between sales commission and the salesperson's year-to-date sales total. The chart also includes location data—the salesperson's territory—as the secondary grouping. The values in the legend correspond to the unique values of the secondary grouping (the sales territory). Both grouping values are shown in the tooltip.

This chart shows that employees earning a higher commission tend to make larger sales overall. The secondary grouping lets viewers compare this across the company's sales regions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
a!scatterChartField(
  data: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}Order',
  primaryGrouping: a!grouping(
    field: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}Order.fields.{3f2ba6f1-4afd-4a21-afd1-f399eb6c18e0}orderNumber',
    alias: "orderNumber_primaryGrouping"
  ),
   secondaryGrouping: a!grouping(
    field: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}AW Sales Order Header.relationships.{cc547bb2-c17d-4884-97c7-7c67dbb5dd76}salesPerson.fields.{2c03cc2d-c998-4719-9e64-e719e33fccf5}territoryId',
    alias: "territoryId_secondaryGrouping"
  ),
  xAxisMeasure: a!measure(
    label: "Salesperson commission (%)",
    function: "AVG",
    field: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}Order.relationships.{afdc307f-fe3b-4ded-867d-734cf283d54f}salesPerson.fields.{77dd5675-8988-4381-a574-ec7a86d3477d}commissionPercent',
    alias: "commissionPercent_avg_measure1",
    formatValue: if(
      a!isNullOrEmpty(fv!value),
      "No commission",
      tostring(concat(product(fv!value, 100),"%"))
    )
  ),
  yAxisMeasure: a!measure(
    label: "Order total",
    function: "AVG",
    field: 'recordType!{ad898682-e651-4b2d-af67-47c1fcb1171f}Order.relationships.{afdc307f-fe3b-4ded-867d-734cf283d54f}salesPerson.fields.{7a3fdc19-53c0-40a8-a441-e8eb8500d4c1}ytdSales',
    alias: "ytdSales_avg_measure1"
  ),
  label: "Average order total compared with salesperson commission",
  yAxisMin: 10000,
  colorScheme: "CLASSIC"
)

Displays the following:

Feature compatibility