Expressions may define calculations used in the axes of visualizations. They are often referred to as dynamic, since the expressions are recalculated based on changes to the analysis.
Overview
Axis Expressions may be defined in direct interaction with a visualization or programmatically. These expressions define the data that is mapped to an axis in a visualization. Remember that the term axis not only refer to the X and Y axes, but is a general term for the mapping of data to a dimension represented in the visualization: Coloring is controlled by the Color axis, marker shape by the Shape axis and so forth.
This article explains how to use expressions when configuring visualizations via the API. To explore the available methods, launch the custom expression editor from the context menus of the axis selectors in visualization. Defining expressions graphically in the UI before creating them programmatically will speed up learning.
Note: The Spotfire Metrics license is required to use axis expressions in the UI, but not from the API.
Axis Binding Example:
- Axis Binding
Axis binding retrieves the currently marked value in a column as base for an axis expression. It is used to set up visualizations with axis expressions changing in response to marking in other visualizations.
See also:
Categorical or continuous expressions
Expressions are either continuous or categorical. Categorical expressions are embraced by angle brackets: The expression X is continuous, whereas the expression <x> is categorical.
An axis may support categorical expressions, continuous expressions, or both. This depends on the axis in question. The Y axis of a scatter plot, for instance, can be either continuous or categorical, but the Y axis of a bar chart only supports continuous expressions. The following example shows how to create a bar chart and set expressions on the XAxis, YAxis and ColorAxis:
public void CreateBarchart(AnalysisApplication application)
{
// Create the bar chart
BarChart barChart = application.Document.ActivePageReference.Visuals.AddNew<BarChart>();
// Connect the bar chart to data
DataManager dataManager = application.Document.Data;
barChart.Data.DataTableReference = dataManager.Tables.DefaultTableReference;
// Set filtering for the visualization
barChart.Data.UseActiveFiltering = true;
// Set marking for the visualization
barChart.Data.MarkingReference = dataManager.Markings.DefaultMarkingReference;
// Put the column named Year on the x-axis. Put angles around it to make it categorical.
barChart.XAxis.Expression = "<Year>";
// Put sum of column sales on the y-axis. This is a continous expression.
barChart.YAxis.Expression = "Sum(Sales)";
// And finally color categorically by the column named Region
barChart.ColorAxis.Expression = "<Region>";
}
Depending on what data you have, the bar chart will look something like this:
Continuous Expressions
A continuous expression may be as simple as a column name, for instance Sales. Often an aggregation method is applied along the axis, like Sum(Sales) in the example above.
Some axes, usually Y axes, support multiple expressions. These are separated by commas: Sum(A), Sum(B). In this case a categorical axis must be specified to distinguish the parts in the expression. In the user interface this is done by selecting (Column Names) from the axis selector.
On the expression side, this is represented by <[Axis.Default.Names]>:
void SetColorByColumnNames(BarChart barChart)
{
barChart.ColorAxis.Expression = "<[Axis.Default.Names]>";
}
Categorical Expressions
A categorical expression may also be as simple as a column name, but embraced by angle brackets: <year>. Categorical expressions can be used to create hierarchies. When creating hierarchies the values of the columns can optionally be combined using the CROSS and NEST operators:
<A CROSS B> creates a hierarchy with values for all possible combinations of values in the columns A and B.<A NEST B> creates a hierarchy with values only for the combinations that have data.
One would expect a change of axis expression from NEST to CROSS to dramatically alter the visualization, but it is very likely not to change. The reason is that another axis property also influences the final result: ShowAllCategories defaults to false, and unless it is set to true, categories that do not contain any data will not be shown. The reason they will not be shown is either that the combination of values do not exist in the data, or that they have been filtered out.
Referring to Columns
When referring to column, it is good practice to surround the name with square brackets. This is really only needed when column names contain certain characters, such as spaces: The expression Sum(Sales Total) is invalid and must be written as Sum([Sales Total]). Additional brackets do not turn up in the user interface, since it is tidied up prior to display.
Columns names containing ] may be used but must be escaped since the square bracket character is use for delimiting identifiers. Replace ] by ]]. For instance, refer to a column named column[0] as [column[0]]]. The ExpressionUtilities class provides methods for escaping and unescaping column name identifiers.
Expression (None)
When clearing the expression on an axis, remember that the expression also controls if the axis is continuous or categorical. There is a difference in setting the expression to the empty string, meaning continuous, and <>, meaning categorical. Setting a continuous expression on an always categorical axis like trellis axes, will throw an exception. The user interface display axes with empty expressions like this: 
Aggregation (Row Number)
The (Row Number) option in the axis selector enables the use of an implicit row number in the data table being visualized: 
This is represented by the expression <baserowid()>. It is important to understand the logic behind this expression.
By default, most visualizations are aggregating: They try to aggregate all data to a single marker, bar or line. The aggregation can be split by categorical or non-aggregating expressions on any axis. When a visualization is aggregating, the application will display aggregation context menus for continuous axes, and automatically apply aggregation methods when the user selects a column for an axis. For some visualizations, setting the expression <baserowid()> on a certain axis turns aggregation off. But note that for some visualization the default behavior here will vary depending on if the plot is created via the API or via the user interface:
| Visualization |
Aggregating by default |
Axis that turns on/off aggregation |
| Bar Chart |
Yes |
N/A |
| Line Chart |
Yes |
N/A |
| Scatter Plot |
Yes, but turned off when created via UI |
MarkerByAxis |
| Parallel Coordinate Plot |
Yes, but turned off when created via UI |
LineByAxis |
| Pie Chart |
Yes |
N/A |
| Box Plot |
No |
N/A |
| Map Chart |
Yes |
MarkerByAxis |
| Cross Table |
Yes |
N/A |
| Summary Table |
Yes |
N/A |
| Table |
No |
N/A |
Example: Setting up a non-aggregating scatter plot
void CreateScatterPlot(AnalysisApplication application)
{
// Add a scatterplot to the page
ScatterPlot scatterplot = application.Document.ActivePageReference.Visuals.AddNew<ScatterPlot>();
// Connect the scatterplot to data
DataManager dataManager = application.Document.Data;
scatterplot.Data.DataTableReference = dataManager.Tables.DefaultTableReference;
// Set filtering for the visualization
scatterplot.Data.UseActiveFiltering = true;
// Set marking for the visualization
scatterplot.Data.MarkingReference = dataManager.Markings.DefaultMarkingReference;
// Set marker by (Row Number) to get one marker per row in
// the data set.
scatterplot.MarkerByAxis.Expression = "<baserowid()>";
// X Axis
scatterplot.XAxis.Expression = "Cost";
// Y Axis
scatterplot.YAxis.Expression = "Benefit";
}
Binning
Binning can be performed with a number of methods but one is more commonly used than others, the BinByEvenIntervals method. It is used in the auto-bin feature. When an expression of the form <BinByEvenIntervals([Sales Total],23)> is set on an axis the application will display it with a binning slider: 
Hierarchies
Although it is possible to define a hierarchy dynamically directly on an axis, it is often convenient to use hierarchies defined as part of a data table. These hierarchies behave like columns in many ways, but cannot be used the same way in expressions:
- Qualify the name: A hierarchy named
Location needs to be referred to as Hierarchy.Location.
- Use the
PruneHierarchy method to specify how much of the hierarchy that should be expanded: To show the data at Region level for a hierarchy named Location with the levels Country, Region and City, use the expression <PruneHierarchy([Hierarchy.Location], 1)>.
The user interface displays the following hierarchy slider: 
This kind of hierarchy can be combined with other expressions to create more complex hierarchies. The previous hierarchy may be nested with a Person column in the expression <PruneHierarchy([Hierarchy.Location], 1) NEST [Person]>.
OVER Expressions
Over Expressions is a powerful feature enabling the computing of aggregated values over subsets in the visualizations. For instance they can be used to create bar charts showing the accumulated sum over the values on the X axis. For an introduction to OVER expressions, refer to the TIBCO Spotfire User's Guide.
Case sensitivity
Finally a note on case sensitivity:
- Column names are case sensitive:
[Column 1]
- Methods are not case sensitive:
Sum()
- Keywords are not case sensitive:
NEST, OVER, AS