Series.Pie

The Chart Canvas element's Series child elements cause a data visualization (the chart) to be rendered in the canvas. This topic discusses the Series.Pie element.

About Series.Pie

The Series.Pie element generates a Pie chart, which is a circular chart divided into sectors, illustrating numerical proportion.
 

The example above shows a simple Pie chart, presenting one month's sales of different product categories.

 

As shown above, the chart is created by adding Series.Pie to the canvas, along with a datalayer and, typically, some child elements that may include Time Period Column elements, a Group Filter, and a Group Aggregate Column element. Very few attributes need to be set for the Series element in order to produce a basic chart. In the example, a list of custom wedge colors was provided.

Note that a datalayer element can be used either beneath Series.Pie, as shown above, or beneath Chart Canvas. If used as a child of Chart Canvas, its data is available to all child Series elements. This can improve performance if you have several series, all using the same data, beneath the same Chart Canvas element.


The properties of the X- and Y-axis, including captions, are set using the X-Axis and Y-Axis elements. For example, in order to angle the X-axis labels, add an X-Axis element beneath Chart Canvas (none of its attributes need to be set) and add its child Label Style element. Set the Label Style element's attribute as shown above.

Back to top

Shaping the Pie

You can control the shape of the Pie chart in several ways.
 

The example above shows a Pie chart with a "donut hole" in its middle. This is controlled by setting the Series.Pie element's Donut Hole Size attribute to a value, in pixels, equal to the diameter of the hole.

The example above shows a Pie chart that only fills part of the usual 360-degree pie space. This is created by using the Series.Pie element's Angle Start and Angle End attributes. The example uses Angle Start = 270 degrees and Angle End = 450 degrees. How do we come up with those numbers?
 

Assume we want a Pie chart that's a half-circle, above the equator, like our previous example. To find the starting angle, we navigate clockwise around a circle to the starting point, as shown above left, to 270. Then to find the ending angle, we add the number of degrees in a half-circle (180) to the starting angle, or 270 + 180, which equals 450, as shown above, right. Using this method, you can create a Pie chart that's any portion of a complete circle.

Back to top

Using Multiple Series

Just as it is with other Series, it's possible to add multiple Pie charts to one Chart Canvas.
 

Overlaying Pie charts can produce "visual clutter" that's hard to decipher (and that's without any data labels displayed), as you can see in the example above, left. In the example above, right, however, the second Series has been configured so that it's off center, using its Center X and Center Y attributes, which provides a little more clarity.

When using multiple series, you may be able to reduce the number of data queries and improve performance by using local data to read all of the data once, see Datalayer Introduction. Then, link its datalayer to share it to the series, see Link Datalayers.At each Series element, link its datalayer to the shared Local Data datalayer and filter the data to meet the needs of each individual series.

You can combine different types of Series elements, for example, Series.Pie and Series.Line, to produce combinations of visualizations.

Back to top

Attributes

The Series.Pie element has the following attributes:
 

Attribute Description

Y-Axis Data Column

(Required) Specifies the name of a datalayer column whose values will be plotted along the Y-axis, dictating how large each pie slice is.

Angle End

Sets the ending angle of the Pie chart's last slice, in degrees. For example, to create a Pie chart which has 180 degrees total, facing upwards, set these attributes: Angle Start = 270, Angle End = 450

Angle Start

Sets the starting angle of the Pie chart's first slice, in degrees. The default value of 0 starts the first slice at the 12 o'clock position and a value of 90 is the 3 o'clock position.

Border Color

Sets the color of the border line around the pie and around each slice. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, like #112233.

Border Color Transparency

Specifies the transparency of the border line. The lowest value of 0 specifies that the background is opaque, with no transparency. At the other end of the scale, 15 specifies a completely transparent background. Use medium-level transparency to allow different chart layers to show through each other.

Border Thickness

The thickness of border line around the pie and around each slice, in pixels. The default is value is 1 pixel.

Center X

Sets the horizontal center point of the Pie chart, in pixels, within the canvas.

Center Y

Sets the vertical center point of the Pie chart, in pixels, within the canvas.

Colors

Sets the colors of the pie slices, which should be entered as a comma-separated list. Enter a color by name, decimal RGB value, or hex RGB value. Prefix hex values with the pound sign, e.g. #112233. When there are more slices than colors specified, the listed colors are used again from the beginning. A default set of colors is used if this is left blank and no theme has been applied, see Chart Canvas Charts.

Disable Mouse Tracking

Disables mouse tracking for the series, when set to True. This affects tooltips and click events on graphs and points. For large datasets, this may improve performance.
The default value is False.

Donut Hole Size

Sets the size of the inner diameter of the Pie chart, in pixels. Any size greater than 0 renders a "doughnut" style chart. The default value is 0 pixels.

Hover Brightness

Specifies the amount to change a pie slice's color when the mouse pointer is hovered over it. Values can be between 0 (no change) and 15 (lighter). The default value is 2.

Label Data Column X-Axis

Set this to a column returned from the DataLayer. It represents the "name", or x-axis value, of each pie slice.

Label Location
 

Specifies how Pie chart slice labels will appear. Select:

- SideLayout to have labels appear outside the pie, with arrows connecting them to slices.
- Legend to have slices identified in a legend. The legend can be clicked to toggle the visibility of individual slices in the pie.
- NoLabels to hide the labels altogether.

The default value is SideLayout.

Min Radius

Sets the minimum acceptable size of the pie chart, in pixels. During rendering, the pie radius will try to shrink automatically, if necessary, to accommodate any exterior slice labels and still fit the canvas, but it can be no smaller than this size.

Pie Label Style

Specifies how Pie chart slice labels will appear. Select:

- SideLayout to have labels appear outside the pie, with arrows connecting them to slices.
- Legend to have slices identified in a legend. The legend can be clicked to toggle the visibility of individual slices in the pie.
- NoLabels to hide the labels altogether.

The default value is SideLayout.

Radius

Determines the size, by setting the radius, of a Pie chart, in pixels. If left blank, the chart size is determined automatically.

Show Data Values
 

Specifies if the value of each data point should be shown on the pie chart. Depending on the value of the Label Location attribute, they may be shown alone or with the label values. The default value is False.

Show Data Values Format
 

Specifies formatting characteristics for data values. For dates, the non-specific formats, such as General Date, Short Time, etc., are converted according to the browser's international settings. For very large reports, the non-specific formats perform better. Special formats include:

< and > -  change strings to lower and upper case.
Expanded Spaces - preserves space characters that would otherwise be collapsed by the web browser.
mp - formats numbers with the "metric prefix". For example, to format 1,234,567 as "$1.23M", enter $#.00mp. Supported metric prefixes are from 1000^6 to 1000^-6. For more information see http://en.wikipedia.org/wiki/Metric_prefix.

qq - returns the number of the quarter when the value being formatted represents a date. To return the year and quarter together like "2010 Q1", set the format to yyyy Qqq.

Transparency

Specifies the transparency of the pie slice color. The lowest value of 0 specifies that the background is opaque, with no transparency. At the other end of the scale, 15 specifies a completely transparent background. Use medium-level transparency to allow different chart layers to show through each other.

Back to top

Adding Data Labels

A "data label" is text that can be shown adjacent to each pie slice that shows its X-axis data value. This is controlled using the Label Location attribute.
 

As shown above, labels can be placed beside the slices, or in a legend, or not shown at all.

When side labels are shown, the Side Label Style element can be used to style them and their connector lines.

When the legend option is selected, "legend filtering" is active: clicking a slice's entry in the legend will toggle its appearance in the chart. For more information about legends, see CCC Legend.

If you want to show the data values instead of, or with, the data labels near each pie slice, as shown above, use the Series.Pie element's Label Location, Show Data Values, and Show Data Values Format attributes.

In the example shown above, the data values are displayed as percentages. This is done by adding a Percent of Total Column element to your datalayer and using it as the chart's Y-axis Data Column. The Show Data Values and Show Data Values Format attributes are then set as shown.

The values displayed can also be styled using the Side Label Style element. Its attributes allow you to control the font family, color, size, and weight, the data format, background color, border color, connecting lines and more. The side labels in the image above have been styled.

The Side Label Style element's Maximum Label Length attribute lets you specify the maximum number of characters that will be displayed for a label before the text is truncated and ellipsis (...) is appended.

Back to top

Using the Quicktips Element

By default, a "quicktip" is displayed when the mouse hovers near or over a pie slice:
 

The automatically-generated quicktip displays information for the X- and Y-axis, as shown above, left. However, you may want to display other information or format it differently, perhaps as shown above, right. This "custom" Quicktip is created by adding a Quicktip child element beneath Series.Pie and setting its attributes and, optionally, using its Quicktip Row child element. Use @Chart tokens to include chart data in the Quicktip.
 

The example above shows another custom Quicktip in use and this time the chart data values are displayed in the Quicktip as percentages. This is done by adding a Percent of Total Column element to your datalayer and using its @Chart token in a Quicktip Row element's Value attribute. The Quicktip Row element's Format attribute is then set to Percent, as shown.

Intrinsic functions are supported in the Quicktip attributes.

The Quicktip Row element has been made context-sensitive with the addition of a Condition attribute.

Back to top

Using the Chart Drill To Element

The Chart Drill To element, a child of the Series element, enhances charts by allowing users to examine the data "behind" the chart.

 The parent Chart Canvas element must have an ID attribute value in order to use the Chart Drill To element with it.
 

As shown above, when this element is being used, clicking a pie wedge displays a list of columns. Selecting a column re-draws the chart so that only the data representing the clicked wedge is shown:
 

After drilling to a column, the user can click a button to "drill back", as shown above. It's also possible to continue drilling further down into the data (assuming the elements are configured for it) by clicking a wedge again.

Chart Canvas Charts that use the Chart Drill To element can only have a single Series.

The Drill Back button only appears when the mouse cursor is hovered over the upper right-hand corner of the chart.

As shown above, the Chart Drill To element drills into grouped data, so the datalayer used beneath the Chart Canvas Chart or Series element must be grouped using a Group Filter or Sql Group element. The example datalayer has been grouped on the CategoryName column and Keep Grouped Rows = False.

The Series itself has been configured so that its Label Data Column = CategoryName and its Y-axis Data Column = gacProductSales (the Group Aggregate Column that sums the ProductSales values).

Next, a Chart Drill To element has been added beneath the Series element, as shown above. Required child Drill To Column elements have also been added; they define the columns the user can select to drill into. They should be added and configured for columns that can be reasonably grouped, such as text-type columns with a limited number of unique values and date-type columns.

You must also configure a Drill To Column element for the column that's specified as the chart's Label Data Column, in this example the CategoryName column.

The Column Header attribute specifies the text that will appear in the Drill to Column drop-down list options. The vertical order of the drop-down list options will match the vertical order of the Drill To Column elements in the definition. Year, Quarter, and Month options will be added automatically for Drill To Columns with Data Type = Date. You do not need to add any filter or additional grouping elements to achieve the results shown in the example above.

The Drill Back button displayed on the chart after drilling has occurred can be styled using the Drill Back Button Style element.

Back to top

Using Action Elements

Action elements initiate processing of a report or process task definition, redirection to a link, or other processing when a pie slice is clicked.
 

In the example above, an Action.Report element has been added as a child of the Series, along with its Target.Report and Link Parameters child elements. To reference chart data in parameters, use the @Chart token, as shown above.

A variety of Action elements are available for use with Series, including Action.Link, Action.Process, and Action.Refresh Element. Additional Action elements will be added in future releases.

Back to top

Using Input Selection

This series can also be used with the Input Selection family of elements, which turn the chart into an input control. This allows users, at runtime, to select points or values on the chart with their mouse and your report can then take action using the selected data. This is very useful, for example, for drilling into the data.

For more information about this functionality, see Input Selection for Chart Canvas Charts.

Back to top

Using the Refresh Series Timer

The Refresh Series Timer, added as a Series child element, updates charts automatically, based on a time interval. When the interval is reached, a request is sent back to the web server for updated data. Series are updated with a smooth animation.

The Refresh Interval attribute specifies the number of seconds to wait before refreshing the series data. A value is required and must be an integer greater than 0.
 

Refresh Mode

Series may be refreshed in two ways: either all of the data is refreshed with each request, or the series data automatically slides to the left one data interval per refresh. The refresh mode is selected in the Chart X Axis element's Axis Type attribute.

When the Axis Type is not set to DateTimeLinear, all of the data will be refreshed.

When the Axis Type value is DateTimeLinear, newer values are added to the right side of the chart, previous values slide left, and older values disappear as they reach the left edge of the chart. In this case, the Refresh Series Timer element's Time Span attribute is used to specify the age of the data included. This value must be in hh:mm:ss format (for example "00:02:00" for two minutes) and must be larger than the Refresh Interval attribute value.

When a Time Span attribute is set, the series' datalayer can make use of a special timestamp token, @Chart.rdTimeSpanStart~, in a query to retrieve just the rows necessary to update the chart. On the initial request, this token returns the current time minus the Time Span value. For subsequent refreshes, when Axis Type = DateTimeLinear and the X-axis will be sliding, the token returns the last time the chart was updated, so only the newest rows are retrieved. Here's an MS SQL Server query example:

    SELECT * FROM MyTable WHERE UpdateTime BETWEEN '@Chart.rdTimeSpanStart~' AND '@Function.DateTime~'

For best performance, avoid setting a very short refresh interval if a very large number of users will be displaying the report.

Back to top