Jump to content
We've recently updated our Privacy Statement, available here. ×
  • How to Configure a KPI Chart in Spotfire® Using IronPython Scripting


    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.

    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. 

     

    converted-file.thumb.png.6be71217b1fb47efb33ad908cee4ddac.png

     

    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

    License:  TIBCO BSD-Style License

     

     


    User Feedback

    Recommended Comments

    There are no comments to display.


×
×
  • Create New...