3.7. Labels

This section contains information about creating labels which identify data values on the plot.

There are two types of labels for X values: data labels and tick labels. There are also tick labels for Y values, and data labels for Y values which only work with bar charts and stacked bar charts. None of this applies to pie charts, which have no tick labels and internally-generated data value labels.

3.7.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 X values for the data are supplied, the X tick labels are still calculated automatically (unless modified by the functions named above). That is, your supplied X values in the data array are not used for tick labels.

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

3.7.2. Data Labels

Data labels apply to X values for all plot types. X 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'. These data labels will be drawn at the bottom of the plot (by default) below the corresponding X values. You can disable or reposition the X data labels with SetXDataLabelPos.

You will generally not want both X tick labels and X 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') to turn them off. You can also call SetXTickLabelPos to explicitly position the tick labels; PHPlot will then disable the data labels.

If you don't tell PHPlot what to do with X data and X 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 data labels are empty, tick labels will be drawn. (PHPlot through 5.0.7 will draw both tick and data labels in these cases.)

There is one type of Y data label for bar charts, which indicates the Y value above each bar. There are two types of Y data labels for stacked bar charts. Bar total labels indicate the total Y value for a bar stack, and are drawn above the bar. Bar segment labels indicate the incremental value of each segment within the bar, and are drawn inside the segment below the top. Use SetYDataLabelPos to enable Y data labels. Section 5.19, “Example - Bar Chart with Data Labels” shows a bar chart with Y data labels. Section 5.20, “Example - Stacked Bars with Y Data Labels” shows a stacked bar chart with Y data labels. (Note that Y data labels for stacked bars was first implemented in PHPlot-5.1.1.)

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