The Analysis Chart

This topic introduces developers to the Analysis Chart super-element. The Analysis Chart is a dynamic chart set that provides interactive data analysis capabilities.
 


About the Analysis Chart

The Analysis Chart allow users to display charts at runtime, based on a discrete data set and limited to chart types the developer chooses to include.

Chart Canvas charts are used by default by the Analysis Chart, in all new applications. Older Logi applications that are upgraded to v12 will use the classic static charts for their Analysis Charts. To force upgraded apps to use Chart Canvas charts, add the constant rdFavorChartCanvas = True to your _Settings definition.

Like data tables, the Analysis Chart uses child column elements to include data for display.
 


     

The example above shows a typical set of Analysis Chart elements:

  • An Analysis Chart element
  • A DataLayer element to retrieve the data
  • One or more Analysis Chart Column elements to make data available for analysis

Analysis Chart Column elements do not require any child elements, such as a Label element, in order to make data visible. The element's Data Type attribute determines how each column can be used. "Text"-type columns can be used as Label Columns for Pie and Bar charts. "Number"-type columns may be used in the X- and Y-axis of Line and Scatter charts. "Date" columns may be used in the X-axis. In addition, the Format attribute can be used to format the values that appear in tooltips displayed when the cursor is hovered over various chart areas.
 

     

As shown above, the display produced by this element consists of a Control Panel and a Chart Area. By default, the Control Panel will appear above the Chart Area, as shown. However, the Analysis Chart can be configured to display the Control Panel to the left of the Chart Area instead.

The chart's title changes dynamically based on the selections the user makes at runtime; it cannot be set independently by the developer.

Resizing handles, which are only visible when the mouse hovers over the chart, are also provided so that the user can resize the chart at runtime.
 

     

Chart type options, shown above, allow the user to select different chart types at runtime. The types available to the user can be restricted by the developer when configuring the element and will also be limited based on the nature of the data. For example, Pie and Bar chart types are only available when there is at least one Analysis Chart Column with its Data Type attribute set to Text.

The default orientation of bar charts that are not based on a time series is Horizontal, to make it easier to read X-axis label data values. This can be changed at runtime by the user to Vertical.

A built-in Group Filter is available for X-axis (Label) values:
 

For example, if a DateTime type column is selected, the filter appears in the control panel automatically, as shown above. It allows users to group data by Day, Month, Quarter, or Year time periods.

Quicktips are automatically included:
 


As shown above, this feature displays a pop-up "balloon", containing detail data, when the mouse is hovered over a data point. This feature is available for all chart types and no action on the developer's part is required to enable it.

If you're working with very large data sets, you may be able to use a special-purpose datalayer for better performance. You can find out more about it and review the restrictions in DataLayer.ActiveSQL.

This datalayer provides the basic SQL query needed to retrieve data but doesn't initially retrieve and cache all of the result set. Instead, in response to runtime manipulations of the Analysis Chart interface, it dynamically modifies its own SQL query and retrieves the minimum required amount of data with each request. This increases the number and frequency of SQL queries the database server must handle (and, generally, does not prove to be a burden on the database server) but improves performance for the user.

A Zero Rows Message element is available as a child element of the Analysis Chart. This element allows developers to display a customized message if the datasource returns no data. The message text and its font type, size, and color can be set using the element's attributes.
 

Studio Wizard Available

Logi Studio includes a wizard that will help you to build and configure an Analysis Chart:

As shown above, you can launch the wizard from Studio's main menu Wizards tab, or by right-clicking a container element and using its context menus. The wizard will walk you through decisions about connecting to and retrieving data, and about which data columns to use, and will then insert the configured elements into your definition.
 

Retaining User Settings

With all these possibilities, it may be important for users to be able to save their settings between sessions. Settings can be automatically saved on the web server and made available to users during their next session (this is discussed in more detail below).
 

Embedded Sub-Report Caveat

 We do not recommend that you use this element within an embedded sub-report.

Analysis Chart Attributes

The Analysis Chart element can be quickly configured and has the following attributes:
 

Attribute

Description

ID

(Required) Specifies a unique identifier for this element.

Allow Control Hiding

Specifies whether a "gear" icon will be visible that allows the user to hide the control panel.
Default Value: False.

Analysis Chart Types

Specifies a comma-delimited list of the chart types that will be available in the Analysis Chart. Possible values are Pie, Bar, Line, Spline, Scatter, Heatmap and Gauge. "Spline" is the Curved Line chart. The first type in the list will be the initial/starting chart type.

The Pie chart option only appears when there is at least one Analysis Chart Column with Data Type=Text. Bar charts require a column with a Text or Date type.

Batch Selection

Specifies whether the chart will be updated immediately as each control panel item is changed (False) or only when a now-visible OK button is clicked (True). Setting this to True can speed up the user experience by reducing the number of updates requested from the server.

Class

Specifies a user-defined style sheet class to be used with the Analysis Chart. We recommend the use of a Theme for the best appearance.

Color

Specifies the chart colors. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, like #112233. Each bar in a Bar Chart can be made a different color by entering multiple colors, in a comma-separated list.

Control Panel Location

Specifies whether the Control Panel appears above (Top) or beside (Left) the Chart Area. Default value: Top

Height

Specifies the height, in pixels, of the chart image. Does not include the Control Panel. Leave blank for a default size, which can vary by chart type and data.

Save File

Specifies the fully-qualified file path and name of the file to which runtime user configuration changes will be saved. Must include the .xml file extension and can use an @Function token.

Example: @Function.AppPhysicalPath~\SaveFiles\AFSaveFile.xml
Example: @Function.AppPhysicalPath~\UserSaveFiles\@Function.UserName~.xml

Save files can also be stored in a database see Bookmarks.

Security Right ID

When using Logi Security, specifies one or more Security Right IDs, separated by commas. Users with these Security Right IDs will be able to view the Analysis Chart, users without them will not.

Template Modifier File

Identifies a custom XML file developers can create containing elements that will override the same elements in the template file, for language- and culture-customization of captions.

Width

Specifies the width, in pixels, of the chart image. Does not include the Control Panel. Leave blank for a default size, which can vary by chart type and data.

Adding Analysis Chart Columns

The columns available for use with an Analysis Chart consist of one or more columns from the datalayer. Analysis Chart Columns have the following attributes:
 

Attribute

Description

Column Header

(Required) Specifies the text that will appear in the column header.

Data Column

(Required) Specifies the name of the column in the datalayer that will appear in this column.

Data Type

(Required) Specifies the type of data in this column: Boolean, Date, DateTime, Number, or Text.

ID

(Required) Specifies a unique identifier for this element.

Format

Specifies the formatting characteristics of the data. More information can be found in Format Data.

No Aggregates
 

Set to True to prevent this column from being used as an aggregate column for charts. The user will not be able to pick the column from drop-down lists.

No Compare

Set to True to prevent this column from being used as a comparison column. The user will not be able to pick the column from the drop-down list. In general, comparison columns should have a limited number of possible values, since each value appears in the chart legend.

No Grouping

Set to True to prevent this column from being used as a grouping column when building charts, such as Bar, Pie and Heatmap charts. The user will not be able to pick the column from drop-down lists.

Security Right ID

When using Logi Security, specifies one or more Security Right IDs, separated by commas. Users with these Security Right IDs will be able to view the column, users without them will not.

Working with Analysis Chart columns is easy and here's how to add them:
 

  1. In Studio, select the parent Analysis Chart element and add the Analysis Chart Column element.
  2. Set the Column Header and ID attributes.
  3. Set the Data Column attribute to the name of a column returned by the datalayer. Tokens are not necessary here; just providing the column name is sufficient.
  4. Set the Data Type attribute to Text, Number, or Date.
     

 There is no way to make the appearance of an individual Analysis Chart Column conditional.

Studio includes a wizard to assist in adding Analysis Chart Columns. Select and right-click your Analysis Chart element, and use the context menus shown above to launch the wizard.

     

As shown above, the wizard lets you select the columns in the datalayer to use with the chart and to set their data types. The wizard can be launched by selecting the Analysis Chart element and then either clicking it in the main menu's Wizards tab or right-clicking and selecting it from the element's Element Wizards pop-up menu.

Adding a Second Series

It's frequently useful to add a second series to the chart, allowing easier visual comparisons. Controls are available for this:
 

When the chart type (Bar, Line, Curved Line, Scatter Plot) supports it, the (1) Additional Column control will be available for you to use in selecting the Data Column for a second series. The second series (2) Aggregation and (3) Chart Type can be selected to suit your needs. A second axis and label will appear automatically along the side of the chart opposite the original Y-axis, as shown above.

Adding Forecasting

Forecasting features are included in the Analysis Chart. These features use a variety of techniques to produce projected values by analyzing existing values. Forecasting is available for Bar, Line, and Curved Line chart types.
 

Forecasting is enabled in an Analysis Chart by including a Data Forecast element beneath it, as shown above. This element has no attributes.
 


     

When the Data Forecast element is present and an appropriate X-axis column is selected, a special selection list (1) of forecast options will become visible in the control panel, as shown above. When an option is selected, the forecast data is displayed in the example chart as an extra set of bars. In other chart types, it might appear as a dotted line.

If the X-axis column is of DateTime type, the data may be analyzed using either Time Period Decomposition or Regression analysis; columns of Numeric type are analyzed using Regression analysis. An additional option list (2) allows selection of a time span for Time Period Decomposition analysis, or a regression method for Regression analysis. Available regression methods include:

  • Linear/Trend
  • Autoregressive (using "Burg's" formula)
  • Exponential
  • Logarithmic
  • Polynomial (orders 2 - 5)
  • Power

The forecast options also include Trend Line, with straight or curved presentation options.

he Studio wizard for creating an Analysis Chart also includes forecasting options. More information about forecasting is available in Forecast Methodologies.

Saving Individual User Settings

A described earlier, the Analysis Chart will automatically save a user's runtime configuration changes during their session, if the Save File attribute is set. The file specified will be created if it does not exist but its containing folder is not automatically created. You must ensure that the account used by the web server to run the application has "Write" permission to the folder.

Save files can also be stored in a database, see Bookmarks.

You can also save separate configurations for each user that survive their session. If Logi Security is being used, include the @Function.UserName~ token as part of the Save File name. If not, use @Function.GUID~ to generate a unique file name for the user and save the file name as a cookie in the user's browser.

Users' settings can be cleared by calling the Analysis Chart report with the rdAcReset parameter set to True. To get fresh data from the datasource while maintaining the user's settings, call the report with the rdAcRefreshData parameter set to True.
 


In the example above, a Label has been added to an Analysis Report as a link that clears the user's settings. The Target.Report element is set to Current Report and the Link Parameters element is used to pass the rdAcReset parameter.

Adding Charts to Dashboards

An exciting level of interaction between the Analysis Chart and the Dashboard element is available. Users working with an Analysis Chart in one report, at runtime, can generate a chart and then, with one mouse click, add it as a new panel in an existing Dashboard in another report.

When properly configured, the Analysis Chart will display an Add To Dashboard icon, as shown above.

When the icon is clicked, the chart is added as a new panel in the Dashboard, as shown above.

Behind the scenes, when the icon is clicked, the Analysis Chart writes the underlying XML for its chart into the Dashboard's configuration file (its "Save File"). In the Dashboard, the chart is inserted at the top of Column 1; if Dashboard tabs are being used, the insertion occurs in the currently active tab.

Just before panel insertion, the user will be prompted for the Panel Title and a description for display on the Configuration Page.

The new chart panel thereafter appears in the Dashboard Configuration Page, as shown above, just like any other panel, complete with a thumbnail image. The new panel can be removed from the visible dashboard panels and from the configuration page entirely, using the usual controls.

The user can insert multiple tables and charts into a Dashboard using this technique.

In the report definition, the developer makes this functionality available by adding a Custom Dashboard Panels element, shown above, beneath the Analysis Chart element. Its Dashboard Save File attribute value should be set to match the target dashboard's Save File attribute value.

 The Save File attribute values shown above have been shortened for visual clarity. However, a fully-qualified path and file name, with .xml extension, is required, so a realistic attribute value would be something like:

    @Function.AppPhysicalPath~\DashFiles\DashbdSave.xml

and the account the Logi application runs under must be given Write permissions to the "DashFiles" folder. For experimentation purposes, you can use the rdDownload folder, for which appropriate permissions already exist (but its contents are periodically deleted, so don't use it for anything but experimentation).

Dashboard Save Files are often named using a token, such as @Function.UserName~, in order to create personalized dashboard configurations and, in that case, the Custom Dashboard Panel attribute would use the same token.

The Custom Dashboard Panels element has a new attribute, Add Caption, which sets the caption for the button used to save the data table or chart. If left blank, the caption is "Add to Dashboard".

For more information about Dashboards, see Logi Info Dashboard.

Customizing Analysis Chart Appearance

Analysis Chart appearance can be changed most easily by applying a theme to the report definition. Most of the screen shots in this document were taken with the Signal theme applied.

You can create your own custom theme, based on a standard theme, using the Theme Editor tool.
 

Changing Appearance Using Style Classes

Analysis Chart appearance can be also customized using style classes and Info Studio provides the following standard style sheet for all Analysis Charts:

    <YourAppFolder>\rdTemplate\rdAnalysisChart\rdAcStyle.css

Developers can override classes in this style sheet by copying them to their application style sheet and modifying them there.

  Do not make changes in the standard style sheet in the rdTemplate folder.
 

Changing Appearance Using Template Modifiers

The Analysis Chart element uses a "template file" to define certain element properties that are not otherwise available as attributes to the developer for modification. These include language- and culture-specific Caption attributes that you may want to change to match the locale (or you may simply want to change the captions to better suit your application).

The Analysis Chart element's Template Modifier File attribute identifies a custom XML file developers can create containing elements that will override the same elements in the template file.

For example, the Analysis Chart template file:

    <yourAppFolder>\rdTemplate\rdAnalysisChart\rdAcTemplate.lgx

contains several Label elements. One of them has an ID of "lblChartXLabelColumn_rdAcID"; this controls the caption text that appears beside the Label Column input select list. This text can be modified by changing the Caption associated with that Label element. To change the text from its default "Label Column" to "X-axis Data Column", create your own XML file, identify it in the Template Modifier File attribute, and add this code to it: 

<TemplateModifier>
    <SetAttribute ID="lblChartXLabelColumn_rdAcID" Caption="X-axis Data Column" />
</TemplateModifier>

You can set the attributes for any number of elements in this file; examine the rdAcTemplate.lgx file to learn the ID and Caption attributes available. The template modifier file can be in any folder accessible to the web application; if a fully-qualified file path is not provided in the Template Modifier File attribute value, then the application expects the file to be in its _SupportFiles folder.

More detailed information about template modifier files can be found in Template Modifier Files.