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 shipped with beta versions of the new Visualization API, side-by-side with the previous Visualization API version. In version 8.3, the Pentaho platform ships with the release version of the new Visualization API, while still side-by-side with the previous Visualization API version.

Visualization format of stock visualizations

The Analyzer application supports visualizations of both formats, allowing you to convert any custom visualizations of the previous format at your own pace.

All stock visualizations, with the exception of the Geo Map, are available in the new format.

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.

You can choose which format of stock visualizations Analyzer uses 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 change the way it displays but not the saved report file. 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.

Differences between the stock visualizations of the previous and new formats

The new stock visualizations are not totally identical to the corresponding previous ones. The following sections describe the most notable 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. The change of visualization format requires custom visualizations to be converted, by hand.
  2. Visualization configuration is performed in a different way, so existing Analyzer visualization configurations need to be migrated; see Migrating visualization settings.
  3. Custom translations for properties of stock visualizations may not work anymore.

Known issues

  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",
             annotation: "pentaho/analyzer/visual/Options"
           },
           apply: {
             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