Chapter 14. Common features for all Cartesian (x,y) graph types
Prev | Part III. Common features | Next

## Chapter 14. Common features for all Cartesian (x,y) graph types

## 14.1. The definition of linear graphs

With cartesian graphs we refer to all plots which have orthogonal x and y axis. The library support the option of multiple y-scales (when applicable) but only on x-axis can be used.

The following principle linear graph types are supported as of v2.5 (note that some graph types may have additional subtypes that are not shown in this overview.)

Figure 14.1. Supported principle linear graph types in the library

a) Line plot (See Section 15.1.1) | b) Area plot (See Section 15.1.10) | c) Bar plot (See Section 15.2)
a) Field plot (See Section 15.5.3) | b) Error plot (See Section 15.3) | c) Stock plot (See Section 15.4)
a) Geo-map plot (See Section 15.5.5) | b) Impuls (stem) plot (See Section 15.5) | c) Spline plot (See Section 15.1.15)
a) Balloon plot (See Section 15.5.4) | b) Scatter plot (See Section 15.5) | c) Contour plot (See Section 15.6)

Each of these graph types have there own section where more details can be found by following the link under the corresponding graph icon.

### 14.1.1. Axis and coordinate systems

The x and y axis each in a graph has an associated scale, labels, titles, grid lines, colors and position. The axis properties are accessed as objects of the axis instance variables in the main graph class. The axis can be access vi the following instance variables.

- `Graph::xaxis`, The x-axis, (by default on the bottom)

- `Graph::yaxis`, The y-axis, (by default on the left side)

- `Graph::y2axis`, The second y-axis (by default on the right side)

In addition the library also supports the use of multiple y-axis and they are accessed via an instance array

- `Graph::ynaxis[]`

All axis in turn are instances of `class Axis` and hence share common properties. The only two property that can be publicly accessed on the axis are

- `Axis::scale`. The scale of the axis. An instance of either `LinearScale`, `LogScale` or `DateScale`. This rarely needs to be accessed directly.

- `Axis::title`. The axis title. On the x-axis this is horizontal by default and on the y-axis the title is vertical by default

On the other hand there are a large amount of methods that can be used on the axis to adjust various properties. Some examples of commonly used methods are given below. The full description of each method is given in the API reference.

- Adjusting the labels

  - `Axis::SetLabelFormatString($aFormStr,$aDateFormat=false)`. Specifies the labels format string assuming `printf()` format if `$aDate` is false and in `date()` format if `$aDate` is true.

  - `Axis::SetLabelFormatCallback($aCallbackFunc)`

  - `Axis::SetLabelAlign($aHorAlign, $aVertAlign='top',$aParagraphAlign='left')`

  - `Axis::HideLabels($aHide=true)`

  - `Axis::SetTicklabels($aLabels, $aLabelColors=null)`

  - `Axis::SetLabelMargin($aMargin)`

  - `Axis::SetLabelSide($aSide)`

  - `Axis::SetFont($aFamily,$aStyle=FS_NORMAL,$aSize=10)`

  - `Axis::SetLabelAngle($aAngle)`. Species the angle of the label. Note: It is only possible to use arbitrary angles if the font is a true type font. The built in bit map fonts only supports 0 and 90 degree text strings.

- Adjusting the tick marks

  - `Axis::SetTickSide($aSide)`

  - `Axis::SetTickPositions($aMajPos,$aMinPos=NULL,$aLabels=NULL)`

  - `Axis::HideTicks($aHide)`

- Adjusting the actual axis

  - `Axis::HideLine($aHide=true)`, ONly hide the axis but whos the labels

  - `Axis::Hide($aHide)`, Hide both axis and labels

  - `Axis::SetWeight($aWeight)`, Set the weight in pixels of the axis

  - `Axis::SetPos($aPositionOnOtherScale)` Specifies the position of the axis on the other scale. The position is given the scale of the other axis. There are two special values (strings) that can be given and those are

    - `'min'` - Will position the axis at the minimum value of the other scale

    - `'max'` - Will position the axis at the maximum value of the other scale

- Adjusting the title

  - `Axis::SetTitle($aTxt)`

  - `Axis::SetTitleMargin($aMargin)`

  - `Axis::SetTitleSide($aSide)`

  - `Axis::SetColor($aColor,$aLabelColor)`

The above methods are valid for all possible axis. So for example the following line sets the font for the labels on the x-axis

    1
    $graph->xaxis->SetFont(FF_ARIAL,FS_NORMAL,12);

and the follwing code set the font for the y-axis

    1
    $graph->yaxis->SetFont(FF_ARIAL,FS_NORMAL,12);

### 14.1.2. Adjusting the axis look and feel

The two major ways to adjust the look and feel of the axis are adjustments of the color and the weight (i.e. width) and this can be done with the appropriate methods as described above.

- `Axis::SetColor($aColor,$aLabelColor)`, For example `$graph->xaxis->SetColor('teal')`. Please note that by default the color for the labels will be that of the line if the label color is not explicitly specified.

- `Axis::SetWeight($aWeight)`. Specify the weight (in pixels of the axis)

### 14.1.3. Adding grid lines in the plot

### Note

The possibility of a having different styles, colors and weight for minor and major grid lines was added in 3.0.4 and is not available in earlier releases.

Grid lines will make it easier to see where the data points are in the graph. The grid lines are access by the properties "`xgrid`" and "`ygrid`"of the Graph class. By default only the y-axis grid are enabled by default. The following code example enables the major grids for both the x- and y-axis.

    1
    2
    $graph_>xgrid->Show();
    $graph->ygrid->Show();

The grid lines are instances of `Class Grid`. and supports the following methods

- `Grid::SetColor($aMajColor,$aMinColor=false)`. Specify the color for the major an minor grid lines

- `Grid::SetWeight($aMajorWeight,$aMinorWeight=1)`. Specify the weight of the line for the major and minor grid line

- `Grid::Show($aMajGid=true,$aMinGrid=false)`. Determine which grid lines should be shown

- `Grid::SetLineStyle($aMajorType,$aMinorType)` This method makes it possible to adjust the line style of the grid lines (both major and minor separately). The line style is specified as a string and can have one of the following values

  - `"solid"`

  - `"dotted"`

  - `"dashed"`

  - `"longdashed"`

- `Grid::SetFill($aFlg=true,$aColor1='lightgray',$aColor2='lightblue')`

The last method needs an explanation. The fill refers to the possibility to fill the space between the grid lines with alternating colors as specified in the method call. Figure 14.2 shows an example on how this can be used to make it easier to read a plot.

Figure 14.2. Using alternating fill colors in the grid `(`filledgridex1.php`)`

In the above example we have also used the possibility of using alpha-blending (for example on the shadow on the legend box).

The example below shows how to use different styles for the major and minor grid lines

Figure 14.3. Using different grid styles for major and minor grids `(`gridstylesex1.php`)`

### 14.1.4. Predefined scientific axis setups

In order to make it easier to setup a couple of typical axis configuration used in science plots there are four predefined configurations as shown in Figure 14.4.

Figure 14.4. Predefined scientific axis positions

`AXSTYLE_BOXOUT` | `AXSTYLE_BOXIN` | `AXSTYLE_YBOXIN` | `AXSTYLE_YBOXOUT`

The styles can easily be setup with a call to the method

- `Graph::SetAxisStyle($aStyle)`

An example of using this setup of the axis is shown in Figure 14.5

Figure 14.5. Example of `AXSTYLE_BOXIN` axis style `(`funcex2.php`)`

### 14.1.5. Other possible ways to position the axis

The axis can be manually positioned with a call to

`Axis::SetPos($aPos)`

The argument `$aPos` is normally the coordinate position on the "other" axis where the crossing of this and the other axis should be. There are also two special positions which are given as strings. They are `'min'` and `'max'`. Not surprisingly these special positions will always refer to the min and max scale value of the other axis.

The position given is the scale position on the "other"axis, i.e. for the x-axis the position specifies the crossing of the y-axis and vice versa.

Since it is possible to manually specify all aspects of the axis the table below shows some typical common setups and the principle calls needed to achieve the illustrated affect.

Table 14.1. Axis configurations

| This is the default setup and not extra configurations are needed and it is the same as
    1
    $graph->SetAxisStyle(AXSTYLE_SIMPLE);
| This setup is configured by moving the x-axis to the top
    1
    2
    3
    $graph->xaxis->SetPos('max');
    $graph->xaxis->SetLabelSide(SIDE_UP);
    $graph->xaxis->SetTickSide(SIDE_DOWN);
| This is the standard style but with an added box around the plot area.
    1
    2
    $graph->SetAxisStyle(AXSTYLE_SIMPLE);
    $graph->SetBox();
    1
    2
    3
    4
    $graph->xaxis->SetPos('max');
    $graph->xaxis->SetLabelSide(SIDE_UP);
    $graph->xaxis->SetTickSide(SIDE_DOWN);
    $graph->SetBox();
| This configuration locks the x- and y-axis at the origin
    1
    2
    $graph->xaxis->SetPos(0);
    $graph->yaxis->SetPos(0);
| With an added box around the plot area
    1
    2
    3
    $graph->xaxis->SetPos(0);
    $graph->yaxis->SetPos(0);
    $graph->SetBox();

Prev | Up | Next
13.7. Troubleshooting input data | Home | 14.2. Specifying and formatting the overall displayed graph