Formatting

These IronPython scripts below show how to modify any of the Scatter Plot visualization settings found on the Formatting tab of the Scatter Plot Properties dialog box in the Spotfire user interface.

The IronPython scripts shown below cover each of the following scatter plot axis formatting options:

There are a few pieces of additional information about changing formatting options with IronPython that will help avoid confusion.

First, in each of the scripts below, you will notice comments talking about changing the datatypes used in the scripts based on the “targeted axis custom expression output datatype”. This is required because the syntax for changing an axis’s formatting using IronPython changes depending on the datatype of the axis you are trying to format. An axis with a Real datatype will require a slightly different script than an axis with an Integer datatype, for example.

Unfortunately, I’ve not found a way to determine the datatype of an axis programmatically, so you will need to determine it yourself to make the scripts below work correctly. Here are a tips that should help you do so:

  • Start by checking what the datatype of the underlying column in the axis expression is. You can see this in the Spotfire user interface by clicking on the “Edit” menu on the top toolbar, and going to “Column Properties”. You can then see each of the columns’ datatypes in the main column information table shown there. If your custom expression for your targeted axis is using this column directly without any aggregation, such as [Integer Column] or [DateTime Column], the datatype of the underlying column will also be the datatype of your axis.
  • However, if you are doing any calculations or aggregations in your custom expressions, the datatype may change. For example Sum([Integer Column]) becomes a Real datatype. On the other hand, First([Integer Column]) stays an Integer datatype. UniqueCount([DateTime Column]) is an Integer. Usually, you can figure out the correct axis datatype intuitively, but some trial and error may be required. If needed, just keep trying different datatypes until your script works.
  • Some axis datatypes cannot be changed. These include Strings, Booleans, categorical columns such as <[Integer Column]> and binned columns. In the user interface, you can check whether an axis’s formatting can be changed by going to the Formatting tab in the visualization properties dialog box. If the only formatting category available for that axis is “Text”, the axis’s formatting cannot be changed as it is currently configured.
  • Finally, TimeSpan axes formatting can be changed in the user interface, but as far as I can tell, they cannot be formatted using IronPython.
Note

In each of the scripts below, it is assumed that the MyVis variable references the targeted visualization. See here for more information about referencing visualizations.

Use General Formatting:

The IronPython script below is equivalent to selecting the General category on the scatter plot properties formatting tab.

This option is only available when the targeted axis has a numeric data type.

from Spotfire.Dxp.Data import * 
from Spotfire.Dxp.Application.Visuals import *
from Spotfire.Dxp.Data.Formatters import *

myVis = myVis.As[Visualization]()

# Create the formatter:
# IMPORTANT - Replace "Real" on next line with 
# "Integer", "Currency", "LongInteger", or "SingleReal" if needed 
# based on the targeted axis custom expression output datatype
formatter = DataType.Real.CreateLocalizedFormatter()


# Set the formatter category to General
formatter.Category = NumberFormatCategory.General


# Apply the formatter to the targeted axis:
# IMPORTANT - Replace "RealFormatter" on next two lines with 
# "IntegerFormatter", "CurrencyFormatter", 
# "LongIntegerFormatter", or "SingleRealFormatter" if needed
# based on the axis custom expression output datatype
myVis.XAxis.Scale.Formatting.RealFormatter = formatter  #Apply to x axis
myVis.YAxis.Scale.Formatting.RealFormatter = formatter  #Apply to y axis

The script below is equivalent to selecting the Currency category on the scatter plot properties formatting tab and setting the related options.
This option is only available when the targeted axis has a numeric data type.

from Spotfire.Dxp.Data import * 
from Spotfire.Dxp.Application.Visuals import *
from Spotfire.Dxp.Data.Formatters import *

myVis = myVis.As[Visualization]()

# Create the formatter:
# IMPORTANT - Replace "Real" on next line with 
# "Integer", "Currency", "LongInteger", or "SingleReal" if needed 
# based on the targeted axis custom expression output datatype
formatter = DataType.Real.CreateLocalizedFormatter()


# Set the formatter category to Currency
formatter.Category = NumberFormatCategory.Currency

# Set "Decimals:" option:
formatter.DecimalDigitsMode = DecimalDigitsMode.Auto  #(Auto) option
# OR
formatter.DecimalDigits = 2  #Any other integer option (0 to 15)

# Use thousands separator:
formatter.GroupSeparatorEnabled = True

# Set "Negative numbers:" option:
formatter.NegativePattern = NumberFormatNegativePattern.NegativeSign
# OR
formatter.NegativePattern = NumberFormatNegativePattern.Parentheses

# Use short number format:
formatter.ShortFormattingEnabled = True


# Apply the formatter to the targeted axis:
# IMPORTANT - Replace "RealFormatter" on next two lines with 
# "IntegerFormatter", "CurrencyFormatter", 
# "LongIntegerFormatter", or "SingleRealFormatter" if needed
# based on the axis custom expression output datatype
myVis.XAxis.Scale.Formatting.RealFormatter = formatter  #Apply to x axis
myVis.YAxis.Scale.Formatting.RealFormatter = formatter  #Apply to y axis

The script below is equivalent to selecting the Percentage category on the scatter plot properties formatting tab and setting the related options.
This option is only available when the targeted axis has a numeric data type.

from Spotfire.Dxp.Data import * 
from Spotfire.Dxp.Application.Visuals import *
from Spotfire.Dxp.Data.Formatters import *

myVis = myVis.As[Visualization]()

# Create the formatter:
# IMPORTANT - Replace "Real" on next line with 
# "Integer", "Currency", "LongInteger", or "SingleReal" if needed 
# based on the targeted axis custom expression output datatype
formatter = DataType.Real.CreateLocalizedFormatter()


# Set the formatter category to Percentage
formatter.Category = NumberFormatCategory.Percentage

# Set "Decimals:" option:
formatter.DecimalDigitsMode = DecimalDigitsMode.Auto  #(Auto) option
# OR
formatter.DecimalDigits = 2  #Any other integer option (0 to 15)

# Use thousands separator:
formatter.GroupSeparatorEnabled = True


# Apply the formatter to the targeted axis:
# IMPORTANT - Replace "RealFormatter" on next two lines with 
# "IntegerFormatter", "CurrencyFormatter", 
# "LongIntegerFormatter", or "SingleRealFormatter" if needed
# based on the axis custom expression output datatype
myVis.XAxis.Scale.Formatting.RealFormatter = formatter  #Apply to x axis
myVis.YAxis.Scale.Formatting.RealFormatter = formatter  #Apply to y axis

The script below is equivalent to selecting the Scientific category on the scatter plot properties formatting tab and setting the related options.
This option is only available when the targeted axis has a numeric data type.

from Spotfire.Dxp.Data import * 
from Spotfire.Dxp.Application.Visuals import *
from Spotfire.Dxp.Data.Formatters import *

myVis = myVis.As[Visualization]()

# Create the formatter:
# IMPORTANT - Replace "Real" on next line with 
# "Integer", "Currency", "LongInteger", or "SingleReal" if needed 
# based on the targeted axis custom expression output datatype
formatter = DataType.Real.CreateLocalizedFormatter()


# Set the formatter category to Scientific
formatter.Category = NumberFormatCategory.Scientific

# Set "Decimals:" option:
formatter.DecimalDigitsMode = DecimalDigitsMode.Auto  #(Auto) option
# OR
formatter.DecimalDigits = 2  #Any other integer option (0 to 15)


# Apply the formatter to the targeted axis:
# IMPORTANT - Replace "RealFormatter" on next two lines with 
# "IntegerFormatter", "CurrencyFormatter", 
# "LongIntegerFormatter", or "SingleRealFormatter" if needed
# based on the axis custom expression output datatype
myVis.XAxis.Scale.Formatting.RealFormatter = formatter  #Apply to x axis
myVis.YAxis.Scale.Formatting.RealFormatter = formatter  #Apply to y axis

The script below is equivalent to selecting the Number category on the scatter plot properties formatting tab and setting the related options.
This option is only available when the targeted axis has a numeric data type.

from Spotfire.Dxp.Data import * 
from Spotfire.Dxp.Application.Visuals import *
from Spotfire.Dxp.Data.Formatters import *

myVis = myVis.As[Visualization]()

# Create the formatter:
# IMPORTANT - Replace "Real" on next line with 
# "Integer", "Currency", "LongInteger", or "SingleReal" if needed 
# based on the targeted axis custom expression output datatype
formatter = DataType.Real.CreateLocalizedFormatter()


# Set the formatter category to Number
formatter.Category = NumberFormatCategory.Number

# Set "Decimals:" option:
formatter.DecimalDigitsMode = DecimalDigitsMode.Auto  #(Auto) option
# OR
formatter.DecimalDigits = 2  #Any other integer option (0 to 15)

# Use thousands separator:
formatter.GroupSeparatorEnabled = True

# Set "Negative numbers:" option:
formatter.NegativePattern = NumberFormatNegativePattern.NegativeSign
# OR
formatter.NegativePattern = NumberFormatNegativePattern.Parentheses

# Use short number format:
formatter.ShortFormattingEnabled = True


# Apply the formatter to the targeted axis:
# IMPORTANT - Replace "RealFormatter" on next two lines with 
# "IntegerFormatter", "CurrencyFormatter", 
# "LongIntegerFormatter", or "SingleRealFormatter" if needed
# based on the axis custom expression output datatype
myVis.XAxis.Scale.Formatting.RealFormatter = formatter  #Apply to x axis
myVis.YAxis.Scale.Formatting.RealFormatter = formatter  #Apply to y axis

The script below is equivalent to selecting the Custom category on the scatter plot properties formatting tab and setting the related options.

note

More examples and guidelines for creating custom format strings are available here in the online Spotfire help documentation.

from Spotfire.Dxp.Data import * 
from Spotfire.Dxp.Application.Visuals import *
from Spotfire.Dxp.Data.Formatters import *

myVis = myVis.As[Visualization]()

# Create the numeric datatype formatter:
# IMPORTANT - Replace "Real" on next line with 
# "Integer", "Currency", "LongInteger", or "SingleReal" if needed 
# based on the targeted axis custom expression output datatype
formatter = DataType.Real.CreateLocalizedFormatter()
# OR
# Create the DateTime datatype formatter:
# This syntax is used for "DateTime", "Date", or "Time"
# targeted axis custom expression output datatypes
formatter = DataType.DateTime.CreateLocalizedFormatter()


# Create the numeric format string, for example:
formatter.FormatString = "#.00"
# OR
# Create the DateTime format string, for example:
formatter.FormatString = "MM/dd/yyyy"


# Apply the formatter to the targeted numeric axis:
# IMPORTANT - Replace "RealFormatter" on next two lines with 
# "IntegerFormatter", "CurrencyFormatter", 
# "LongIntegerFormatter", or "SingleRealFormatter" if needed
# based on the axis custom expression output datatype
myVis.XAxis.Scale.Formatting.RealFormatter = formatter  #Apply to x axis
myVis.YAxis.Scale.Formatting.RealFormatter = formatter  #Apply to y axis
# OR
# Apply the formatter to the targeted DateTime axis:
# This syntax is used for "DateTime", "Date", or "Time"
# targeted axis custom expression output datatypes
myVis.XAxis.Scale.Formatting.DateTimeFormatter = formatter  #Apply to x axis
myVis.YAxis.Scale.Formatting.DateTimeFormatter = formatter  #Apply to y axis
Welcome!

The purpose of this website is to provide a comprehensive, accurate, and efficient IronPython reference for Spotfire developers.