<html>
<head>
<!-- This file has been generated by unroff 1.0, 03/11/09 12:56:13. -->
<!-- Do not edit! -->
<STYLE TYPE="text/css">
<!--
A:link{text-decoration:none}
A:visited{text-decoration:none}
A:active{text-decoration:none}
OL,UL,P,BODY,TD,TR,TH,FORM { font-family: arial,helvetica,sans-serif;; font-size:small; color: #333333; }
H1 { font-size: x-large; font-family: arial,helvetica,sans-serif; }
H2 { font-size: large; font-family: arial,helvetica,sans-serif; }
H3 { font-size: medium; font-family: arial,helvetica,sans-serif; }
H4 { font-size: small; font-family: arial,helvetica,sans-serif; }
-->
</STYLE>
<title>ploticus: proc categories</title>
<body bgcolor=D0D0EE vlink=0000FF>
<br>
<br>
<center>
<table cellpadding=2 bgcolor=FFFFFF width=550><tr>
<td>
<table cellpadding=2 width=550><tr>
<td><br><h2>proc categories</h2></td>
<td align=right>
<small>
<a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
Version 2.41 Mar2009
</small><br><a href="../doc/scripthome.html">Scripts</a>
<td></tr></table>
</td></tr>
<td>
<br>
<br>
<title>Manual page for proc_categories(PL)</title>
</head>
<body>
<p>
<b>proc categories</b>
defines a category set to be associated with the X or Y axis, for
handling categorical data, typically for bar positioning, etc.
This proc also controls attributes related to category processing.<tt> </tt>
<p>
Categories can be defined using this proc before invoking <b>proc areadef</b>.<tt> </tt>
In older Ploticus versions categories were defined within <b>proc areadef</b> using an
<a href="#oldway">
old syntax described below
</a>
which will continue to be supported.
However, additional capabilities and higher capacities are available via
proc categories.<tt> </tt>
<p>
Proc categories also assumes the functionality of the old <b>proc catslide</b>
(see the <tt>slideamount</tt> attribute).<tt> </tt>
<br><br><br>
<h2>Category sets</h2>
The category scaletype allows
positioning of data points using categorical bins rather than a continuous scale,
often useful in positioning bars, rangebars, etc.<tt> </tt>
<p>
Category names are alphanumeric labels, and are generally short (less than 40 chars long).<tt> </tt>
Embedded whitespace in a category name is allowed.<tt> </tt>
<p>
Categories are often used as the basis for an axis, and when this is done the category name can be given as a
<a href="attributetypes.html#plotvalue">
locvalue
</a>
to position labels, etc (for example in proc annotate's location parameter).<tt> </tt>
When category names are used this way, and the category names contain embedded spaces, use underscores instead of spaces.<tt> </tt>
<p>
During plotting, data are categorized by comparing a given data field with each
defined category label until a match is found, then the point is plotted at that
location.<tt> </tt>
If no match is found nothing is plotted, and an error is issued if the <tt>-showbad</tt>
command line option is in effect.<tt> </tt>
<p>
One category set may be defined for the X axis, and one for the Y axis.<tt> </tt>
Category sets and associated attributes are independent of individual
plotting areas (thus categories may be defined one time and then used in
several different plotting areas). Category sets are also completely independent
from input data sets (thus categories may be defined from one set of data,
then still be in effect after different data are read in).<tt> </tt>
<p>
Category sets may be taken from a data field or specified explicitly.
Category labels should always be unique within an axis, and are normally
displayed in the same order as specified.<tt> </tt>
<p>
The default maximum number of categories is 250 in X and 250 in Y.<tt> </tt>
These limits can be raised using the <tt>listsize</tt> attribute.<tt> </tt>
<br><br><br>
<h2>Example</h2>
See the
<a href="../gallery/mouse.htm">
mouse
</a>
gallery example.<tt> </tt>
<br><br><br>
<h2>Attributes</h2>
Some attributes need to be specified in a certain order, unlike most other ploticus procs.<tt> </tt>
The <tt>axis</tt> attribute must be specified before any other attribute.<tt> </tt>
Also, <b>#clone</b> is not supported.<tt> </tt>
<p>
<b>axis</b>
<tt>x | y</tt>
<dl>
<dt><dd><p>
Which axis the category set is associated with.<tt> </tt>
This attribute must be the first one specified.<tt> </tt>
<br>
Example: <tt>axis: x</tt>
<br><br>
</dl>
<p>
<b>datafield</b>
<a href="attributetypes.html#dfield">
dfield
</a>
<dl>
<dt><dd><p>
Specify a data field to get category labels from.<tt> </tt>
<br>
Example: <tt>datafield: measnum</tt>
<br>
Example: <tt>datafield: 2</tt>
<br><br>
</dl>
<p>
<b>categories</b>
<a href="attributetypes.html#text">
multi-line text
</a>
<dl>
<dt><dd><p>
List of category labels, one per line. Terminated with a blank line.<tt> </tt>
Example:
<pre>
categories:
red
blue
orange
</pre>
<br><br>
</dl>
<p>
<b>select</b>
<a href="select.html">
select expression
</a>
<dl>
<dt><dd><p>
Allows data rows to be selected for inclusion as categories using a selection expression.
This only has an effect when used with <tt>datafield</tt>, and it must be specified before <tt>datafield</tt>.<tt> </tt>
<br>
Example: <tt>select: @4 != null</tt>
<br><br>
</dl>
<p>
<b>extracategory</b>
<a href="attributetypes.html#text">
text
</a>
<dl>
<dt> <dd>
Allows an extra category to be added explicitly. For example, this attribute might
be useful when categories are being set by a data field and it is desired to have an additional
"Total" category.
<dt><dd><p>
This position of this attribute relative to others is important.<tt> </tt>
If specified before the category set is defined,
the extra category will be added to the beginning of the category list and it will appear
near the axis min. If specified after, the extra category will be
appended to the category list and appear near the axis max.<tt> </tt>
<dt><dd><p>
This attribute may be specified as many times as necessary, with each adding an additional category.
<br>
Example: <tt>extracategory: Total</tt>
<br><br>
</dl>
<p>
<b>checkuniq</b>
<tt>yes|no</tt>
<dl>
<dt><dd><p>
Default is <tt>yes</tt>.
The only situation where one might set this to <tt>no</tt> is with
data sets where each category tag is guaranteed to appear once and only once.. to get a tiny gain in efficiency--
because incoming category tags won't be checked against the list of known tags.<tt> </tt>
Since the max # of categories is a
few hundred this doesn't amount to much savings anyway.<tt> </tt>
<br><br>
</dl>
<p>
<b>comparemethod</b>
<tt>exact | beginslike | length=</tt><i>n</i>
<dl>
<dt><dd><p>
When data points are being plotted using category scaletype, a given data
field is compared against each defined category label until a match is found,
then the data is plotted at that location.<tt> </tt>
This attribute controls the method used for matching.<tt> </tt>
Default is <tt>exact</tt>.<tt> </tt>
To compare for only the length of the data field, use <tt>beginslike</tt>.<tt> </tt>
To compare for a specific length, use <tt>length=</tt><i>n</i>, where <i>n</i> is
the number of characters.<tt> </tt>
<br><br>
</dl>
<p>
<b>roundrobin</b>
<tt>yes | no</tt>
<dl>
<dt><dd><p>
Default is <tt>yes</tt>. Normally a round-robin style lookup algorithm is used,
which is most efficient when the category labels are encountered in the same
order as defined. In practice this is most often the case.<tt> </tt>
However, this attribute can be set to <tt>no</tt> which will cause the lookup to
be sequential starting each time at the begining of the list.<tt> </tt>
This might perform better in certain situations.<tt> </tt>
<br>
Example: <tt>roundrobin: no</tt>
<br><br>
</dl>
<p>
<b>slideamount</b>
<i>n</i>
<dl>
<dt><dd><p>
Adjust category locations by a small amount. For categories in X
this attribute shifts the location of all categories rightward when given a positive slideamount value,
and leftward for negative values. For categories in Y this attribute shifts categories
downward when given positive slideamount values, and upward for negative values (which may be contrary to
what you'd expect).<tt> </tt>
<dt><dd><p>
This attribute is often used to set up category "bins". For example in X,
the first category is located at X=1, the second at X=2, and so on by default. For certain data displays
it's nice to have the first category located at X=0.5, the second at X=1.5, and so on, so that the first
category is immediately adjacent to the origin. slideamount allows you to do this.<tt> </tt>
<dt><dd><p>
Another common use is to display pairs or clusters. slideamount can be used to shift a bit to one side
to do the first member of a pair, then shift back the other way to do the second member.<tt> </tt>
<dt><dd><p>
Note: when areadef sets up the plotting area and scaling it cancels any
<tt>slideamount</tt> currently in effect. So <tt>slideamount</tt> must be specified in a separate
#proc categories block <b>after</b> #proc areadef, as shown below.
The following will slide the categorical X axis 0.1 scale units to the left:
<pre>
#proc categories
axis: x
...
#proc areadef
...
#proc categories
axis: x
slideamount: -0.1
</pre>
<br><br>
</dl>
<p>
<b>listsize</b>
<i>n</i>
<dl>
<dt><dd><p>
Specify the size of the category list. Default capacity is 250 categories per axis.<tt> </tt>
If you need more categories, you can specify the upper limit here.<tt> </tt>
This attribute may be specified only one time per <b>script</b>, and must be given before
any categories are defined for the axis.<tt> </tt>
Example:
<pre>
proc categories
axis: x
listsize: 1000
datafield: 2
</pre>
<br><br><br>
<a name=oldway></a>
</dl>
<h2>Old syntax for setting up categories</h2>
Here is a summary of the old syntax used within
<a href="areadef.html">
proc areadef
</a>
to specify categories. This syntax will continue to be supported, but new work
should use proc categories (above).<tt> </tt>
<br><br>
<p>
<b>xcategories</b> <tt>datafield=</tt><i>dfield</i><tt> [selectrows=</tt><i>conditional expression</i>]
<br>
..OR..<tt> </tt>
<br>
<b>xcategories</b>
<a href="attributetypes.html#text">
multi-line text
</a>
<dl>
<dt> <dd>
Defines a set of categories for use on the X axis.<tt> </tt>
To take categories from a data field, use the construct
<tt>datafield=</tt><i>dfield</i>
where <i>dfield</i> is a
<a href="attributetypes.html#dfield">
data field specification.<tt> </tt>
</a>
Or, category names may be listed explicitly one per line, terminating with a blank line.<tt> </tt>
An optional
<a href="select.html">
select expression
</a>
may be supplied if taking categories from data field,
to use selected data rows only (new in 2.03.. see example 2 below).<tt> </tt>
<pre>
Example 1: xcategories: datafield=1
Example 2: xcategories: datafield=1 selectrows=@3 like S*
Example 3: xcategories: Red
Blue
Green
</pre>
</dl>
<p>
<b>ycategories</b> <tt>datafield=</tt><i>dfield</i><tt> [selectrows=</tt><i>conditional expression</i>]
<br>
..OR..<tt> </tt>
<br>
<b>ycategories</b>
<a href="attributetypes.html#text">
multi-line text
</a>
<dl>
<dt> <dd>
Specify categories for use in Y, one per line.<tt> </tt>
Same syntax as <tt>xcategories</tt> above.<tt> </tt>
Default orientation of categories along Y is from top to bottom.<tt> </tt>
<br><br>
</dl>
<p>
<b>xextracategory</b>
<a href="attributetypes.html#text">
text
</a>
<dl>
<dt> <dd>
Allows an extra X axis category to be added explicitly. For example, this attribute might
be useful when categories are
being set by a data field and it is desired to have an additional "Total" category.<tt> </tt>
Unlike most other ploticus attributes, its behavior is position-dependent,
and it may be specified more than once.<tt> </tt>
If specified before (above) <tt>xcategories</tt> in the proc areadef attributes,
the extra category will be added to the beginning of the category list and it will appear
near the X axis min. If specified after, the extra category will be
appended to the category list and appear near the X max.<tt> </tt>
This attribute may be specified one or more times, with each
adding a category.
<pre>
Example: xextracategory: Total
xextracategory: Weekly average
</pre>
<br><br>
</dl>
<p>
<b>yextracategory</b>
<a href="attributetypes.html#text">
text
</a>
<dl>
<dt> <dd>
Same as <tt>xextracategory</tt> above, but for the Y axis.<tt> </tt>
<br><br>
</dl>
<p>
<b>catcompmethod</b> <tt>beginswith</tt> | <tt>exact</tt> | <tt>length=</tt><i>N</i>
<dl>
<dt> <dd>
Control the details of how category comparisons are done.<tt> </tt>
The default is <tt>beginswith</tt> for backward compatibility; <tt>exact</tt>
is highly recommeded for new work.<tt> </tt>
In all cases, the comparisons are case-insensitive, and work from the beginning of the
categories list to the end, stopping when a match is found.<tt> </tt>
<dt> <dd>
<tt>beginswith</tt> = the comparison is successful if the data item matches
the category name but only to the length of the data item.
<dt> <dd>
<tt>exact</tt> = the comparison is successful if the data item exactly
matches the category name.<tt> </tt>
<dt> <dd>
<tt>length=</tt><i>N</i> = the comparison is successful if the first <i>N</i> characters
of the data item match the first <i>N</i> characters of the category name.<tt> </tt>
<br><br><br>
</dl>
<h2>Old syntax for proc catslide</h2>
Here's an example of the old syntax for proc catslide, which has been superseded
by the <tt>slideamount</tt> attribute:
<pre>
#proc catslide
axis: x
amount: -0.1
<br>
<br>
</td></tr>
<td align=right>
<a href="../doc/welcome.html">
<img src="../doc/ploticus.gif" border=0></a><br><small>data display engine <br>
<a href="../doc/Copyright.html">Copyright Steve Grubb</a>
<br>
<br>
<center>
<img src="../gallery/all.gif">
</center>
</td></tr>
</table>
<br>
<center>
<table><tr><td>
Ploticus is hosted at http://ploticus.sourceforge.net</td><td> </td><td>
<a href="http://sourceforge.net/projects/ploticus"><img src="http://sflogo.sourceforge.net/sflogo.php?group_id=38453&type=12"
width="120" height="30" border="0"
alt="Get ploticus data display engine at SourceForge.net. Fast, secure and Free Open Source software downloads" /></a>
</td></tr></table>
</center>
</pre>
<p><hr>
Markup created by <em>unroff</em> 1.0, <tt> </tt> <tt> </tt>March 11, 2009.
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ed05dc5f357c49fdded780f52b150dce
>
files
>
23
