C3 AI Documentation Home

Chart axis markers

Axis markers refers to rendering a shaded area or lines on a chart, either vertically (parallel to y-axis) or horizontally (parallel to x-axis).

For example, on a timeseries chart, a developer might want to provide a vertical shaded band representing all weekends. Or, a developer may want to provide a horizontal shaded area to represent the area between a min and max value. This simplifies finding values that fall outside the defined min or max values.

Associated Types and examples

We provide three visualization types that may be configured in the .json file for a chart. These types should be added as part of a yAxisFields configuration, in the visualizationType value.

UiSdlTimeseriesLineBarChartXAxisAreaShadingVisualization

  • UiSdlTimeseriesLineBarChartXAxisAreaShadingVisualization
  • Use this type when you want to shade a vertical area of the chart.
  • Provide a metric that returns 1s for the datetimes of shaded area, and 0s for unshaded areas.
  • For example, the data for a metric that would show shaded areas on the weekends, might look as follows:
    • Assuming the first value in the array represents Friday:
    • [0, 1, 1, 0, 0, 0, 0, 0, 1, 1, 0, 0, 0, 0, 0, 1, 1, 0]
    • Example config:
JSON
{ 
  "type": "UiSdlConnected<UiSdlTimeseriesLineBarChart>",
  "component": {
    "dataSpec": {
      "dataType": "TestMetricEvaluatable",
      "yAxisFields": [
        {
          "legendLabel": "SDLDemo.ChartXAxisAreaShadingMetricSeries.label",
          "visualizationType": {
            "type": "UiSdlTimeseriesLineBarChartXAxisAreaShadingVisualization"
          },
          "entityId": "thing_2",
          "metricName": "Weekends"
        }
      ]
    }
  }
}

UiSdlLineBarChartYAxisMarkerRangeShadingVisualization

  • UiSdlLineBarChartYAxisMarkerRangeShadingVisualization
  • Use this type when you want to provide a horizontal shaded area, to represent a min and max value.
  • Provide from and to values in the configuration, and lines will be drawn on the chart, with a shaded area between them.
  • Using the relatedMarkers configuration, you can associate a metric configuration with many marker configurations.
  • In the example below, the markerIdentifier is set to threshold_2. The value threshold_2 may then be used in other metric configuration relatedMarkers to tie the marker to the metric.
  • Example config:
JSON
{ 
  "type": "UiSdlConnected<UiSdlTimeseriesLineBarChart>",
  "component": {
    "dataSpec": {
      "yAxisFields": [
        {
          "legendLabel" : "SDLDemo.ChartBasic.series.FutureArrivals.name",
          "visualizationType" : {
            "type" : "UiSdlTimeseriesLineBarChartLineVisualization"
          },
          "entityId" : "thing_2",
          "metricName" : "RandomChartDataOne",
          "relatedMarkers": ["threshold_2"]
        },
        {
          "legendLabel": "SDLDemo.ChartYAxisMarkers.threshold2.name",
          "visualizationType" : {
            "type" : "UiSdlLineBarChartYAxisMarkerRangeShadingVisualization",
            "markerAxisValue": {
              "type": "UiSdlChartAxisMarkersRangeValue",
              "from": 5,
              "to": 20
            },
            "markerIdentifier": "threshold_2"
          },
          "unit": {
            "symbol": "$",
            "id": "USD"
          }
        }
      ]
    }
  }
}

UiSdlLineBarChartYAxisMarkerLineVisualization

  • UiSdlLineBarChartYAxisMarkerLineVisualization
  • Use this type when you want to draw a single horizontal line at a specified position on the y-axis.
  • For example, you might want to represent a max threshold, and be able to easily see when values have exceeded that threshold.
  • You can provide either a static value, or a metric that produces a data set of the same value.
  • Using the relatedMarkers configuration, you can associate a metric configuration with many marker configurations.
  • Example configs:
JSON
// static value
{ 
  "type": "UiSdlConnected<UiSdlTimeseriesLineBarChart>",
  "component": {
    "dataSpec": {
      "yAxisFields": [
        {
          "legendLabel" : "SDLDemo.ChartBasic.series.FutureArrivals.name",
          "visualizationType" : {
            "type" : "UiSdlTimeseriesLineBarChartLineVisualization"
          },
          "entityId" : "thing_2",
          "metricName" : "RandomChartDataOne",
          "relatedMarkers": ["marker1", "marker2"]
        },
        {
          // Marker with static value
          "legendLabel": "SDLDemo.ChartYAxisMarkers.threshold1.name",
          "visualizationType" : {
            "type" : "UiSdlLineBarChartYAxisMarkerLineVisualization",
            "markerAxisValue": 30,
            "markerIdentifier": "marker1"
          },
          "unit": {
            "symbol": "$",
            "id": "USD"
          }
        },
        {
          // Marker using a metric response as value
          "type": "UiSdlConnected<UiSdlTimeseriesLineBarChart>",
          "component": {
            "dataSpec": {
              "dataType" : "TestMetricEvaluatable",
              "yAxisFields": [
                {
                  "legendLabel": "SDLDemo.ChartYAxisMarkers.threshold3.name",
                  "visualizationType" : {
                    "type" : "UiSdlLineBarChartYAxisMarkerLineVisualization",
                    "markerIdentifier": "marker2"
                  },
                  "entityId" : "thing_1",
                  "metricName" : "identity(3)",
                  "color": "#228630",
                  "unit": {
                    "symbol": "$",
                    "id": "USD"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  }
}

Linking metrics to Y axis markers

  • Linking a metric to 1 or more markers will add some visual integrations such as showing metrics and markers together in the tooltip and highlighting related series all together.
  • Markers will inherit the related metric color by default but marker can customize this on visualizationType.
JSON
{
  // Marker with static value
  "legendLabel": "SDLDemo.ChartYAxisMarkers.threshold1.name",
  "visualizationType" : {
    "type" : "UiSdlLineBarChartYAxisMarkerLineVisualization",
    "markerAxisValue": 30,
    "markerIdentifier": "marker1",
    "lineStyle": "Dashed",
  },
  "color": "#E8CD01",
  "unit": {
    "symbol": "$",
    "id": "USD"
  }
},
Was this page helpful?