This repository has been archived on 2024-04-08. You can view files and clone it, but cannot push or open issues or pull requests.
phptsmadmin/includes/jpgraph/docs/chunkhtml/ch22s04.html

450 lines
40 KiB
HTML
Raw Normal View History

2011-05-28 09:51:52 +00:00
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Formatting the matrix plot</title><link rel="stylesheet" type="text/css" href="manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.0"><link rel="home" href="index.html" title="JpGraph Manual"><link rel="up" href="ch22.html" title="Chapter 22. Matrix graphs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Formatting the matrix plot</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center">Chapter 22. Matrix graphs</th><td width="20%" align="right"> </td></tr></table><hr></div><div class="sect1" title="Formatting the matrix plot"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id2591962"></a>Formatting the matrix plot</h2></div></div></div>
<div class="sect2" title="Color maps"><div class="titlepage"><div><div><h3 class="title"><a name="sec.matrix-color-maps"></a>Color maps</h3></div></div></div>
<p>The color map is a property of the matrix plot and all aspects of the color map is
accessed through the "<code class="code">MatrixPlot::colormap</code>" property which is an
instance of <code class="code">class MatrixColormap</code>.</p>
<p>To adjust how the color map is used the following methods are available</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">ColorMap::SetMap($aMap, $aInvert=false)</code></p>
<p>This is a polymorphic method that can take either a symbolic constant
as argument and in that case specifies one of the built in color maps or
it can be an array of colors which in that case specifies a manual color
map. There are several built in color maps of different types which are
referenced by an integer in range [0, 19]. A list of the built in color
maps can be found in <a class="xref" href="ch22s08.html" title="Built in color maps">Built in color maps</a></p>
<p>For example the specification</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$mp-&gt;colormap-&gt;SetMap(0);</span></pre></td></tr></table></div><p>
</p>
<p>will make the library use the heat color map which is standard color
map that goes from black for the min value up through red, orange,
yellow and finally white for the highest value. This could be though of
as the color of a heated iron rod (the hottest iron is white
glowing).</p>
<p>The following manual specification uses three color plateau that the
map touches.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$map = array( 'navy', 'gray', 'red' );
$mp-&gt;colormap-&gt;Set($map);</span></pre></td></tr></table></div><p>
</p>
<p>would create a color map that would use '<code class="code">navy</code>' color for
the min value and '<code class="code">red</code>' for the max value and linearly
interpolate all other values for a color range continuously moving from
'<code class="code">navy</code>'-'<code class="code">gray</code>'-'<code class="code">red</code>'. The
color interpolation made between these values is a linear interpolation
of the corresponding RGB values which creates the illusion of a
continuous color change. The array must have at least two colors. There
is no limit on the maximum number of base colors specified. However
using more than ~7-10 colors to specify the color map is probably not to
be recommended.</p>
<p>If <code class="code">$aInvert</code> is set to <code class="code">true</code> then the color
map will be reversed so that the lowest color in the map will be the
highest and vice versa.</p>
</li><li class="listitem">
<p><code class="code">ColorMap::GetCurrMap()</code></p>
<p>Return the current set color map</p>
</li><li class="listitem">
<p><code class="code">ClorMap::SetRange($aMin,$aMax)</code></p>
<p>This is used to manually specify the min and max values to be used for
mapping matrix values to a color. Any values in the matrix that is lower
than <code class="code">$aMin</code> will be set to the min color and any values
above <code class="code">$aMax</code> will be set to the maximum color. </p>
<p>The matrix values in between will be mapped to the entire color scale.
Another way of looking at this is that this will compress the dynamic
range used or the colors. If the min and max values specified are much
higher and lower than the actual content of the matrix the result is
that most of the colors in the matrix will have "middle" colors (and
hence lower the contrast). By default the values are (0,0) which means
that the library will automatically determine the min/max value based on
the input data and use the entire range of colors specified in the color
map.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> This will lower the contrast by roughly 50 percent </span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$mindataval</span><span class="hl-code"> = ... ; </span><span class="hl-comment">//</span><span class="hl-comment"> The minimum data value</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$maxdataval</span><span class="hl-code"> = ... ; </span><span class="hl-comment">//</span><span class="hl-comment"> The maximum data value</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$contrast</span><span class="hl-code"> = -</span><span class="hl-number">0</span><span class="hl-number">.5</span><span class="hl-code">; </span><span class="hl-comment">//</span><span class="hl-comment"> Reduce the contrast by 50%</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$adj</span><span class="hl-code"> = </span><span class="hl-brackets">(</span><span class="hl-var">$maxdataval</span><span class="hl-code">-</span><span class="hl-var">$mindataval</span><span class="hl-code">+</span><span class="hl-number">1</span><span class="hl-brackets">)</span><span class="hl-code">*</span><span class="hl-var">$contrast</span><span class="hl-code">/</span><span class="hl-number">2</span><span class="hl-code">;
</span><span class="hl-var">$matrixplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">colormap</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetRange</span><span class="hl-brackets">(</span><span class="hl-var">$mindataval</span><span class="hl-code">+</span><span class="hl-var">$adj</span><span class="hl-code">, </span><span class="hl-var">$maxdataval</span><span class="hl-code">-</span><span class="hl-var">$adj</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>In a similar way the following code will instead increase the
"contrast" 50% by letting a large part of the data values become mapped
to the min and max color values.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-comment">//</span><span class="hl-comment"> This will increase the contrast by roughly 50 percent </span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$mindataval</span><span class="hl-code"> = ... ; </span><span class="hl-comment">//</span><span class="hl-comment"> The minimum data value</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$maxdataval</span><span class="hl-code"> = ... ; </span><span class="hl-comment">//</span><span class="hl-comment"> The maximum data value</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$contrast</span><span class="hl-code"> = </span><span class="hl-number">0</span><span class="hl-number">.5</span><span class="hl-code">; </span><span class="hl-comment">//</span><span class="hl-comment"> Increase the contrast by 50%</span><span class="hl-comment"></span><span class="hl-code">
</span><span class="hl-var">$adj</span><span class="hl-code"> = </span><span class="hl-brackets">(</span><span class="hl-var">$maxdataval</span><span class="hl-code">-</span><span class="hl-var">$mindataval</span><span class="hl-code">+</span><span class="hl-number">1</span><span class="hl-brackets">)</span><span class="hl-code">*</span><span class="hl-var">$contrast</span><span class="hl-code">/</span><span class="hl-number">2</span><span class="hl-code">;
</span><span class="hl-var">$matrixplot</span><span class="hl-code">-&gt;</span><span class="hl-identifier">colormap</span><span class="hl-code">-&gt;</span><span class="hl-identifier">SetRange</span><span class="hl-brackets">(</span><span class="hl-var">$mindataval</span><span class="hl-code">+</span><span class="hl-var">$adj</span><span class="hl-code">, </span><span class="hl-var">$maxdataval</span><span class="hl-code">-</span><span class="hl-var">$adj</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>The three plots in <a class="xref" href="ch22s04.html#fig.matrix-plot-adj-contrast" title="Figure 22.3. The effects of changing the value range for the colormap">Figure 22.3. The effects of changing the value range for the colormap</a> shows the effect of
increasing and decreasing the contrast with this method.</p>
<div class="figure"><a name="fig.matrix-plot-adj-contrast"></a><p class="title"><b>Figure 22.3. The effects of changing the value range for the colormap</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/matrix-colormap-contrast.png" alt="The effects of changing the value range for the colormap"></div>
</div></div><br class="figure-break">
<div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>When using the auto ranging (the default) the contrast can be
adjusted with a call to </p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">
<p><code class="code">MatrixPlot::SetAutoContrast($aContrast)</code>
</p>
</li></ul></div><p>
</p>
<p>as in</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$matrixplot-&gt;SetAutoContrast(-0.3);</span></pre></td></tr></table></div><p>
</p>
</div>
</li><li class="listitem">
<p><code class="code">ColorMap::SetNumColors($aNum)</code></p>
<p>This is used to specify the number of discrete color steps used in the
map. By default the scale range is divided in approximately 64 color
buckets that all matrix entries are mapped into. Depending on the actual
color map the specified value might be adjusted up or down up to +/-
(p-1). Where <span class="italic">p=number of base colors</span>. Valid ranges are
3-128 but is also dependent on the actual color map. </p>
<p>The reasons for these restriction and the adjustments are</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem">
<p>The minimum number of colors are the number of base colors
in the current color map</p>
</li><li class="listitem">
<p>The number of colors must satisfy the equation</p>
<p><span class="italic">n = p + k*(p-1), k = 0, 1, 2,
...</span> (eq. 1)</p>
<p>where</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="square"><li class="listitem">
<p><span class="italic">n</span> = number of
colors</p>
</li><li class="listitem">
<p><span class="italic">p</span> = number of base colors
that specifies the map</p>
</li></ul></div><p>
</p>
<p>The specified number of colors will be adjusted to the
closest number that satisfies (eq. 1). </p>
</li></ul></div><p>
</p>
</li><li class="listitem">
<p><code class="code">ColorMap::SetNullColor($aColor)</code></p>
<p>If specified this determines what color will be used for any values in
the matrix that are null</p>
</li></ul></div><p>
</p>
</div>
<div class="sect2" title="Changing the module type (rectangle vs. circle)"><div class="titlepage"><div><div><h3 class="title"><a name="id2592595"></a>Changing the module type (rectangle vs. circle)</h3></div></div></div>
<p>By default the module type (the shape that represents one cell in the matrix) is a
rectangle. As was mentioned in the introduction this can also be a circle. This is
controlled by the method</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixPlot::SetModuleType($aType)</code></p>
<p><code class="code">$aType</code>, 0 = Use rectangle, 1 = Use a circle</p>
</li></ul></div><p>
</p>
<p>When using circular module type it might also be useful to specify a separate
background color for the plot since there will be some space between the circles
where the background can be seen. The plot background is specified with the
method</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixPlot::SetBackgroundColor($aColor)</code></p>
</li></ul></div><p>
</p>
<p>An example of using circular modules can be seen in <a class="xref" href="ch22s04.html#fig.matrix_ex05" title="Figure 22.4. Using a circular module type (matrix_ex05.php)">Figure 22.4. Using a circular module type <code class="uri"><a class="uri" href="example_src/matrix_ex05.html" target="_top">(<code class="filename">matrix_ex05.php</code>)</a></code> </a></p>
<p>
</p><div class="figure"><a name="fig.matrix_ex05"></a><p class="title"><b>Figure 22.4. Using a circular module type <code class="uri"><a class="uri" href="example_src/matrix_ex05.html" target="_top">(<code class="filename">matrix_ex05.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/matrix_ex05.png" alt="Using a circular module type (matrix_ex05.php)"></span> </div></div><p><br class="figure-break">
</p>
</div>
<div class="sect2" title="Adjusting the alpha blending of the plots"><div class="titlepage"><div><div><h3 class="title"><a name="id2592689"></a>Adjusting the alpha blending of the plots</h3></div></div></div>
<p>By default the plots are filled with solid colors from the chosen color map. By
specifying an alpha value it is possible to let the background shine through the
matrix plot. The alpha blending is chosen by the method</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixPlot::SetAlpha($aAlpha)</code></p>
<p><code class="code">$aAlpha</code> , 0=No transparency, 1=Full transparency (not so
useful since then only the background can be seen)</p>
</li></ul></div><p>
</p>
<p>
</p><div class="informaltable">
<table border="0"><colgroup><col class="c1"><col class="c2"></colgroup><tbody><tr><td>
<div class="figure"><a name="fig.matrix_ex04.1"></a><p class="title"><b>Figure 22.5. Matrix alpha blending=0.2 <code class="uri"><a class="uri" href="example_src/matrix_ex04.1.html" target="_top">(<code class="filename">matrix_ex04.1.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/matrix_ex04.1.png" alt="Matrix alpha blending=0.2 (matrix_ex04.1.php)"></span> </div></div><br class="figure-break">
</td><td>
<div class="figure"><a name="fig.matrix_ex04.2"></a><p class="title"><b>Figure 22.6. Matrix alpha blending=0.7 <code class="uri"><a class="uri" href="example_src/matrix_ex04.2.html" target="_top">(<code class="filename">matrix_ex04.2.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/matrix_ex04.2.png" alt="Matrix alpha blending=0.7 (matrix_ex04.2.php)"></span> </div></div><br class="figure-break">
</td></tr></tbody></table>
</div><p>
</p>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>As can be seen in the figures only the plot area is adjusted. The legend
is always shown with no transparency.</p>
</div><p>
</p>
</div>
<div class="sect2" title="Specifying the size"><div class="titlepage"><div><div><h3 class="title"><a name="id2592859"></a>Specifying the size</h3></div></div></div>
<p>There are three and disjunct way to specify the size of the matrix plot. However
the size can not be set to any pixel value. Since the matrix plot is a visualization
of a matrix the width and height must always be an even multiple of the number of
rows and columns since each cell in the matrix have an integer number of pixels as
width and height (the module size). This will sometimes force the library to adjust
a specified size so that it is an even multiple of the number of rows and columns in
the input data matrix.</p>
<p>For example; if the matrix has 50 columns this means that the width will only grow
and shrink by multiples of 50 pixels since each cell has an equal number of pixels.
The minimum width for such a matrix is 50 pixels.</p>
<p>There are three ways to specify the size:</p>
<p>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">
<p>by setting the width and height explicitly (in number of pixels). </p>
<p>Note that the actual rendered size might be different depending on the
input matrix size since each cell must have an integer number of pixels
and not all sizes will be even dividable with the input data matrix
size.</p>
</li><li class="listitem">
<p>by setting the width and height as fractions of the overall width and
height of the graph</p>
<p>Note that the actual rendered size might be different depending on the
size of the input data matrix.</p>
</li><li class="listitem">
<p>by specifying the width and height of each rendered cell (a.k.a the
module size)</p>
<p>This specifies the size (in pixels) of each module. The minimum size
is 1x1 pixels.</p>
</li></ol></div><p>
</p>
<p>The size is adjusted by the following two methods</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixPlot::SetSize($aW,$aH)</code></p>
<p><code class="code">MatrixPlot::SetSize($aW)</code></p>
<p>If the two arguments are numbers in range [0.0, 1.0] it will be
interpreted as specifying the size as fractions of the overall graph
width and height. If the number are &gt; 1 they will be interpreted as the
absolute size (in pixels). It is perfectly possible to mix teh two ways.
For example the following is a valid size specification</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$matrixplot-&gt;SetSize(250,0.6); // 250px wide and height will be ~60% of the graph height</span></pre></td></tr></table></div><p>
</p>
<p>If only one argument is specified it will set both the width and
height to the specified size. If the single size is specified as a
fraction the smallest of the graph width/height will be used as the
base.</p>
</li><li class="listitem">
<p><code class="code">MatrixPlot::SetModuleSize($aW,$aH)</code></p>
<p>The two argument specifies the module size, i.e. the size of each cell
in the plot (in pixels).</p>
</li></ul></div><p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>The size does not effect the legend that belongs to a matrix plot.</p>
</div><p>
</p>
</div>
<div class="sect2" title="Specifying the position of the plot on the graph"><div class="titlepage"><div><div><h3 class="title"><a name="id2592997"></a>Specifying the position of the plot on the graph</h3></div></div></div>
<p>The position of the plot by is by default centered vertically and slightly move to
the left of the vertical center in order to compensate for the default legend that
is shown n the right of the plot. The position of the plot is specified by the
method</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixPlot::SetCenterPos($aX,$aY)</code></p>
<p>Specifies the center of the plot to be the given x and y-coordinates.
The position can be specified in either absolute pixels or as fractions
of the width and height (or as a combination).</p>
</li></ul></div><p>
</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3>
<p>In order to position multiple plots on the same graph it is easier to user
the layout classes (as described in <a class="xref" href="ch22s07.html" title="Using layout classes to position matrix plots">Using layout classes to position matrix plots</a>)</p>
</div><p>
</p>
</div>
<div class="sect2" title="Adjusting the legend"><div class="titlepage"><div><div><h3 class="title"><a name="id2593044"></a>Adjusting the legend</h3></div></div></div>
<p>The legend belongs to the matrix plot and not the graph. All legend are instances
of <code class="code">class MatrixLegend</code> and is accessed through the property</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixPlot::legend</code></p>
</li></ul></div><p>
</p>
<p>By default the legend is enabled and positioned to the right of the plot. Both the
size and position of the legend can be manually adjusted. </p>
<p>There are four possible positions of the legend as shown in <a class="xref" href="ch22s04.html#fig.matrix-legend-pos" title="Figure 22.7. Matrix legend positions">Figure 22.7. Matrix legend positions</a>, on each of the four sides of the plot.
The labels of the legend will be automatically adjusted to face aways from the
plot.</p>
<div class="figure"><a name="fig.matrix-legend-pos"></a><p class="title"><b>Figure 22.7. Matrix legend positions</b></p><div class="figure-contents">
<div class="mediaobject"><img src="images/matrix_legend_pos.png" alt="Matrix legend positions"></div>
</div></div><br class="figure-break">
<p>To position the legend the following <code class="code">MatrixPlot</code> method is used</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixPlot::SetLegendLayout($aPos)</code></p>
<p>The position of the legend is specified as an integer in range [0-3]
where 0 is the right side of the plot and the remaining posiotins follow
clockwise from the right, (i.e. 1 is the bottom, 2 is the left and 3 is
the top side).</p>
</li></ul></div><p>
</p>
<p>The following methods can be used to fine tune and adjust the legend</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixLegend::Show($aFlg=true)</code></p>
<p>Used to enable/disable the legend. The following code line would hide
the legend</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">$matrixplot-&gt;legend-&gt;Show(false);</span></pre></td></tr></table></div><p>
</p>
</li><li class="listitem">
<p><code class="code">MatrixLegend::SetModuleSize($aBucketWidth,$aBucketHeight=5)</code></p>
<p>This specifies the size of each color bucket in the legend. </p>
</li><li class="listitem">
<p><code class="code">MatrixLegend::SetSize($aWidth,$aHeight=5)</code></p>
<p>This is an alternative way to specify the size of the legend compare
with the individual bucket specification. With this method the overall
width and height of the legend bar can be adjusted. The size can be
specified s either absolute pixels or as fraction of the width height of
the entire graph.</p>
</li><li class="listitem">
<p><code class="code">MatrixLegend::SetMargin($aMargin)</code></p>
<p>Specifies the margin (in pixels) between the matrix plot and the
legend.</p>
</li><li class="listitem">
<p><code class="code">MatrixLegend::SetLabelMargin($aMargin)</code></p>
<p>Specifies the margin between the min/max label and the legend
bar</p>
</li><li class="listitem">
<p><code class="code">MatrixLegend::SetFont($aFamily,$aStyle,$aSize)</code></p>
<p>Specifies the font for the label on the legend</p>
</li><li class="listitem">
<p><code class="code">MatrixLegend::SetFormatString($aStr)</code></p>
<p>Specifies the format string (in <code class="code">printf()</code> format) to be
used when rendering the legend label</p>
</li></ul></div><p>
</p>
</div>
<div class="sect2" title="Adding row and column legends"><div class="titlepage"><div><div><h3 class="title"><a name="id2593243"></a>Adding row and column legends</h3></div></div></div>
<p>
</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3>
<p>This feature is only available in v3.0.4p and above.</p>
</div><p>
</p>
<p>When using matrix plots to display micro arrays it is often desirable to have
legends for each row and column. <a class="xref" href="ch22s04.html#fig.matrix_edgeex01" title="Figure 22.8. Adding row and column legends to a matrix plot (matrix_edgeex01.php)">Figure 22.8. Adding row and column legends to a matrix plot <code class="uri"><a class="uri" href="example_src/matrix_edgeex01.html" target="_top">(<code class="filename">matrix_edgeex01.php</code>)</a></code> </a> shows an example of this which helps
understand this concept.</p>
<p>
</p><div class="figure"><a name="fig.matrix_edgeex01"></a><p class="title"><b>Figure 22.8. Adding row and column legends to a matrix plot <code class="uri"><a class="uri" href="example_src/matrix_edgeex01.html" target="_top">(<code class="filename">matrix_edgeex01.php</code>)</a></code> </b></p><div class="figure-contents"> <span class="inlinemediaobject"><img src="images/matrix_edgeex01.png" alt="Adding row and column legends to a matrix plot (matrix_edgeex01.php)"></span> </div></div><p><br class="figure-break">
</p>
<p>In the library this is modelled by the <code class="code">class EdgeLabel</code> which is
instantiated in the matrix plot as</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><code class="code">MatrixPlot::collabel</code></p>
<p>Instance for horizontal labels</p>
</li><li class="listitem">
<p><code class="code">MatrixPlot::rowlabel</code></p>
<p>Instance for vertical labels</p>
</li></ul></div><p>
</p>
<p>To adjust the appearance of the labels the following methods can be used:</p>
<p>
</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
<p><span class="bold"><strong><code class="code">EdgeLabel::SetFont($aFF,$aFS,$aSize)</code></strong></span></p>
<p>Specify the font to be used. Keep in mind that the font size should
not be larger than the module size chosen to be able to fit within the
row/column it specifies. For the default module size a font size of 8-9
for a TTF font is usually fine. By default the labels are set in
FF_ARIAL, 8 pt size.</p>
</li><li class="listitem">
<p><span class="bold"><strong><code class="code">EdgeLabel::SetFontColor($aColor)</code></strong></span></p>
<p>Specifies the font color.</p>
</li><li class="listitem">
<p><span class="bold"><strong><code class="code">EdgeLabel::SetMargin($aMargin)</code></strong></span></p>
<p>Set the margin from the edge of the matrix in pixels.</p>
</li><li class="listitem">
<p><span class="bold"><strong><code class="code">EdgeLabel::SetSide($aSide)</code></strong></span></p>
<p>Specifies on what side the labels should be drawn. For horizontal (x)
labels the possible sides are <code class="code">"left"</code> or
<code class="code">"right"</code> and for vertical (y) the possible sides are
<code class="code">"top"</code> and <code class="code">"bottom"</code>.</p>
</li><li class="listitem">
<p><span class="bold"><strong><code class="code">EdgeLabel::Set($aLabels)</code></strong></span></p>
<p>Specifies the 1-dimensional array that holds the labels to be
used.</p>
</li><li class="listitem">
<p><span class="bold"><strong><code class="code">EdgeLabel::SetAngle($aAngle)</code></strong></span></p>
<p>Specify the angle to draw the label at. By default row labels are
drawn at 0 degree and column labels are drawn at 90 degrees
angle.</p>
</li></ul></div><p>
</p>
<p>The simplest use of labels is to use the default values for all parameters and
just set the labels, i.e.</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
2
3
4
5
6
7
8
9
10
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-inlinetags">&lt;?php</span><span class="hl-code">
</span><span class="hl-var">$data</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-code"> ... </span><span class="hl-brackets">)</span><span class="hl-code"> ;
</span><span class="hl-var">$collabels</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-code"> ... </span><span class="hl-brackets">)</span><span class="hl-code"> ;
</span><span class="hl-var">$rowlabels</span><span class="hl-code"> = </span><span class="hl-reserved">array</span><span class="hl-brackets">(</span><span class="hl-code"> ... </span><span class="hl-brackets">)</span><span class="hl-code"> ;
</span><span class="hl-var">$mp</span><span class="hl-code"> = </span><span class="hl-reserved">new</span><span class="hl-code"> </span><span class="hl-identifier">MatrixPlot</span><span class="hl-brackets">(</span><span class="hl-var">$data</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$mp</span><span class="hl-code">-&gt;</span><span class="hl-identifier">collabel</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Set</span><span class="hl-brackets">(</span><span class="hl-var">$collabels</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-var">$mp</span><span class="hl-code">-&gt;</span><span class="hl-identifier">rowlabel</span><span class="hl-code">-&gt;</span><span class="hl-identifier">Set</span><span class="hl-brackets">(</span><span class="hl-var">$rowlabels</span><span class="hl-brackets">)</span><span class="hl-code">;
</span><span class="hl-inlinetags">?&gt;</span></pre></td></tr></table></div><p>
</p>
<p>Below is a final example of adding row and column labels to a matrix graph</p>
<p>
</p><div class="hl-main"><table class="hl-table" width="100%"><tr><td class="hl-gutter" align="right" valign="top"><pre>1
</pre></td><td class="hl-main" valign="top"><pre><span class="hl-code">#=matrix_edgeex02|Adding row and column legends to a matrix plot##</span></pre></td></tr></table></div><p>
</p>
</div>
</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"><a accesskey="u" href="ch22.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>