3.8. 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 4.11, “Labels”.

Several types of labels are available in PHPlot:

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.

Tick labels and Data labels on a plot

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

Pie chart data labels

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

Tick labels, Data labels, and Data Value labels on a plot

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

Tick labels, Data labels, and Data Value labels on a plot

3.8.1. Tick Labels

Tick labels are calculated from the X or Y values of the data. By default, PHPlot will figure out what to use for X and Y tick labels, but the results may not be what you want. You can change the calculated tick labels by using several PHPlot functions. You can use SetXTickIncrement and SetYTickIncrement to set the spacing between tick marks (in World Coordinates), or you can use SetNumXTicks and SetNumYTicks to set the number of tick marks. These don't affect the value of the first tick mark, only the interval. To set the value for the first tick mark, you define the World Coordinate mapping with SetPlotAreaWorld. For example:

$plot->SetPlotAreaWorld(-10, NULL, 10, NULL);
$plot->SetXTickIncrement(1);

This results in the X tick labels going from -10 to 10, with a tick mark every 1 data unit.

Note that even with data type 'data-data', where explicit independent variable values for the data are supplied, the tick labels along that axis are still calculated automatically (unless modified by the functions named above). 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.8.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.8.3. Data Value Labels

Data value labels are available only for bar and stackedbar charts. These are displayed inside the plot, and show the value at the end of each 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.

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.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.

3.8.4. Formatting Labels

Both tick and data 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.)

Label format type 'data' expects the tick or data 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. PHPlot will try to set the thousands grouping separator and decimal separator according to your locale, but this can be overridden if necessary.

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, but here are some examples for 31 December 2004 at 1:23:45 pm:

Format String:Result:
%Y-%m-%d2004-12-31
%b %YDec 2004
%b %d, %YDec 31, 2004
%d %b31 Dec
%H:%M:%S13:23:45

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.

Two additional label format types are available. Label format type 'printf' uses a custom print format string. To use label format type 'custom', you supply a function of your own to format the labels. See SetXLabelType for more details about these format types.