3.6. Labels
Prev | Chapter 3. PHPlot Concepts | Next

## 3.6. Labels

This section contains information about creating labels which identify data values on the plot. For a list of functions used to control labels, see Section 6.11, “Labels”.

Several types of labels are available in PHPlot:

- Tick labels identify the values at the tick positions. There are X tick labels and Y tick labels.

- Axis data labels display the label values from your data array. X axis data labels are available for vertical plots, and Y axis data labels are available for horizontal plots.

- Data value labels display the actual value of a data point. These are available only for some plot types. Y data value labels are available for vertical plots, and X data value labels are available for horizontal plots.

- Pie chart data labels identify the pie segments. By default, they show the percentage of each pie segment.

### Note

The term data label is often used to refer to both axis data labels and data value labels. The same PHPlot functions are used to configure axis data labels and data value labels.

Here is a sample plot with the Y tick labels and X axis data labels called out.

Here is a sample plot with the pie chart labels called out.

Here is a sample vertical bar plot with the Y tick labels, Y data value labels, and X axis data labels called out.

Here is a sample horizontal bar plot with the Y (axis) data labels, X data value labels, and X tick labels called out.

### 3.6.1. Tick Labels

Tick labels identify the X or Y values at tick positions (even if the tick marks themselves are not drawn). See Section 3.7.4, “Tick Marks” for information about the tick positions.

Note that even with data type 'data-data', where explicit independent variable values for the data are supplied, the tick positions and labels along that axis are still calculated automatically (unless modified by the available functions). For example, for vertical plots, your supplied X values in the data array are not used for the X tick labels.

You can enable, disable, or position the tick labels with SetXTickLabelPos and SetYTickLabelPos.

### 3.6.2. Axis Data Labels

Axis data labels are available for the independent variable axis. This is X for vertical plots, and Y for horizontal plots. These data labels are supplied in your data array for each data point. For example, with data type text-data :

    $data = array( array('Peaches',100),
                   array('Apples', 140),
                   array('Pears', 90));

The three points have data labels 'Peaches', 'Apples', and 'Pears'. For vertical plots, these data labels will be drawn at the bottom of the plot (by default) below the corresponding X values. For horizontal plots, these data labels will be drawn to the left of the plot (by default), to the left of the corresponding Y values. You can disable or reposition the data labels with SetXDataLabelPos and SetYDataLabelPos.

### Note

The axis data labels are not necessarily drawn along axis lines. They are usually drawn along the bottom (for X) or left side (for Y) of the plot. Although these are also the usual positions for the X axis and Y axis, the actual axis lines may be drawn elsewhere. See SetXAxisPosition or SetYAxisPosition for more information on axis positions.

You will generally not want both tick labels and axis data labels on, because they will overlap and be unreadable. If you are not using data labels, you should either make them all empty strings in your data array, or else use SetXDataLabelPos('none') (for vertical plots) or SetYDataLabelPos('none') (for horizontal plots) to turn them off. You can also call SetXTickLabelPos (for vertical plots) or SetYTickLabelPos (for horizontal plots) to explicitly position the tick labels. PHPlot will then disable the data labels.

If you don't tell PHPlot what to do with data and tick labels, the behavior depends on the PHPlot version. PHPlot 5.1.0 and later will examine your data array to see if there are any non-empty data labels, and if so it will draw only data labels, and omit tick labels. If all of the labels in your data array are empty, tick labels will be drawn. (PHPlot through 5.0.7 will draw both tick and data labels in these cases.)

### 3.6.3. Data Value Labels

Data value labels are available only for some plot types. These are displayed inside the plot, and show the value at each data point, bar, or bar segment.

For vertical bar charts, Y data value labels indicate the Y value for each bar, and are drawn above the bar for positive values, or below the bar for negative values. For vertical stackedbar charts, Y data value labels indicate the total Y value for each stack, and optionally indicate the value of each segment. Use SetYDataLabelPos to enable Y data value labels.

For horizontal bar charts, X data value labels indicate the X value for each bar, and are drawn to the left or right of the end of the bar. For horizontal stackedbar charts, X data value labels indicate the total X value for each stack, and optionally indicate the value of each segment. Use SetXDataLabelPos to enable X data value labels.

Y data value labels are also available for vertical plots of types lines, linepoints, points, and squared (starting in PHPlot-5.3.0). X data value labels are available for horizontal plots of types lines, linepoints, and points (starting in PHPlot-6.0.0). The data value labels indicate the value of each point and are displayed (by default) above each point. Use SetYDataLabelPos to enable Y data value labels for these vertical plots, and SetXDataLabelPos to enable X data value labels for these horizontal plots. PHPlot does not attempt to prevent interference between the labels and other plot elements. To change the position of the labels, see Section 4.7.7, “Tuning Labels”.

Data value labels are not available with other plot types.

### Note

The same function is used to position X axis data labels and X data value labels, and the same function is used to position Y axis data labels and Y data value labels. There is no ambiguity, because one type of label is available for each axis for vertical plots, and the other type for horizontal plots.

Example 5.19, “Bar Chart with Data Value Labels” shows a vertical bar chart with Y data value labels. Example 5.20, “Stacked Bars with Y Data Value Labels” shows a vertical stacked bar chart with Y data value labels. Example 5.33, “Linepoints Plot with Data Value Labels” shows a linepoints plot with Y data value labels.

Example 5.27, “Horizontal Bar Chart” shows a horizontal bar chart with X data value labels. Example 5.28, “Horizontal Stacked Bar Chart” shows a horizontal stacked bar chart with X data value labels. Example 5.48, “Horizontal Linepoints Plot with Data Value Labels and Data Lines” shows a horizontal linepoints plot with X data value labels.

### 3.6.4. Pie Chart Labels

Pie chart labels identify segments on a pie chart. By default, these show the percentage of each segment, relative to the whole pie. Starting with PHPlot-5.6.0, pie chart labels can display other information, and can be flexibly formatted.

Use SetPieLabelType to select the source for pie labels as well as how to format them. Example 5.41, “Pie Chart Label Types” shows a pie chart with different labeling options.

### 3.6.5. Formatting Labels

Tick labels, data labels, and pie chart labels are subject to format controls. There are several choices in formatting. By default, the label value itself is simply displayed. Use SetXLabelType and SetYLabelType to select one of the other format types for tick labels. Use SetXDataLabelType and SetYDataLabelType to select one of the other format types for data labels (both axis data labels and data value labels). (Note that SetXLabelType also sets the default format for X data labels, for use if SetXDataLabelType is not called. Also SetYLabelType sets the default for Y data labels, for use if SetYDataLabelType is not called.) Use SetPieLabelType to select a format type for pie chart labels.

The following sections contain details of the available formatting types. More examples can be found in the reference page for SetXLabelType.

#### 3.6.5.1. Formatting Labels: 'data' type

Label format type 'data' expects the tick label, data label, or pie label values to be numbers, and formats the values as floating point numbers with a separator between every group of thousands and a fixed number of decimal places. You can set the number of digits of precision, with the default being 1 digit. You can also set a prefix and/or suffix string (such as a currency symbol or percent sign). PHPlot will try to set the thousands grouping separator and decimal separator according to your locale, but this can be overridden if necessary.

For example:

    $plot->SetYLabelType('data', 2, '$');

This might format the value 1234.567 as "$1,234.57" (depending on locale).

#### 3.6.5.2. Formatting Labels: 'time' type

Label format type 'time' expects the tick or data label values to be a PHP time value (number of seconds since a fixed base data, the Unix Epoch). PHPlot will format the labels according to the format string you provide. Refer to the PHP documentation for `strftime()` for details on the format string.

For example:

    $plot->SetXLabelType('time', $format);

If a label value is the numeric equivalent of "31 December 2004 at 1:23:45 pm" (which is 1104517425 on some platforms), the following table shows some examples of the result with different values of $format:

$format: | Result:
--- | ---
%Y-%m-%d | 2004-12-31
%b %Y | Dec 2004
%b %d, %Y | Dec 31, 2004
%d %b | 31 Dec
%H:%M:%S | 13:23:45

(This formatting type is generally not applicable to pie chart labels.)

### Note

If you select 'time' formatting, but don't set a time format string, PHPlot-5.0rc3 and higher will format the values as hours, minutes, and seconds as shown in the last row of the table above. (The default format was undefined before version 5.0rc3.)

Also note that there are limits to the range of this type of formatting that can make it unusable for historical data. On some platforms, dates before 1970-01-01 can not be formatted.

Starting with PHPlot-5.0.4, empty string values for data labels are ignored for 'time' and 'data' formatting. Earlier versions would format the labels as 0 (for 'data') or cause an error (for 'time').

While date/time formatting can be useful, for X values it may be easier to just format the label values in your PHP code and put the result into the label positions in the data array. If you need date/time formatting for Y values (and it is hard to imagine where that would be useful), you have no option but to use the 'time' format labels for tick values.

#### 3.6.5.3. Formatting Labels: 'printf' type

Label format type 'printf' expects a second argument specifying a `printf` format string, and formats the label value according to the string. The format string must contain exactly one conversion specification (%-code) which consumes a single argument. For example:

    $plot->SetYLabelType('printf', '%8.2e parsecs');

This might produce a label like " 1.23e+8 parsecs".

#### 3.6.5.4. Formatting Labels: 'custom' type

A user-defined function can be provided to format labels. Specify formatting type 'custom', and provide the name of your function as a string. (This is actually a PHP callback type argument, which can also be an array containing an object and a method name. See the PHP documentation on callbacks for more details.) You can provide an additional argument which will be passed to your function when formatting labels (a pass-through argument).

In this example, the user-provided function is called `my_formatter`, and you want an additional argument $data passed to the function.

    $plot->SetYLabelType('custom', 'my_formatter', $data);

Your formatting function will accept 1 or 2 arguments (or more - see below).

    function my_formatter($label, $arg)
    {
        ...
        return $some_result;
    }

The function will be called with $label set to the value of the label to be formatted, and is expected to return the formatted label text. $arg is a pass-through argument that has whatever value you used with `SetXLabelType` (etc.). In the above example, this is $data. You need to declare this second argument in your function only if you are using a pass-through argument.

### Note

PHPlot may call your label formatting function multiple times for the same label, and your function must return the same value each time. Also, do not rely on the labels being formatted in any particular order.

A custom label formatting function will not be called at all if the label value is an empty string (`''`). This generally only applies to axis data labels (the label strings in your data array), since others are numbers. This means you cannot use custom label formatting to replace an empty string with something else. The custom label formatting function will be called if the label string is anything other than an empty string, such as a string with single space.

Custom label formatting is extremely flexible. You can convert values into another format (for example, degrees, minutes, seconds), or look up values in an external array (see Section 5.40, “Example - Bubbles Plot”), for example. However, using this method, you can only selectively format or display labels based on their value. For even more control, use the additional arguments provided to the formatting function which are described in the next section.

#### 3.6.5.5. Formatting Labels: Extended 'custom' type

When you use 'custom' formatting type, PHPlot actually provides 0, 1, or 2 additional arguments to your callback. These identify the row, or row and column, of the data point being labeled. You can use these extra arguments in your callback for selective formatting or filtering based on the position of the point being plotted in your data array.

PHPlot provides the following additional arguments to a custom label formatting callback (after the label value and pass-through arguments):

Label: | Arguments Provided:
--- | ---
Tick Labels | (None)
Axis Data Labels | $row
Data Value Labels (other than stackedbars total labels) | $row, $column
stackedbars data value labels for bar totals | $row

You need not declare these arguments unless you are using them, but if you do declare them, it is safer to make them optional with default NULL. (If you are only using the custom callback function for one specific type of label, you can omit the defaults.) For example:

    function my_formatter($label, $arg, $row=NULL, $column=NULL)
    {
        ...
        return $some_result;
    }

The row argument value is an index starting with zero that numbers the rows in your data array. This corresponds to the ordinal position of the independent variable (X for vertical plots, Y for horizontal plots). This is also the outer index of your data array.

The column argument value is an index starting with zero that numbers the data sets in each row. This corresponds to the ordinal position of the dependent variable (Y for vertical plots, X for horizontal plots). Note that this is not simply the inner index of your data array, because the data array rows also have labels, and (depending on the data type) may contain other values. For example, given the data type `data-data` and this data array:

    $data = array(
        array('Jan', 1,  10, 11, 12),
        array('Feb', 2,  20, 21, 22),
        array('Mar', 3,  30, 31, 32),
    );

When formatting a data value label for X=2, Y=22 (the 3rd data set in the row labeled 'Feb'), PHPlot will call a custom label formatting function like this:

    my_formatter(22, $passthrough, 1, 2);

That is, row=1 and column=2.

As described in Section 3.6.5.4, “Formatting Labels: 'custom' type”, your callback function returns the value of the formatted label. You can return an empty string to display no label. This can be used to display data value labels for only one data set, for example - just return an empty string if $column is not equal to the index of the data set you want to label.

See Section 5.43, “Example - Custom Data Value Label Formatting” for an example.

### Note

These additional row and column arguments are only available starting with PHPlot-5.8.0.

Prev | Up | Next
3.5. Colors | Home | 3.7. Other Plot Elements