## PHPlot User Functions

- Important functions
- Appearance functions
- Color functions
- Data manipulation functions

### Important functions

SetDataType($which_dt)
  User Function: PHPLOT can accept data in a number of different formats. One main difference between PHPLOT and PGPLOT is that the x-y or x-y-error data should be passed in with the data grouped together in an array.

  Asside: Why the author chose this data format: In PGPLOT you would have the X-values in one array and the Y-values in a second. This would sometimes lead to really strange graphs if one array was accidentally one data element short. Plus most of the data the author was using came in from a database using a _get_row or _get_array (in php) and one can just pass it straight in to PHPLOT.

  Colors and border colors are set by SetDataColors. Why not have colors as part of the same array? Because most data applications are used to putting out raw data and not raw data + color information.

  So in PHPLOT the datalabel,x-value,y-value and error are grouped together as a value array. Then the entire set of points to be plotted is passed in as a data array E.g. Data_array = array(value_array_1,value_array_2,....)

  See below for examples of the various data types:

  - text-data: Data is displayed at equal spacing along the x-axis. Data is passed in as a data array of value arrays. Each element of the data array is a position on the x-axis. The first element of the value array is the label for that x-axis position, every subsequent element of the value array is a y-value. Example data

        $data = array(
        	array("label 1",1.1,2,3,4),
        	array("label 2",2,3,4,5),
        	array("label 3",5,6,7,8),
        	array("label 4",10,12,13,14)
        );

    Which will display data points at (1,1.1), (1,2), (1,3), (1,4), (2,2), (2,3)....
  - data-data: X-Y data is passed in like text-data except that the second element of the value array is the position along the x axis of the data point(s). One data element would be $data[] = (title,x,y1,y2,y3,y4,...) or

        $data = array(
        	array("label 1",1.1,2,3,4),
        	array("label 2",2,3,4,5),
        	array("label 3",5,6,7,8),
        	array("label 4",10,12,13,14)
        );

    Notice that this is the same as in the previous example except that the x,y data points are at (1.1,2), (1.1,3), (1.1,4), (2,3)...
  - data-data-error: Again X-Y data is passed in as an array with each value array being (data_label,x_position,y_position,error_plus,error_minus)

SetDataValues($which_dv)
  User Function: Passes the raw data values into the class variable $this->data_values. This function needs to be called before any image can be drawn.

SetPlotType($which_pt)
  User Function: Can be: bars, lines, linepoints, area, points, and pie

SetErrorBarLineWidth($width)
  Width of the Error Bars in Pixels. If not set then uses "line_width" to set the width of the error_bar lines.

SetFileFormat($which_file_format)
  User Function: Set the format of the output graph. Supported formats are GIF, JPEG, and PNG. You can only use those formats that are supported by your version of GD. For example, if you use GD-1.8.3 you can not use GIF images. If you use GD-1.2 you can not use PNG or JPEG images.

SetUseTTF($which_ttf)
  User Function: Call this as SetUseTTF(1) when you have TTF compiled into PHP otherwise call this as SetUseTTF(0)

  ### Appearance functions

SetErrorBarShape($which_ebs)
  User Function: Can be "tee" or "line." If it is tee, then the half-width of the tee is set by SetErrorBarSize

SetErrorBarSize($which_ebs)
  User Function: Size in pixels of the Tee shape of the error bar.

SetHorizTickIncrement($which_ti)
  User Function: Set where to place the X-tick marks.

SetNumHorizTicks($which_nt)
  User Function: Use this or SetHorizTickIncrements but not both.

SetNumVertTicks($which_nt)
  User Function: Use this or SetVertTickIncrements but not both.

SetPlotAreaPixels($x1,$y1,$x2,$y2)
  User Function: You can use this to set the actual size in pixels of the plot area on the image.

SetPointShape($which_pt)
  User Function: Can be: rect,circle,diamond,triangle,dot,line,halfline

SetPointSize($which_ps)
  User Function: Set the width of the displayed data point for plot_type's that have data points. E.g. dots, linepoints This is an integer. For diamonds, values that are even make the diamond look better.

SetPrecisionX($which_prec)
  User Function: Set the precision of the data written to the X axis. $which_prec is an integer which represents the number of digits displayed to the right of the decimal. This uses the number_format command in PHP.

SetPrecisionY($which_prec)
  User Function: Set the precision of the data written to the Y axis. $which_prec is an integer which represents the number of digits displayed to the right of the decimal. This uses the number_format command in PHP.

SetShading($which_s)
  User Function: Set the length of the shadows for shading bar charts The color used is the LightGridColor See SetLightGridColor.

SetTickLength($which_tl)
  User Function: Set the length of the tick in pixels for the x axis and y axis. $which_color can be either a name like "black" or an rgb color array array(int,int,int).

SetTitle($title)
  User Function: Set the title of the graph. Printed at the top middle of the graph.

SetHorizTickIncrement($which_ti)
  User Function: Set the distance between tick marks on the X axis. $which_ti is in world coordinates.

SetVertTickIncrement($which_ti)
  User Function: Set the distance between tick marks on the Y axis. $which_ti is in world coordinates.

SetXDatalabelMaxlength($which_xdlm)
  User Function: Sets the maximum length of the datalabels on the x-axis. This adjusts the margins if the angle of the labels is not 0.

SetXGridLabelType($which_xtf)
  User Function: Can be "time", "title", "none", "default" or "data".
  time - label is set by the the php command strftime()
  title - label is treated as text, the first element of the data array.
  data - label is formateed using php command number_format
  none - no labelss are printed.
  default - prints as it is entered.

SetXScaleType($which_xct)
  Can be "log" or "linear".

SetXTimeFormat($which_xtf)
  User Function: Used for x_grid_label_type="time". For the format see the php manual for strftime(). It assumes the x-data values are unix timestamps, and displays them according to the passed format string.

  Example: If x values are seconds offset from the beginning of the day. This coresponds to unix timestamps on January 1, 1970, so all I had to do was $graph->SetXGridLabelType("%H:%M") to display the time properly.

  The php strtotime() function also comes in handy turning dates into timestamps, especially for parameters to SetPlotAreaWorld().

  Example:
  $graph->SetPlotAreaWorld(strtotime("October 1"), 0,strtotime("December 15"),10);
  $graph->SetXGridLabelType("time") ;
  $graph->SetXTimeFormat("%b %d") ;

SetXLabel($xlbl)
  User Function: Set the label for the X axis.

SetYLabel($ylbl)
  User Function: Set the label for the Y axis.

SetYScaleType($which_xct)
  Can be "log" or "linear".

  ### Color functions

SetBackgroundColor($which_color)
  User Function: Set the color of the background of the entire image. $which_color can be either a name like "black" or an rgb color array array(int,int,int).
  It defaults to array(222,222,222) if not defined.

SetGridColor ($which_color)
  User Function: Set the color of the grid. Defaults to "black" $which_color can be either a name like "black" or an rgb color array array(int,int,int).

SetLegend($which_legend)
  $which_legend is an array of text for display in a small box on the image. If you do not set the position with SetLegendPixels() then it puts it in the upper right hand side.

SetLegendPixels($which_x,$which_y,$which_type)
  Pick the upper left corner of the legend box with $which_x and $which_y in pixels. $which_type is reserved for future use.

SetLegendWorld($which_x,$which_y,$which_type)
  Untested and documentation not written. Have Fun!

SetLightGridColor ($which_color)
  User Function: There are two grid colors, this sets the light grid color. $which_color can be either a name like "black" or an rgb color array array(int,int,int).
  It defaults to array(222,222,222) if not defined.

SetLineWidth($which_lt)
  User Function: Set the width of lines in pixels for graphs that use lines (linepoints and lines). Affects the size of the error bar lines as well.

SetLineStyles($which_sls)
  User Function: Set style of the line to be printed. This is an array. Currently only 'dashed' and 'solid' are supported.

SetPlotBgColor($which_color)
  User Function: Set the Background color of the area on which the plot is defined. Called from PlotAreaBackground
  $which_color can be either a name like "black" or an rgb color array array(int,int,int).
  It defaults to array(222,222,222) if not defined.

SetTextColor ($which_color)
  User Function: Set the color of text written. It defaults to black if not called. You can call this function multiple times - each time it changes the color of text written. $which_color can be either a name like "black" or an rgb color array array(int,int,int).

SetTickColor ($which_color)
  User Function: Set the color of the ticks on the axes $which_color can be either a name like "black" or an rgb color array array(int,int,int).

SetTitleColor($which_color)
  User Function: Set the color of the title. $which_color can be either a name like "black" or an rgb color array array(int,int,int).

  ### Data manipulation functions

  These functions only are availabe in the class PHPlot_data that extends PHPlot. Since all functions of that section do calculations on the data, it is neccessary that data is supplied to the class by the SetDataValues() function before calling any of the functions.

DoScaleData($even, $show_in_legend)
  User Function: Scales the data so that graphs with widely different amplitudes can be plotted into one image. If $show_in_legend is true, the amplification factor that is applied to each for the datasets is appended to the legend of the graph. If $even is true, the function multiplies only by 10^x,2*10^x or 5*10^x.

DoMovingAverage($datarow, $interval, $show_in_legend)
  User Function: Computes a moving average over an amount of $interval units on the data row that is indexed by $datarow. If $show_in_legend is true, a notice that a data row is averaged and the length of the interval are appended to the legend.

  ### not implemented

SetCharacterHeight()
  User Function: Not yet implemented