Analyzer and the Visualization API

Overview

Pentaho Analyzer reports display visualizations that are based on the Pentaho Visualization API.

As of version 7.1, the Pentaho platform ships with the new version of the Visualization API, still in beta, side-by-side with the previous version.

Analyzer supports visualizations of both formats, allowing you to evaluate and immediately take advantage of the new format, and to convert any custom visualizations of the previous format at your own pace.

All stock visualizations, with the exception of the Geo Map, are already available in the new format and you can choose which format you want Analyzer to use, by configuring an Analyzer setting (see Changing the visualization format of stock visualizations). This setting does not affect reports that use a custom (non-stock) visualization — these will continue to use their visualization format, whether it is the previous or new.

Once you choose to use the new format of stock visualizations, viewing a previously saved report, with a visualization of the previous format, will not change it in any way. However, if you save it, it will be irreversibly upgraded to use the new format. If you later decide to switch-back Analyzer to using the previous format of stock visualizations, the visualization part of this report will not be available and the report will be displayed in the Pivot table view.

Remember

When you choose to try out the new format of stock visualizations:

  1. For precaution, be sure to create a backup of your existing Analyzer reports.
  2. To be sure that you are satisfied with the new experience, test all of your existing Analyzer reports before saving any of them.

Fresh Pentaho installations are configured to use the new format stock visualizations, while upgrade installations are configured to keep using the previous format stock visualizations.

Differences between the stock visualizations of the previous and new formats

The new stock visualizations are not totally identical to the corresponding previous ones. Most changes are intentional, enabling new features or fixing faulty behaviours, while others are still work in progress, and expected to change when coming out of beta.

The following sections describe the differences that new stock visualizations have relative to the previous stock visualizations.

Usability and Style

  1. Visualizations scroll horizontally and vertically when too many axis categories exist, instead of shrinking to available space.
  2. Selection is either enabled or not, depending on whether there are no gems in the Pivot “Column” gem bar, while there used to be an intermediate selection state where some partial selections were possible if only one gem was in the Pivot “Column” gem bar.
  3. General styling of visualizations changed to be aligned platform-wide (e.g. PDI, CDF).
  4. Standard color palettes have changed to be aligned platform-wide (e.g. PDI, CDF).

Breaking changes

  1. Visualization configuration is performed in a different way, so existing Analyzer visualization configurations need to be migrated; see Migrating visualization settings.
  2. Custom translations for properties of stock visualizations may not work anymore.

Work In Progress

  1. Printing of scrolled charts shrinks them to fit (while preserving their aspect-ratio).
  2. Printing only reflects custom configurations that are located in the Global Configuration File.

Changing the visualization format of stock visualizations.

In a Pentaho Server installation, go to the Analyzer plugin folder, located at pentaho-server/pentaho-solutions/system/analyzer and open the settings.xml file.

Find the <viz-api-version> setting and change its value according to the desired stock visualization format:

Save the file and restart Pentaho Server.

Migrating visualization settings

Visualizations of the previous format can be configured in Analyzer
through properties in its analyzer.properties file, located at pentaho-server/pentaho-solutions/system/analyzer, in a Pentaho Server installation.

Visualizations of the new format are however configured using the platform-wide JavaScript configuration system, and so, the Analyzer previous format visualization settings must be migrated to it.

General visualization properties

Take the example of a configuration that changes the default value of the “Line width” property of “Line chart” visualizations.

  1. Previous format, in analyzer.properties:

     viz.ccc_line.args.lineWidth=1
    
  2. New format, in a platform configuration file:

     define(function() {
       return [
         {
           select: {
             application: "pentaho-analyzer",
             module: "pentaho/visual/models/Line"
           },
           apply: {
             props: {
               "lineWidth": {defaultValue: 1}
             }
           }
         }
       ];
     });
    

To perform the translation, all you need to know is the correspondence between, previous and new, visualization identifiers and property values.

The maxValues property

Take the example of a configuration that changes the possible maximum number of results for “Bar chart” visualizations.

  1. Previous format, in analyzer.properties:

     viz.ccc_bar.maxValues=250,500,1000,5000
    
  2. New format, in a platform configuration file:

     define(function() {
       return [
         {
           select: {
             application: "pentaho-analyzer",
             module: "pentaho/visual/models/BarHorizontal"
           },
           apply: {
             application: {
               maxValues: [250, 500, 1000, 5000]
             }
           }
         }
       ];
     });
    

The chart.series.colors property

This property allows changing the default discrete color palette.

  1. Previous format, in analyzer.properties:

     chart.series.colors=#0045a1,#5f9e00,#ffc20f,#ff6600,#3c008f
    
  2. New format, in a platform configuration file:

     define(function() {
       return [
         {
           select: {
             application: "pentaho-analyzer",
             module: "pentaho/visual/color/palettes/nominalPrimary"
           },
           apply: {
             colors: [
               "#0045a1","#5f9e00","#ffc20f","#ff6600","#3c008f"
             ]
           }
         }
       ];
     });
    

Correspondence between visualization identifiers

Current Vis. Id. Future Vis. Id. Description
ccc_area pentaho/visual/models/AreaStacked Area Stacked
ccc_line pentaho/visual/models/Line Line
ccc_bar pentaho/visual/models/Bar Column
ccc_barstacked pentaho/visual/models/BarStacked Column Stacked
ccc_barnormalized pentaho/visual/models/BarNormalized Column Stacked 100%
ccc_horzbar pentaho/visual/models/BarHorizontal Bar
ccc_horzbarstacked pentaho/visual/models/BarStackedHorizontal Bar Stacked
ccc_horzbarnormalized pentaho/visual/models/BarNormalizedHorizontal Bar Stacked 100%
ccc_barline pentaho/visual/models/BarLine Column/Line Combo
ccc_scatter pentaho/visual/models/Bubble X/Y Scatter/Bubble
ccc_heatgrid pentaho/visual/models/HeatGrid Heat-Grid
ccc_pie pentaho/visual/models/Pie Pie
ccc_sunburst pentaho/visual/models/Sunburst Sunburst

Correspondence between visualization property values

Property Name Value changes
labelsOption
  • inside_end"insideEnd"
  • inside_base"insideBase"
  • outside_end"outsideEnd"
pattern
  • ryg_3"ryg-3"
  • ryg_5"ryg-5"
  • ryb_3"ryb-3"
  • ryb_5"ryb-5"
  • blue_3"blue-3"
  • blue_5"blue-5"
  • gray_3"gray-3"
  • gray_5"gray-5"
lineWidth The number in the properties file passes verbatim to a JSON number value.
trendLineWidth
emptySlicesHidden The true or false value in the properties file passes verbatim to a JSON boolean value.
reverseColors
colorSet The textual value in the properties file is wrapped in quotes to form a JSON string value. E.g.:
  • circle"circle"
lineLabelsOption
shape
sliceOrder
trendName
trendType