SetPieLabelType

SetPieLabelType — Set type and format for pie chart labels

Synopsis

$plot->SetPieLabelType($source, [$type], [...])

Description

SetPieLabelType sets the type and format of labels which will be displayed on a pie chart. The labels identify the segments of the pie. They can show the segment percentage, a numeric value, or a text string.

Parameters

There is one required argument, $source, following by an optional argument $type. If $type is present and not empty, additional arguments are required.

$source

A string or array indicating the source of the label. If a string, it must be one of the following values (see notes for more details):

SourceDescription
indexUse the ordinal number of the segment (starting at 0)
labelUse the label string from the data array
percentUse the segment's percentage of the whole pie
valueUse the numeric value of the segment

An empty string (or NULL) restores the default pie chart label source and format type.

An array of strings can be used. Each element in the array must be one of the string values above. PHPlot will join the multiple sources for the label, separating each pair with a space. This can be used with custom formatting types to have pie chart labels with multiple fields (such as percentage and label, or label and value). See notes below for more.

$type

Optional argument indicating how to format the label string. If supplied, it can be one of the following: data, printf, or custom. If the argument is missing or an empty string, this indicates that the default of no formatting should be used. If the argument is provided and not empty, additional arguments are required or optional as shown below.

If the $type argument is data, there are three optional arguments:

$precision

The formatting precision, or number of decimal places (optional). If omitted, the default is 1.

$prefix

A prefix string to be placed before the formatted label values.

$suffix

A suffix string to be placed after the formatted label values. When $source is percent, a percent sign '%' should be specified as the suffix.

If the $type argument is printf, there is one optional argument:

$format

Formatting string, used with sprintf(). The formatting string must contain exactly one conversion specification (%-code) which consumes a single argument. If omitted, the default value of '%e' uses scientific notation with default field sizes.

If the $type argument is custom, there is one required argument and one optional argument:

$callback

A callback function to format the label. This is either the name of a function (as a string), or a two-element array with an object instance and method name. (Refer to the PHP documentation for more information on the callback type.) The callback will be called with two arguments: the value of the label to be formatted, and the pass-through argument (see next).

$callback_arg

A pass-through argument for the callback function. If omitted, NULL is used.

Notes

The default formatting if this function is not called is to show the percentage of each segment, formatted with one decimal point and a percent sign suffix. This is the same as:

$plot->SetPieLabelType('percent', 'data', 1, '', '%');

The default formatting can be restored by passing an empty string or NULL as the $source argument. (Note: The default precision can be changed; see History below.)

The formatting arguments starting with $type work exactly the same way as when formatting X tick labels (for example) using SetXLabelType. See there for formatting examples. Date/time formatted labels would also work here, but are not documented for pie chart labels because they are unlikely to be useful.

If $source is index, the label source is an integer starting with 0 for the first pie segment, 1 for the second pie segment, etc. (By default, segments are drawn counter-clockwise from 0 degrees, but this can be changed.) This can be useful with custom type formatting, by providing a formatting function to get the label text from an external array (for example).

If $source is label, the label source is taken from the data array as set with SetDataValues. This can only be used with data type text-data-single, because that is the only data type where each data array row (and its label, in the first array position) corresponds to a single pie segment.

If $source is percent, the label source is the percentage of the pie represented by the segment being labeled. This normally needs to used with $type = data, printf, or custom formatting, in order to get a fixed number of decimal places and a percent sign suffix. Note that the following is probably not useful:

$plot->SetPieLabelType('percent'); // Do not use

The resulting labels would display segment percentages, but as unformatted floating point numbers with no suffix. For example, instead of "48.5%", the label might display: "48.4865312". This is usually not the desired result.

If $source is value, the label source is the numeric value of the pie segment. Depending on the data type used, this is a value or sum of values from the data array.

If $source is an array, the result is a string containing multiple space-separated fields. This is most likely to be useful with custom formatting. A custom label formatting function can split up the fields using explode(' ', $str). Note: If one of the fields is a label which might contain spaces, always place that field last when specifying the $source array, and use the 3rd parameter to explode() to limit the number of fields returned. This will ensure that the complete label is extracted as a single field. See the last example below.

To adjust the position of the pie chart labels, see SetLabelScalePosition. To turn the labels off completely, use SetLabelScalePosition(False).

SetPieLabelType also supports the use of two or three format strings with 'printf' formatting type, as described in SetXLabelType and Section 3.6.5.3, “Formatting Labels: 'printf' type”. (The additional format strings are used for negative numbers, or zero.) But this feature is almost never useful with pie charts, where all pie slices have size greater than zero.

Examples

In addition to the examples in this section, see Section 5.41, “Example - Pie Chart Label Types”.

Assume plot type pie, data type text-data-single, and the follow data array:

$data = array(
    array('Gold',        20),
    array('Silver',      13),
    array('Copper',       7),
    array('Tin',         18),
    array('Bronze',      10),
    array('Iron',         4),
    array('Platinum',     2),
    array('Nickel',       5),
);

For the default behavior of percentage labels with numeric formatting, do not call SetPieLabelType. Result: 25.3%, 16.5%, 8.9% etc.
...
Show segment indexes (ordinal segment number from 0). Result: 0, 1, 2 etc.
$plot->SetPieLabelType('index');
Show label strings from the data array. Result: Gold, Silver, Copper etc.
$plot->SetPieLabelType('label');
Show label strings from the data array, with quote marks added. Result: "Gold", "Silver", "Copper" etc.
$plot->SetPieLabelType('label', 'printf', '"%s"');
Show the numeric value of each segment, unformatted. Result: 20, 13, 7 etc.
$plot->SetPieLabelType('value');
Show the numeric value of each segment, formatted with 3 decimal places. Result: 20.000, 13.000, 7.000 etc.
$plot->SetPieLabelType('value', 'data', 3);
Use a custom formatting function to convert the data array labels to upper case. Result: GOLD, SILVER, COPPER etc.
function mylabels($str)
{
    return strtoupper($str);
}
$plot->SetPieLabelType('label', 'custom', 'mylabels');
Combine multiple label sources: data array label and percentage. Result: Gold (25.3%), Silver (16.5%), Copper (8.9%) etc.
function mylabels($str)
{
    list($percent, $label) = explode(' ', $str, 2);
    return sprintf("%s (%.1f%%)", $label, $percent);
}
$plot->SetPieLabelType(array('percent', 'label'), 'custom', 'mylabels');

History

This function was added in PHPlot-5.6.0. In earlier releases, only 'percent' label type was available, and the labels were always formatted as fixed-point values (format type 'data').

Versions before PHPlot-5.6.0 used a numeric precision set with SetPrecisionY or SetYLabelType for pie chart percentage labels, with a default of 1 decimal place. (This was not documented.) PHPlot-5.6.0 still does that, but only if SetPieLabelType was never called (or reset to all defaults). That is, if SetPieLabelType was not called to set up a label source and formatting type, the Y label precision will be used if set, else 1 digit.

SourceForge.net Logo

This version of the manual was produced for the PHPlot Sourceforge project web service site, which requires the logo on each page.

To download a logo-free copy of the manual, see the PHPlot project downloads area.