Before explaining how to customize data color selection, here is a review of how data color selection works by default.

Think of your data array as having rows and columns. The rows represent values of the independent variable (usually X), and the columns contain one or more values of the dependent variable (usually Y) for that value of the independent variable. For this discussion, ignore any additional entries in the data array, such as labels and X values. The set of values from a column in your data array is also referred to as a data set.

The standard behavior of PHPlot is to select a data color from the data colors array using the column index for the data point. The selected color will be used to draw a point marker, line segment, bar, etc. This was explained in Section 3.5.3, “Plotting Colors”.

For example, if you have a data array with 12 rows and 3 columns for a bar chart, you are drawing 12 groups of 3 bars. Within each bar group, the first bar will be drawn with the first color in the data colors array (the color with index 0), the second bar will use the second color from the data colors array, and the third bar will use the third color. You can see this in Example 5.4, “Bar Chart”, where the first three colors in the data colors array are SkyBlue, green, and orange.

There are two other color arrays: the error bar colors and data border colors. Error bar colors are used in error plots to indicate the positive and negative error range, and data border colors are used to draw borders around areas representing the data for some plot types (such as bars). The same index (but not necessarily the same color) is used to select the color for any of the three elements which are used in a plot. For example, the first data set in a points plot with error bars will use data color index 0 for the point markers, and error bar color index 0 for the error bars. The second bar in each group in an unshaded bar chart will use the second data color to fill the bar and the second data border color to outline it.

You can set the colors in the three color arrays with SetDataColors, SetErrorBarColors, and SetDataBorderColors. PHPlot will pad all these arrays to the number of columns in your data array, by duplicating the earlier values. (For example, if you have 5 data sets and define 3 colors red, green, and blue, PHPlot will pad this to be a 5 color array red, green, blue, red, green.) It will not truncate the arrays. This means you can define more data colors than there are data columns. These additional colors will not be used with the standard color selection method, but can be used with custom data color selection.

If you need more control over data colors, you can use the PHPlot callback called data_color. (See Section 4.4, “Callbacks” for general information about callbacks.) Some of the things you can do with custom data color selection are:

To customize the use of data colors, you will define a function that accepts as arguments the data array row and column index numbers (0-based integers), and returns the color array index. Register this function with PHPlot as a callback, and your function will be called whenever PHPlot needs to select a data color.

Note that your callback will return an array index, not a color value. For example, if it returns 0, the first color in the data colors array will be used, and the first color in the error bar colors array (if error bars are being drawn), and the first color in the data border colors array (if data borders are being drawn). You will most likely need to set up the data colors array (and possibly the error bar colors array and data border colors array too) in order to get the results you want.

A function to act as a data color callback might look like this:

function pickcolor($img, $passthrough, $row, $col, $extra = 0)
{
  $color_index = ...;

  return $color_index;
}

The first two arguments are common to all callbacks: the PHPlot image resource, and your passthrough argument (if any - see below). (You generally will not need to access the image resource from the data colors callback, but it is provided to all callbacks.) The second and third arguments specify which data value is being plotted. The $row corresponds to the independent variable (usually X), and $col corresponds to the data set - plot line, bar within a bar group, etc. Both $row and $col are zero based integers indexes.

Your callback is expected to return a color array index for this data point. This will be an integer greater than or equal to zero, where zero indicates the first color in the colors array should be used. Your returned index should be within the bounds of the color array being referenced, however PHPlot will use the value you return modulo the size of the array. For example, the default PHPlot data colors array has 16 colors. If your callback returns the value 20, the 5th color in the array will be used (because 20 % 16 = 4, and index 4 is the 5th value in the array).

The $extra argument to your callback is for extra information you may need to determine the color to use. Currently, this is only used for 'linepoints' plots and 'linepoints' error plots. These plots are drawn in two stages: points and lines. In case you want different colors for the points and lines, use the $extra argument. It will have the value 1 when PHPlot is requesting the color of the point marker (shape), and the value will be 0 when requesting the color of the line segment. Note that the error bars of a linepoints error plot are drawn with the color index returned for the points (but using the error bars colors, not the data colors).

You do not need to specify the $extra argument in your callback function declaration if you do not need it. But if you do specify it, you must make it an optional argument with the value zero, because PHPlot does not always supply the value.

The above function would be established as a data color callback for a PHPlot object $plot like this:

$plot->SetCallback('data_color', 'pickcolor', $passthru_arg);

The first argument is the callback name, or 'reason': data_color. The second argument is the name of your callback function. An object and method can be used here instead - see Section 4.4.4, “Object Methods as Callbacks”. The third argument is an optional pass-through value that will be sent to your callback function each time it is called.

You can also use a PHP anonymous function as a data color callback (or as any callback). This is recommended only when the color selection code is relatively short. Here is an example of using an anonymous function as a data color callback. This uses color 1 (green) or 4 (red) based on the value of a bar chart value (text-data data type). Note the use clause is used by the anonymous function to access the data array $data.

$plot->SetCallback('data_color',
   function($img, $passthru, $row, $col) use($data) {
       if ($data[$row][$col + 1] >= 50) return 1;
       return 4;
   }
);

If your plot includes a legend, the legend uses the colors in the order defined in the data colors array, without regard to any custom data color selection callback. When using a legend with a custom data color selection callback, you need to define your data colors array (with SetDataColors, if used) and set your legend lines (with SetLegend) knowing that each legend line will reference the corresponding color in the data array in order. The Custom Bar Colors example referenced below demonstrates this.

For examples of using a data color callback, see Section 5.25, “Example - Creative Use of the Data Color Callback” and Section 5.26, “Example - Custom Bar Colors Using the Data Color Callback”.