How to Configure a KPI Chart in Spotfire® Using IronPython Scripting

Introduction

Spotfire® 7.8 introduces an API to create and configure KPI Charts. The API can be used in custom tools and other extensions or in IronPython scripts. This article includes some script examples that shows some of the capabilities of the API. You can run the examples from the attached .dxp file. 

Code samples

Set Preferred tile width

This example set the preferred tile width of a KPI chart.

 # Copyright © 2017. TIBCO Software Inc.  Licensed under TIBCO BSD-style license.
 
 from Spotfire.Dxp.Application.Visuals import *
 
 kpiChart = visual.As[KpiChart]()
 kpiChart.PreferredTileWidth = Document.Properties["PreferredTileWidth"] 

Show/hide Sparkline

This example toggles the visiblity of the sparkline in the active KPI Visualization.

 # Copyright © 2017. TIBCO Software Inc.  Licensed under TIBCO BSD-style license.  
 
 from Spotfire.Dxp.Application.Visuals import *
 
 kpiChart = visual.As[KpiChart]()
 kpiVisualization = kpiChart.ActiveKpi
 kpiVisualization.ShowSparkline = showSparkLine

Show/Hide Sparkline scale

This example toggles the visiblity of the sparline scale in the active KPI visualization.

 # Copyright © 2017. TIBCO Software Inc.  Licensed under TIBCO BSD-style license.
 
 from Spotfire.Dxp.Application.Visuals import *
 
 kpiChart = visual.As[KpiChart]()
 kpiVisualization = kpiChart.ActiveKpi
 kpiVisualization.ShowSparklineScale = showSparklineScale

Show/hide X-label in Tile

This example toggles the visibility of the X labels in the tiles of the active KPI visualization.

 # Copyright © 2017. TIBCO Software Inc.  Licensed under TIBCO BSD-style license.
 
 from Spotfire.Dxp.Application.Visuals import *
 
 kpiChart = visual.As[KpiChart]()
 kpiVisualization = kpiChart.ActiveKpi
 kpiVisualization.ShowXLabelInTile = showXLabelInTile

Set Sort Mode

This example sets the sort mode of a KPI chart.

from Spotfire.Dxp.Application.Visuals import *

kpiChart = visual.As[KpiChart]()
sortMode = Document.Properties["KPIChartSortMode"]
if sortMode == 0:
	kpiChart.SortMode = KpiSortMode.None
elif sortMode == 1:
	kpiChart.SortMode = KpiSortMode.Alphabetical
elif sortMode == 2:
	kpiChart.SortMode = KpiSortMode.ReverseAlphabetical
elif sortMode == 3:
	kpiChart.SortMode = KpiSortMode.HighestFirst
elif sortMode == 4:
	kpiChart.SortMode = KpiSortMode.LowestFirst

Drill Down Inside a KPI Chart

The following example has some prerequisites:

• A KPI Chart needs to exist which has a KPI Visualization with Region on the X axis, and which uses a marking called "Marking1"
• An action needs to be setup which takes the KPI Chart as argument (and that argument needs to be called visual).
• The hierarchy in the example set is the columns "Category" and "Type".

Once that is in order the following script needs to be pasted into the Action script UI.

# Copyright © 2017. TIBCO Software Inc.  Licensed under TIBCO BSD-style license.

from Spotfire.Dxp.Data import DataManager
from Spotfire.Dxp.Application.Visuals import KpiChart
 
kpiChart = visual.As[KpiChart]()
kpiVisualization = kpiChart.ActiveKpi
dataManager = Application.GetService[DataManager]()
 
if (kpiVisualization.Data.MarkingReference == dataManager.Markings["Marking1"]):
	kpiChart.Title = "KPI Chart - drilled down to type - click tile to drill up"
	kpiVisualization.TileAxis.Expression = "<[Type]>"
	kpiVisualization.Data.Filterings.Add(dataManager.Markings["Marking1"])
	
	# Need to turn off marking or else the plot will be empty when clicking outside the tile 
	kpiVisualization.Data.MarkingReference = None
else:
	kpiChart.Title = "KPI Chart - click tile to drill down"
	kpiVisualization.TileAxis.Expression = "<[Category]>"
	kpiVisualization.Data.Filterings.Remove(dataManager.Markings["Marking1"])
	
	# Turn on marking again
	kpiVisualization.Data.MarkingReference = dataManager.Markings["Marking1"]

See also this article for how to implement KPI chart drill down using document properties (possible to do from version 7.6).

Create a KPI Chart with a Waterfall Chart as Details plot

This example creates a KPI chart and a Waterfall chart. The Waterfall chart is configured as a details plot.

Copyright © 2017. TIBCO Software Inc.  Licensed under TIBCO BSD-style license.

from System.Drawing import Color
from Spotfire.Dxp.Application.Visuals import KpiChart, KpiSortMode, WaterfallChart
from Spotfire.Dxp.Application.Visuals.ConditionalColoring import RuleComparisonOperator, ConditionValue
from Spotfire.Dxp.Application.Layout import LayoutDefinition
from Spotfire.Dxp.Data import *

# Add a new page that will contain the new KPI chart
page = Document.Pages.AddNew()
page.Title = "KPI & Waterfall"

# Add a waterfall chart as a details plot to the KPI chart.
waterfallChart = Document.ActivePageReference.Visuals.AddNew[WaterfallChart]()
waterfallChart.Title = "Details for the selected KPI above"

# Above that add a KPI chart.
kpiChart = Document.ActivePageReference.Visuals.AddNew[KpiChart]()
kpiChart.Title = "Sales this month - colored by difference to last month"

# Configure the KPI chart.
kpiContent = kpiChart.KpiCollection.AddNew()
kpiContent.Title = "Sales this month"

# Set up the data and marking.
kpiVisualization = kpiContent.Visualization
dataManager = Document.Data
kpiVisualization.Data.DataTableReference = dataManager.Tables.DefaultTableReference
dataManager.Markings.DefaultMarkingReference.Color = Color.DarkGreen
kpiVisualization.Data.MarkingReference = dataManager.Markings.DefaultMarkingReference

# Set up the axes.
kpiVisualization.YAxis.Expression = "Sum([Sales] - [Cost]) as [Profit]"
kpiVisualization.XAxis.Expression = "<[Month]>"
kpiVisualization.TileAxis.Expression = "<[Type]>"
kpiVisualization.ColorAxis.Expression = "Sum([Sales] - [Cost]) THEN [Value] - First([Value]) OVER (NavigatePeriod([Axis.X],0,-1)) as [vs last month]"
kpiVisualization.ComparativeAxis.Expression = "THEN [Color.FinalValue] as [vs last month]"
kpiVisualization.SortColumn.Expression = "THEN [Comparative.FinalValue]"

# Set sort mode on the KPI Chart.
kpiChart.SortMode = KpiSortMode.LowestFirst

# Configure the color scheme. It is important to clear the default coloring before building up your own.
kpiVisualizationColoring = kpiVisualization.ColorAxis.Coloring
kpiVisualizationColoring.Clear()
positiveRule = kpiVisualizationColoring.AddThresholdColorRule(RuleComparisonOperator.GreaterOrEqual, ConditionValue.CreateLiteral(0), Color.FromArgb(65, 197, 114))
positiveRule.ManualDisplayName = "Positive"
negativeRule = kpiVisualizationColoring.AddThresholdColorRule(RuleComparisonOperator.Less, ConditionValue.CreateLiteral(0), Color.FromArgb(240, 80, 80))
negativeRule.ManualDisplayName = "Negative"

# Configure the Waterfall chart as a details plot driven by the KPI Chart.
waterfallChart.Data.DataTableReference = dataManager.Tables.DefaultTableReference

# It needs a new marking for its own.
if dataManager.Markings.Contains("WaterfallChartMarking") :
	waterfallChartMarking = dataManager.Markings["WaterfallChartMarking"]
else:
	waterfallChartMarking = dataManager.Markings.Add("WaterfallChartMarking")
	waterfallChartMarking.Color = Color.Blue;
waterfallChart.Data.MarkingReference = waterfallChartMarking

# It needs to be limited by the marking for the KPI Chart, which was the default marking.
waterfallChart.Data.Filterings.Add(kpiVisualization.Data.MarkingReference)

# Configure the axes of the waterfall chart.
waterfallChart.YAxis.Expression = "Sum([Sales] - [Cost]) as [Profit]"
waterfallChart.XAxis.Expression = "<[Month]>"
waterfallChart.ColorAxis.Expression = "THEN [Y.FinalValue]"

# Also in this case a positive/negative colorscheme may seem adequate.
waterfallChartColoring = waterfallChart.ColorAxis.Coloring
waterfallChartColoring.Clear()
positiveRule = waterfallChartColoring.AddThresholdColorRule(RuleComparisonOperator.GreaterOrEqual, ConditionValue.CreateLiteral(0), Color.FromArgb(65, 197, 114))
positiveRule.ManualDisplayName = "Positive"
negativeRule = waterfallChartColoring.AddThresholdColorRule(RuleComparisonOperator.Less, ConditionValue.CreateLiteral(0), Color.FromArgb(240, 80, 80))
negativeRule.ManualDisplayName = "Negative";

# Set a message on the empty plot.
waterfallChart.Data.LimitingMarkingsEmptyBehavior = LimitingMarkingsEmptyBehavior.ShowMessage
waterfallChart.Data.LimitingMarkingsEmptyMessage = "Mark items in the KPI Chart above to see details in this plot."

References

• API Reference: KPIChart class
• API Reference: KPIVisualization class
• API Reference: WaterfallChart class

License:  TIBCO BSD-Style License