Metrics¶
Metric structure¶
The metric configuration provides the info that is needed to display the metric. All metrics have a unique id, and a static type that determines how it should be displayed (for instance, as currency or a linechart).
Each type will require other attributes that describe the metric. Some of the more common ones are value and sentiment.
Attributes can either be static or be derived from a data source. This gives the creator a lot of flexibility in how an app is built.
A static attribute will have a type of static and a value that will be used where ever that field is used. Static attribute:
"value": {
"type": "static",
"value": "Will be the same on every page"
}
A dynamic attribute will have a type of field and a field that points to the attribute that should be used. Dynamic attribute:
"value": {
"type": "field",
"field": "dynamic_attribute_column_name"
}
By default, dynamic attributes come from the primary data_source. To
use a field made available in a secondary data_source, add a
data_source attribute. The data_source attribute can not be set on
attributes from the primary data_source. Dynamic attribute from
secondary data_source:
"value": {
"type": "field",
"field": "dynamic_attribute_column_name",
"data_source": "country"
}
Some metrics call for multiple values, which can be set using a type of array and a values key that has an array of static and dynamic attributes. Array attribute:
"value": {
"type": "array",
"values": [{
"type": "static",
"value": "Will be the same on every page"
},{
"type": "field",
"field": "dynamic_attribute_column_name"
}]
}
Metric Title¶
metric.title = {}
Each metric should have a title (with the exception of Action Metrics). This usually will be static:
"title": {
"type": "static",
"value": "Absolute metric"
},
On detail views, it can also be dynamic, and refer to a field:
"title": {
"type": "field",
"value": "my_field_title"
},
You can also disable the title by setting the value to false:
"title": {
"type": "static",
"value": false
},
Metric Caption¶
metric.caption = {}
Added in v1.6.0.
In some cases, you may wish to add additional information to a metric to provide a user with additional context about the metric. In general, this should be avoided when possible.
Before implementing a caption, take a moment to revist your graph or other type of metric and see if there is a way to simplify it or make it easier to understand.
The caption will be hidden by default, and a user will need to tap to view the caption.
The caption should be very short and succinct.:
"caption": {
"type": "static",
"value": "Month over month aggregate"
}
This is only supported on KPI display metrics, and is not supported on
metrics inside another metric, such as a displayHorizStack or
dataTable.
Sentiment¶
We want to quickly communicate info about metrics, and convey whether something is good or bad. This value will be reflected in the styling of the metric.
Neutral vs. none: neutral and none are conceptually different-
neutral conveys that it is neither positive nor negative, while none
conveys that you don’t know if it is good or bad. If other values in
that column have sentiment, you likely want to choose neutral. If a
metric doesn’t have a sentiment, it will display as none.
Possible values: positive, negative, neutral, none
These values are case sensitive, and should be transformed using Publisher transform lower_case.
Sentiment in non-chart metrics¶
Sentiment is supported by the following non-chart metrics:
numberAbsolute, numberCurrency, numberRelative, textShort,
textMedium, textLong.
Example:
"sentiment": {
"type": "static",
"value": "positive"
}
Sentiment in dataTable metric¶
In the datatable metric, sentiment is supported for all metric types.
The sentiment value must be an array of the same length as the dataTable
length.
Example:
"sentiment": {
"type": "static",
"value": ["positive", "negative", "neutral"]
}
Sentiment in chart metrics¶
Added in v1.7.0.
Sentiment is supported to an intentionally limited extent in chart metrics. Since we are adding color as a dimension, we can not use it in charts that already use color as a dimension.
Chart sentiment can NOT be used in conjunction with:
- multiple series (with the exception of the dual charts)
- stacked charts
- donut and half donut charts (each point is a color)
Due to these constraints, chart sentiment is supported for the following
metric types: chartBar, chartColumn, chartDot, chartDualBarDot,
chartDualColumnLine (column series only), chartRangeBar,
chartRangeColumn, chartScatterplot.
Since sentiment is only useful by comparison, sentiment values must be an array. A single sentiment will not be applied to all points. If there are more points than sentiment values, the remaining points will be treated as having a ‘null’ sentiment, and the color will return to the default.
On dual charts, the sentiment on a series should be in comparison with the other series.
Example:
"sentiment": {
"type": "static",
"value": ["positive", "negative", "neutral"]
}
- Bar chart
- Column chart
- Dot chart
- Dual column line chart
- Range bar chart
- Range column chart
- Scatterplot chart
Null Value Indicator¶
metric.nullValueIndicator = {}
You can determine how a null value is represented using the nullValueIndicator option. Defaults to ‘-‘.
Example:
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Medium Text with Null Value"
},
"type": "textMedium",
"value": {
"type": "static",
"value": null
},
"nullValueIndicator": {
"type": "static",
"value": "n/a"
}
};
Hidden Metrics¶
metric.hidden = {}
Added in v1.7.0.
You can hide a metric statically or dynamically using the hidden
attribute. This takes a boolean value, and if this is set dynamically,
all logic must be done in the data preparation step. This can not be
used to check for the presence of value, and everything besides the
boolean value true will evaluate to false, meaning the metric will
not be hidden.
This is only available in detail_metrics on an AtomList, and on an
AtomDetail view. It is not supported on metrics inside another metric,
such as a displayHorizStack or dataTable.
Example:
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Long Text Hidden"
},
"type": "textLong",
"hidden": {
"type": "static",
"value": true
},
"value": {
"type": "static",
"value": "This will only be shown if the value for hidden is false."
},
}
In Debug Mode, the metric title will appear in the view, but not the metric content. Users without Debug Mode enabled will see no part of the metric. This allows you to edit the metric (disable the hidden value first) and see where it would be positioned if visible.
Potential use cases:
- “Comment out” metrics that are in progress or need to be temporarily hidden from users.
- A specific metric may only be interest at the end of the month, or on a specific day of the week.
- Show a metric only when it is needed. Perhaps 90% of the time, a
metric is not interesting or useful. If that is the case, your data
processing step can set a field to
trueto hide the metric. If a metric is only shown when useful, it will be more impactful. - Text Long
Text and number metric types¶
Absolute metrics¶
Standalone numbers that don’t refer to other numbers. Examples: Number of units, number of days, number of people.
Positions supported: summary, detail
Attributes: value, sentiment, nullValueIndicator
Example:
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Absolute metric"
},
"type": "numberAbsolute",
"value": {
"type": "field",
"field": "abs"
}
}
Relative metrics¶
Relative metrics are useful when you want to compare a metric to something else. Examples: Cost vs baseline, Monthly number vs yearly. These will be displayed as a percent. A value of 1 will be displayed as “1%”, 100 will be displayed as “100%”
Positions supported: summary, detail
Attributes: value, sentiment, nullValueIndicator
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Relative metric"
},
"type": "numberRelative",
"value": {
"type": "field",
"field": "abs"
}
}
Currency metrics¶
For use when a value represents a value in a currency. Examples: Monthly cost, price of a product.
Positions supported: summary, detail
Attributes: value,sentiment, currency (ISO 4217 code, defaults to USD), decimals (defaults to 2), nullValueIndicator
Example:
{
"id": "CostPerPackage",
"title": {
"type": "static",
"value": "Cost per package"
},
"type": "numberCurrency",
"currency": {
"type": "static",
"value": "USD"
},
"decimals": {
"type": "static",
"value": 0
}
"value": {
"type": "field",
"field": "CostPerPackage"
}
}
Number Config options¶
metric.numberConfig = {}
Number metrics support additional configuration options to help make sure numeric values are easily parsable and understood for users.
Separate Thousands¶
metric.numberConfig.separateThousands = {}
Large numbers can be formatted with commas separating thousands using
the separateThousands option. This is supported by
numberAbsolute and
numberRelative.
Example:
"numberConfig": {
"separateThousands": {
"type": "static",
"value": true
}
}
Decimals¶
metric.numberConfig.decimals = {}
Control the number of decimal points in a number using the decimals
option. This is supported in
numberAbsolute and
numberRelative.
If the number has more fraction digits than the config value, the number will be rounded. If the number has fewer fraction digits than the config value, the number will be padded with zeroes to reach that value.
Example:
"numberConfig": {
"decimals": {
"type": "static",
"value": 2
}
}
Units¶
Added in v1.7.0.
metric.numberConfig.units = {}
Add a unit signifier to make it clear what a number signifies. Both singular and plural must be specified. This will not be added to non-numeric values. This is supported in numberAbsolute.
Attributes:
singular: A string attribute to be used when the value is exactly- Required.
plural: A string attribute to be used when the value is not exactly 1. Required.hideSpace: A boolean attribute. By default, the unit will be separated from the number by a space. To prevent this, set this attribute to true. Optional.
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Absolute metric with units, no space"
},
"type": "numberAbsolute",
"value": {
"type": "field",
"field": "abs"
},
"numberConfig": {
"units": {
"singular": {
"type": "static",
"value": "min"
},
"plural": {
"type": "static",
"value": "mins"
},
"hideSpace": {
"type": "static",
"value": true
}
}
}
}
In this example, a value of 1 will be shown as 1min and a value of 2
will be shown as 2mins.
Magnitude¶
Added in v1.7.0.
metric.numberConfig.magnitude = {}
Consistency is important when communicating with numbers. One common
issue is displaying numbers of different magnitude next to each other.
If 30 and 2k are displayed next to each other, users who are quickly
scanning may understand that 30 is larger than 2k. To handle this,
Sightglass has a “magnitude” formatter to make sure numbers are
consistently shown with the same magnitude. This is especially important
in dataTables, but also in other places where scannable data is
important.
Given a numeric magnitude, the formatter removes magnitude digits
from the right of the number, rounding as needed. It then adds a SI unit
to the number.
This is available in numberAbsolute and numberCurrency. It can be
combined with separateThousands and units, but not with decimals.
| Number | Magnitude | Output |
|---|---|---|
| 1500 | 2 | 1.5k |
| 1500 | 3 | 2k |
| 1500 | 4 | 0.00M |
| 5000 | 4 | 0.01M |
| 5000000 | 4 | 5.00M |
As you can see, this is not the same as significant digits or rounding. Given a magnitude, you are guaranteed a consistent SI unit and number of decimal places, although the number of digits in the integral will vary based on input.
You may also specify a magnitude of “auto”. This will round the number to the closest SI unit. This does not account for multiple values, so it should be used with caution.
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Absolute metric with magnitude"
},
"type": "numberAbsolute",
"value": {
"type": "field",
"field": "abs"
},
"numberConfig": {
"magnitude": {
"type": "static",
"value": 5
}
}
}
Short text metrics¶
Use for short pieces of text that provide a value for the atom. These should be less than 8 characters long.
Attributes: nullValueIndicator
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Static Text"
},
"type": "textShort",
"value": {
"type": "static",
"value": "Static"
}
}
Medium text metrics¶
Use for text descriptions of the atom- for instance, a location or alternative name.
Appropriate for text up to 30 characters.
Attributes: nullValueIndicator
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Static Text"
},
"type": "textMedium",
"value": {
"type": "static",
"value": "Longer text but not too long"
}
}
Long text metrics¶
Use for paragraph-style text info about an atom- for instance, a description of a product, or detailed instructions on usage.
Appropriate for text up to 500 characters. Supports \n for newlines.
Attributes: nullValueIndicator
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Static Text"
},
"type": "textLong",
"value": {
"type": "static",
"value": "This is longer text"
}
}
Unordered list metric¶
Use to display an unordered list of strings. Takes an array of strings.
Example:
"type": "listItemUnordered",
"value": {
"type": "field",
"field": "AvgSpend"
}
Ordered list metric¶
Use to display an ordered list of strings. Takes an array of strings.
Example:
"type": "listItemOrdered",
"value": {
"type": "field",
"field": "AvgSpend"
}
List item Attributes¶
metric.listItemAttributes = {}
Both the ordered and unordered list metrics support the following attributes, which can be combined-
Actions¶
metric.listItemAttributes.actions = {}
Add links to the list items by providing actions. Supported actions are link-external, link-new-view, and link-tool.
Example:
"listItemAttributes": {
"actions": {
"type": "link-external",
"value": {
"type": "field",
"field": "urls"
}
}
}
Completed¶
metric.listItemAttributes.completed = {}
For list items that represent tasks, you can signify that an item is completed by providing an array of booleans for which items are completed.
Example:
"listItemAttributes": {
"completed": {
"type": "static",
"value": [true, false, false, false, true]
}
}
Data table¶
Show data in a table view. Each column is expected to represent the same type of data. If the data is wider than the user’s screen, they will be able to scroll horizontally to view. Given the size of people’s screens, this should not be used for more than 5 columns and 20 rows, although 3 columns and <10 rows is preferred.
This can be used with the horizontal stack to provide more options.
By default, each value represents a column, but this can be changed using the direction option.
The value object for this metric is an array of metric definitions. Each metric definition has a value that is an array of values that will be displayed using that metric definition.
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Data table"
},
"type": "dataTable",
"value": {
"type": "array",
"values": [
{
"id": "labels",
"value":{
"type": "field",
"field": "SeriesNames"
},
"type": "textShort"
},
{
"id": "amounts",
"value":{
"type": "field",
"field": "Amounts"
},
"type": "numberRelative",
"sentiment":{
"type": "field",
"field": "AmountSent"
}
}
]
}
}
In this example, there will be 2 columns of data. The first is a text
field that will be populated with the values from SeriesNames. The
second is a relative number field that will be filled with the values
from Amounts and will apply a sentiment to each.
Metric support¶
The data table supports
textShort,
numberAbsolute,
numberRelative, and
numberCurrency. All
configuration options of those metrics are supported, with the exception
of actions, title, and preferredLayout.
Direction¶
Added in v1.7.0.
metric.dataTableConfig.direction = {}
By default, each value in a dataTable defines the values in a column. You can instead pivot the values so that each value defines the values in a row.
If the direction is column, the number of columns in a data table can not be changed dynamically, but the number of rows can be. Each value in a column must be of the same type.
If the direction is row, the number of rows in a data table can not be changed dynamically, but the number of columns can be. Each value in a row must be of the same type.
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Data table"
},
"type": "dataTable",
"value": {
"type": "array",
"values": [
{ ... },
{ ... },
{ ... }
]
},
"dataTableConfig": {
"direction": {
"type": "static",
"value": "row"
}
}
}
- Data table row
- Data table row with total
- Data table row with static
- Data table row with many options
Header¶
metric.dataTableConfig.header = {}
You can add a header row to a data table that is either static or dynamic. The number of objects in that array should match the number of columns in the data table.
If a row header is defined, there will be an additional column at the beginning. You can either add a header to the row header column, or set it to an empty string to leave it blank.
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Data table"
},
"type": "dataTable",
"value": {
"type": "array",
"values": [
{ ... },
{ ... },
{ ... }
]
},
"dataTableConfig": {
"header": {
"type": "static",
"value": ["Names", "Percent", "Amount"]
}
}
}
Row Header¶
Added in v1.7.0.
metric.dataTableConfig.rowHeader = {}
In dataTables defined by row, you can add a header cell to each row. The number of objects in that array should match the number of rows in the data table.
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Data table"
},
"type": "dataTable",
"value": {
"type": "array",
"values": [
{ ... },
{ ... },
{ ... }
]
},
"dataTableConfig": {
"rowHeader": {
"type": "static",
"value": ["Names", "Percent", "Amount"]
}
}
}
Additional headers¶
Added in v1.8.0.
With the direction set to row, you can set additional rows to be headers for the data table. This is done with a special metric type- textHeader.
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Data table with multiple headers"
},
"type": "dataTable",
"value": {
"type": "array",
"values": [
{ ... },
{
"id": "header2",
"value": {
"type": "static",
"value": ["MTD", "YTD"]
},
"type": "textHeader"
},
{ ... }
]
},
"dataTableConfig": {
"header": {
"type": "static",
"value": ["Names", "Percent", "Amount"]
}
}
}
Sortable¶
metric.dataTableConfig.sortable = {}
You can allow users to sort datatables by a column. This is only available on dataTables defined by column, and can not be used on dataTables defined by row.
To enable or disable sort for all fields, use a boolean value.
To enable sort for only specific columns, use an array of boolean values.
There is no default sort option for data tables, as it is expected that the initial sorting will be done when preparing the data. The first time a user sorts a column, it will sort values ascending.
If both Total Row and Sortable are used on the same data table, total rows that are the first and last row will not be included in the sort, and will stay in their respective location. If total row is set on a row in the middle of a data table, that row will be sorted with the rest of the table.
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Data table"
},
"type": "dataTable",
"value": {
"type": "array",
"values": [
{ ... },
{ ... },
{ ... }
]
},
"dataTableConfig": {
"sortable": {
"type": "static",
"value": true
}
}
}
Total Row and Column¶
metric.dataTableConfig.totalRow = {}
metric.dataTableConfig.totalColumn = {}
Total column added in v1.7.0.
With totalRow, you can specify that a row of data is a total row in a
data table.
With totalColumn, you can specify that a column of data is a total row
in a data table. This is only available in dataTables defined by row.
This emphasizes the styling in a way that helps people understand the data. It does not automatically total your data- that needs to be done as part of your data preparation.
totalRow positional string options: top|bottom|top-and-bottom
totalColumn positional string options: last
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Data table"
},
"type": "dataTable",
"value": {
"type": "array",
"values": [
{ ... },
{ ... },
{ ... }
]
},
"dataTableConfig": {
"totalRow": {
"type": "static",
"value": "bottom"
},
"totalColumn": {
"type": "static",
"value": "last"
}
"direction": {
"type": "static",
"value": "row"
}
}
}
This example will emphasize the bottom row and the right-most column.
You can also use an array of booleans if you need to highlight specific rows in a data table. The following example will style the 2nd and 3rd rows as total rows.
Example:
"dataTableConfig": {
"totalRow": {
"type": "static",
"value": [false, true, true, false, false]
}
}
- Data table total
- Data table total boolean
- Data table sort total
- Data table row total
- Data table row with many options
Striped data tables¶
To help users understand data tables more easily, you can add optional striping to every other row.
Example:
"dataTableConfig": {
"striped": {
"type": "static",
"value": true
}
}
Standalone action metric¶
You can add an action as a metric directly within detail_metrics or within a view’s metrics. This will display as a button that will perform the action when clicked.
Example:
{
"id": "action-example",
"type": "actionMetric",
"action": {
"type": "link-new-view",
"view": {
"type": "static",
"value": "view_id"
},
"title": {
"type": "static",
"value": "View detail"
}
}
}
Chart metric types¶
Line Chart¶
Display continuous data, usually time-based. Examples: Quarterly sales, monthly profits. Given the size of the display, the chart should ideally show 3-6 values.
Positions supported: detail
Attributes: values (array of numbers), labels (array of categories for X axis)
Supported Configurations: baseline, labels, series, multi-axis, axis-config, spline, chart color start, marker config symbol
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Line Chart Currency"
},
"type": "chartLine",
"values": {
"type": "field",
"field": "AvgSpend"
}
}
Column Chart¶
Compare multiple similar values. Examples: Employee performance vs baseline, Product A vs Product B Sales. Given the size of the display, the chart should ideally show 3-6 values.
Positions supported: detail
Attributes: values (array of numbers), labels (array of categories for X axis)
Supported Configurations: baseline, labels, series, stacked, multi-axis, axis-config, chart color cycle, chart color start
Example:
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Column Chart"
},
"type": "chartColumn",
"values": {
"type": "field",
"field": "AvgSpend"
},
Column Range Chart¶
Compare multiple similar value ranges. Each range consists of a lower y value and a higher y value along an x axis.
Positions supported: detail
Attributes: values (array of arrays containing two numbers that indicate the range), labels (array of categories for X axis)
Supported Configurations: baseline, labels, series, stacked, multi-axis, axis-config, chart color cycle, chart color start
Example:
"id": "TemperatureRange",
"title": {
"type": "static",
"value": "Range Column Chart"
},
"type": "chartRangeColumn",
"values": {
"type": "field",
"field": "TemperatureRange"
},
Bar Chart¶
Compare multiple similar values. Examples: Employee performance vs baseline, Product A vs Product B Sales. Given the size of the display, the chart should ideally show 3-6 values.
Positions supported: detail
Attributes: values (array of numbers), labels (array of categories for X axis)
Supported Configurations: baseline, labels, series, stacked, multi-axis, axis-config, chart color cycle, chart color start
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Bar Chart"
},
"type": "chartBar",
"values": {
"type": "field",
"field": "AvgSpend"
}
}
Bar Range Chart¶
Compare multiple similar value ranges. Each range consists of a lower y value and a higher y value along an x axis.
Positions supported: detail
Attributes: values (array of arrays containing two numbers that indicate the range), labels (array of categories for X axis)
Supported Configurations: baseline, labels, series, stacked, multi-axis, axis-config, chart color cycle, chart color start
Example:
"id": "TemperatureRange",
"title": {
"type": "static",
"value": "Range Bar Chart"
},
"type": "chartRangeBar",
"values": {
"type": "field",
"field": "TemperatureRange"
},
Dot Chart¶
Compare multiple similar values. Examples: Employee performance vs baseline, Product A vs Product B Sales. Given the size of the display, the chart should ideally show 3-6 values.
Positions supported: detail
Attributes: values (array of numbers), labels (array of categories for X axis)
Supported Configurations: labels, multi-axis, axis-config, chart color start, marker config
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Dot Chart"
},
"type": "chartDot",
"values": {
"type": "field",
"field": "AvgSpend"
}
}
Donut Chart¶
Compare relative portions of a metric. Examples: Referral vs Organic contributions, Profit per product. Given the size of the display, the chart should ideally show 3-6 values.
This chart type does not support multiple series.
Positions supported: detail
Supported Configurations: labels, axis-config, chart color start
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Donut chart"
},
"type": "chartDonut",
"values": {
"type": "field",
"field": "AvgSpend"
}
}
Half Donut Chart¶
Compare relative portions of a metric. Examples: Referral vs Organic contributions, Profit per product. Given the size of the display, the chart should ideally show 3-6 values.
This chart type does not support multiple series.
Positions supported: detail
Supported Configurations: labels, axis-config, chart color start
Example:
{
"id": "AvgSpend",
"title": {
"type": "static",
"value": "Donut chart"
},
"type": "chartHalfDonut",
"values": {
"type": "field",
"field": "AvgSpend"
}
}
Scatterplot¶
Since: 1.3.0
Display the relationship between data variables, with a variable on each axis. Examples: Quarterly sales vs. quarterly profits.
Positions supported: detail
Attributes: values (array of arrays that each consist of two numbers: an x value and a y value)
Supported Configurations: axis-config, series, multi-axis, chart color start
Example:
{
"id": "salesData",
"title": {
"type": "static",
"value": "Sales vs. Profits Scatterplot"
},
"type": "chartScatterplot",
"values": {
"type": "field",
"field": "salesData"
}
}
Dual column and line chart¶
This is a special type of multiseries chart that displays columns and lines on the same chart.
The dualChart object is required, and the value of columnSeries and
lineSeries defines the display of each series as an array of integers.
The values are the indices of series as defined in the values array, and
is zero-based. If a series index is not listed, it will default to
column.
Supported Configurations: labels, series, stacked, axis-config, multi-axis, chart color start
Example:
"type": "chartDualColumnLine",
"values": [ ... ],
"dualChart": {
"columnSeries": {
"type": "static",
"value": [0,3]
},
"lineSeries": {
"type": "static",
"value": [1,2]
}
}
Dual bar and dot chart¶
This is a special type of multiseries chart that displays bars and dots on the same chart.
The dualChart object is required, and the value of barSeries and
dotSeries defines the display of each series as an array of integers.
The values are the indices of series as defined in the values array, and
is zero-based. If a series index is not listed, it will default to
bar.
Supported Configurations: labels, series, axis-config, multi-axis, chart color start
Example:
"type": "chartDualBarDot",
"values": [ ... ],
"dualChart": {
"barSeries": {
"type": "static",
"value": [0,3]
},
"dotSeries": {
"type": "static",
"value": [1,2]
}
}
Multiseries charts¶
Most charts support multiple series. This requires values.type to be
an array, and values.values to be an array of attributes. (See Metric
Structure.)
Series names are given using the Series chart configuration options and can be static or field based.
In graphs that have series overlaps, such as the dual column line chart, series are rendered from back to front in the order they appear in the array.
Example:
"values": {
"type": "array",
"values": [
{
"type": "field",
"field": "PhysSpendQuarter"
},
{
"type": "field",
"field": "OverallPatSpend"
}
]
},
Chart configuration¶
These items allow you to further configure charts.
Labels¶
This method of labels is deprecated as of version 1.4.0. Please see labels instead.
metric.labels = {}
Communicate what a datapoint on a chart is meant to convey. This should have the same number of values as the number of values in the series.
Example:
"labels": {
"type": "static",
"value": [
"2016 Q3",
"2016 Q4",
"2017 Q1",
"2017 Q2",
"2017 Q3"
]
}
Series¶
metric.series = {}
When using a chart with multiple series, this provides the names for each series as they should be conveyed. This should have the same number of values as the number of series.
Example:
"series": {
"type": "static",
"value": [
"Series 1",
"Series 2"
]
}
Stacked¶
metric.stacked = {}
You can stack values in a chart with multiple series by providing a “stacked” attribute.
Supported in column chart and bar chart.
Example:
"stacked": {
"type": "static",
"value": true
}
Overlapping¶
metric.overlapping = {}
You can overlap values in a chart with multiple series by providing an “overlapping” attribute.
Supported in column charts, bar charts, range column charts, range bar charts, dual bar dot charts, and dual column line charts
Example:
"overlapping": {
"type": "static",
"value": true
}
Error bars¶
metric.error_bars = {}
Error bars can be added to a chart to indicate the margin of error, or uncertainty, in the graph’s data points. The value will be an array of arrays that contain the lower and upper bounds of each point’s margin of error.
Supported in column charts, bar charts, line charts, dual column line charts, range column charts, range bar charts, and dual bar dot charts
Examples:
"error_bars": {
"type": "field",
"field": "AvgSpendError "
}
or
"error_bars": {
"type": "static",
"value": [[2,4], [3,5]]
}
Baseline¶
This method of baseline is deprecated as of version 1.3.0. Please see baseline instead.
Adds a baseline on the relevant axis for the chart type. Use this to put a specific datapoint into a larger context.
Example:
"baseline": {
"type": "static",
"value": 3
}
Axis Config¶
This method of axisConfig is deprecated as of version 1.3.0. Please see axis-config instead.
To specify the range of the y-axis for a graph, use the axisConfig option. If no value or null is set, the graph will automatically determine the min and max.
A common use for this will be ensuring that the graph axis starts at 0.
To ensure that an axis includes a 0 tick, add a showZero attribute to the axis and set the value to true. If a showZero attribute is not included or if the value is set to false, the graph will automatically determine whether or not a 0 tick should be shown.
Example:
"axisConfig": {
"primary": {
"min": {
"type": "static",
"value": 0
},
"max": {
"type": "field",
"field": "max"
},
"showZero": {
"type": "static",
"value": true
}
},
"secondary": {
"max": {
"type": "static",
"value": 200
}
}
}
Multi-axis¶
This method of axisConfig is deprecated as of version 1.3.0. Please see Multi-axis instead.
In order to show 2 different units in a chart, use multiple axes.
This is not compatible with baseline, and if both are present in the config, baseline will not show.
This is defined with 3 attributes-
primaryandsecondaryhold the title that should be used for each axis. Their position will depend on the chart type.secondary_seriesdefines which series will use the secondary axis. It is an array of integers, which are the indices of series as defined in the values array, and is zero-based.
Supported in column, bar, and line charts with multi-series.
Example:
"axis": {
"primary": {
"type": "static",
"value": "Primary"
},
"secondary": {
"type": "static",
"value": "Secondary"
},
"secondary_series": {
"type": "static",
"value": [1]
}
}
Spline¶
metric.spline = {}
To convey that a dataset is continuous, and not just discrete datapoints, you may want to smooth the connections in a line chart.
This can be overridden using
seriesConfig.
The default value is false.
Example:
"spline": {
"type": "static",
"value": true
},
Chart color¶
metric.chartColor = {}
Your charts may be shown with a variety of themes depending on device type, organization, and user settings. However, you may want to use colors to convey that datapoints are either separate within a chart or connected across charts.
Cycle¶
metric.chartColor.cycle = {}
The default behavior for single series charts is that all data points
within a series are the same color. To make each data point a different
color, use the chartColor.cycle option to true. Example:
"chartColor": {
"cycle": {
"type": "static",
"value": true
}
}
Start Color¶
metric.chartColor.start = {}
Each chart theme has a palette of possible colors. By default, this
always starts with the first one, and iterates through the colors if
needed by the chart. To use a different color, use the
chartColor.start option.
This takes an integer value that will be used to offset the array of colors.
The palette may be different for different users based on device or
settings. The palette will be consistent for a user between charts, so
setting start to 2 on two separate charts would mean they both start
with green, given the above palette. However, since the palettes may be
different for different users, this should not be used to convey
meaning- a red bar chart for one user may be green for a different user.
Each palette will have at least 5 colors.
Example:
"chartColor": {
"start": {
"type": "static",
"value": 2
}
}
start and cycle may also be combined.
Axis Configurations¶
metric.axisConfig = {}
The axisConfig option allows you to further configure the x and y axes, including the primary and secondary axes on a multi axis chart.
Common uses for this will be specifying the range of an axis, setting axis titles, and adding a baseline to a graph.
See below for the the options supported. The options of axisConfig are yAxis and xAxis. The available options of each axis are primary, secondary, and secondary_series, with each of these able to contain the remaining options.
Example:
"axisConfig": {
"yAxis": {
"primary": {
"min": {
"type": "static",
"value": 0
},
"max": {
"type": "static",
"value": 10000
},
"showZero": {
"type": "static",
"value": true
},
"title": {
"type": "static",
"value": "Y Title"
},
"baseline": {
"type": "static",
"value": 8000
}
}
},
"xAxis": {
"primary": {
"title": {
"type": "static",
"value": "X title"
}
}
}
}
Multi-axis¶
metric.axisConfig.<yAxis|xAxis>.<primary|secondary|secondary_series>=
{}
In order to show 2 different units in a chart, use multiple axes. This is compatible with both the x axis and y axis.
This is not compatible with including a baseline, and if both are present in the config, baseline will not show.
This is defined with 2 additional attributes, compared to a single axis chart-
secondaryholds the options for the secondary axis. Its position will depend on the chart type. This option is used within the xAxis or yAxis option.secondary_seriesdefines which series will use the secondary axis. It is an array of integers, which are the indices of series as defined in the values array, and is zero-based. This option is used within only the axisConfig option.
Supported in column, bar, scatterplot, and line charts with multi-series.
Example:
"axisConfig": {
"yAxis": {
"primary": {
"min": {
"type": "static",
"value": 0
},
"max": {
"type": "static",
"value": 60000
},
"title": {
"type": "static",
"value": "Primary Y Axis"
}
},
"secondary": {
"min": {
"type": "static",
"value": 100
},
"title": {
"type": "static",
"value": "Secondary Y Axis"
}
},
"secondary_series": {
"type": "static",
"value": [1]
}
}
}
Title¶
metric.axisConfig.<yAxis|xAxis>.<primary|secondary>.title = {}
Used to specify the title of an axis on the graph.
Example:
"title": {
"type": "static",
"value": "Primary Y Axis"
}
Labels¶
metric.axisConfig.xAxis.<primary|secondary>.labels = {}
Communicate what a datapoint on a chart is meant to convey. This should have the same number of values as the number of values in the series.
Example:
"labels": {
"type": "static",
"value": [
"2016 Q3",
"2016 Q4",
"2017 Q1",
"2017 Q2",
"2017 Q3"
]
}
showAllLabels¶
metric.axisConfig.xAxis.<primary|secondary>.showAllLabels = {}
Ensure that all xAxis categories are shown.
Example:
"showAllLabels": {
"type": "static",
"value": true
}
Min and Max¶
metric.axisConfig.<yAxis|xAxis>.<primary|secondary>.<min|max> = {}
To specify the range of the y-axis for a graph, use the min and max options. If no value or null is set, the graph will automatically determine the min and max.
A common use for this will be ensuring that the graph axis starts at 0.
Example:
"min": {
"type": "static",
"value": 0
},
"max": {
"type": "static",
"value": 60000
},
Baseline¶
metric.axisConfig.<yAxis|xAxis>.primary.baseline = {}
Adds a baseline on the relevant axis for the chart type. Use this to put a specific datapoint into a larger context.
A baseline can only be used on a single axis chart, and may only be added to the x axis on a scatterplot.
Example:
"baseline": {
"type": "static",
"value": 3
}
showZero¶
metric.axisConfig.<yAxis|xAxis>.<primary|secondary>.showZero = {}
To ensure that an axis includes a 0 tick, add a showZero attribute to the axis and set the value to true. If a showZero attribute is not included or if the value is set to false, the graph will automatically determine whether or not a 0 tick should be shown.
Example:
"showZero": {
"type": "static",
"value": true
}
Chart Point Configuration¶
metric.<valueConfig|xValueConfig> = {}
You may want to provide additional info on points in a chart- for
instance, the type of number they are, how many decimals to use, etc.
These are provided via a valueConfig attribute, or an xValueConfig
attribute if being used for the x points on a chart (particularly on a
scatterplot).
Integer¶
Example:
"valueConfig": {
"type": "integer"
}
Example for x axis:
"xValueConfig": {
"type": "integer"
}
Decimals¶
Example:
"valueConfig": {
"type": "double",
"decimals": {
"type": "static",
"value": 1
}
}
Relative¶
Show that points on the chart are relative, and values should be shown as a percentage.
Example:
"valueConfig": {
"type": "relative"
}
Currency¶
If the number of decimals is not specified, it will default to 2.
Example:
"valueConfig": {
"type": "currency",
"currency": {
"type": "static",
"value": "USD"
},
"decimals": {
"type": "static",
"value": 0
}
}
Units¶
Note that plurals are not able to be handled at this time. The same unit string will be displayed whether it is 1 item or multiple items.
Example:
"valueConfig": {
"type": "integer",
"units": {
"type": "static",
"value": "Widget(s)"
}
Marker Config¶
To control how the point markers are displayed, use markerConfig.
By default, the markers are hidden if it’s too crowded, based on the metric width and the number of points. If markers are shown, it automatically cycles through a variety of shapes to help users differentiate between series.
Symbol¶
metric.markerConfig.symbol = {}
For line and
dot charts, you may set a
symbol that will be used for the marker points.
Valid values: none, square, circle, diamond
Example:
"markerConfig": {
"symbol": {
"type": "static",
"value": "none"
}
}
Filled¶
metric.markerConfig.filled = {}
By default, point markers have a white center in
dot charts. To fill them, set
the filled attribute to true.
Example:
"markerConfig": {
"filled": {
"type": "static",
"value": true
}
}
Series Config¶
metric.seriesConfig = {}
You may wish to have different options for different series. In that
case, provide a seriesConfig object that overrides the default values.
This is available for marker
config,
spline and
valueConfig.
This example will turn off spline for the series at index 1, assuming
spline is set to true for the metric:
"seriesConfig": {
"1": {
"spline": {
"type": "static",
"value": false
}
}
},
Note that the index must be passed as a string, as integer keys are not supported by JSON.