1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
|
.ig >>
<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: ploticus prefabs handbook</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>Ploticus Prefabs Handbook</h2></td>
<td align=right>
<small>
<a href="../doc/welcome.html"><img src="../doc/ploticus.gif" border=0></a><br>
Version 2.33 Jun'06
</small><br><a href="../doc/prefabs.html">Prefabs</a>
<td></tr></table>
</td></tr>
<td>
<br>
<br>
.>>
.TH Ploticus_Prefabs_Handbook PL "02-JUN-2006 PL ploticus.sourceforge.net"
.LP
Ploticus prefabs are the easiest way to use the package.
You specify certain parameters directly on the command line, and everything
else is handled automatically.
.LP
.ig >>
The <a href="prefab_stdparms.html">standard prefab parameters</a> are common to most of the
various prefabs and control things like reading in data, setting up axes, legends, and so on.
<br>
<br>
<b>Available prefabs:</b>
<ul>
<table cellpadding=2 border=1><tr>
<td><a href="prefab_chron.html"><img src="../gallery/prefab_img/chron7thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_chron.html">chron</a></font> - chronological data (dates, times, etc); also can tabulate on week, month, etc.
</td>
<td><a href="prefab_compare.html"><img src="../gallery/prefab_img/compare4thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_compare.html">compare</a></font> - convenient comparison of 1-4 vars across 1-15 categories. Computes means and SD, and displays groups of bars.
<img src="../gallery/gif/new.gif">
</td>
<td><a href="prefab_cumufrac.html"><img src="../gallery/prefab_img/cumufrac2thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_cumufrac.html">cumufrac</a></font> - cumulative fraction plots (linear or log)
</td>
</tr><tr>
<td><a href="prefab_dist.html"><img src="../gallery/prefab_img/dist1thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_dist.html">dist</a></font> - frequency distribution histogram, numeric or alphanumeric bins
</td>
<td><a href="prefab_heatmap.html"><img src="../gallery/prefab_img/heatmap2thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_heatmap.html">heatmap</a></font> - heatmaps, density grids, and similar displays
</td>
<td><a href="prefab_lines.html"><img src="../gallery/prefab_img/lines3thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_lines.html">lines</a></font> - line plots with optional data points and error bars, up to 4 groups
</td>
</tr><tr>
<td><a href="prefab_pie.html"> <img src="../gallery/prefab_img/pie4thm.gif" border=0> </a><br>
<font size=+1>
<a href="prefab_pie.html">pie</a></font> - pie graphs
</td>
<td><a href="prefab_scat.html"><img src="../gallery/prefab_img/scat2thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_scat.html">scat</a></font> - scatterplots, with optional regression line, point labeling,
and error bars, up to 4 groups
</td>
<td><a href="prefab_stack.html"><img src="../gallery/prefab_img/stack1thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_stack.html">stack</a></font> - stacked bar graphs up to 4 levels
</td>
</tr><tr>
<td><a href="prefab_stack.html"><img src="../gallery/prefab_img/stack3thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_stack.html">stack</a></font> - also does stacked area plots
</td>
<td><a href="prefab_vbars.html"><img src="../gallery/prefab_img/vbars2thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_vbars.html">vbars</a></font> - bar graph of 1 or 2 groups with precomputed error bars
</td>
<td><a href="prefab_vbars.html"><img src="../gallery/prefab_img/vbars3thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_vbars.html">vbars</a></font> - also just the precomputed error bars
</td>
</tr><tr>
<td><a href="prefab_vdist.html"><img src="../gallery/prefab_img/vdist1thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_vdist.html">vdist</a></font> - bee swarm distribution of one variable.
</td>
<td><a href="prefab_vdist.html"><img src="../gallery/prefab_img/vdist3thm.gif" border=0></a><br>
<font size=+1>
<a href="prefab_vdist.html">vdist</a></font> - histogram comparison of two variables.
</td>
<td> </td>
</tr>
<tr><td colspan=3>
<li> <font size=+1><a href="prefab_draw.html">draw</a></font>
for processing drawdumps or ploticus draw commands
<li> <font size=+1><a href="prefab_multidist.html">multidist</a></font>
multiple overlaid frequency distributions
<li> <font size=+1><a href="prefab_processdata.html">processdata</a></font>
use ploticus as a data processing filter (no plots)
<img src="../gallery/gif/new.gif">
</td></tr>
</table>
<br>
</ul>
<center>
<b><a href="prefab_gallery.html">Gallery of all prefab examples</a>
<a href="prefab_news.html">What's new - prefabs</a></b>
<br>
<br>
<b><a href="prefab_stdparms.html">Summary of the standard prefab parameters</a></b>
</center>
<br><br>
<b>Quick start</b>
<ul>
1. <a href="download.html">Download the software</a> and install.
<br>
2. Set the <tt>PLOTICUS_PREFABS</tt> environment variable to the pathname of the ploticus <tt>./prefabs</tt> directory.
Be sure that the <tt>pl</tt> command is in your command search <tt>PATH</tt>.
<br>
3. Look at the <a href="prefab_gallery.html">prefab examples gallery</a> and find an example close to what you want.
<br>
4. Execute the pl command appearing below the example.
<br>
5. Check the <a href="prefab_stdparms.html">standard parameters</a> and the individual prefab manual page for
more possibilities.
<br>
6. Use prefabs as far as possible for prototyping and "quick-n-dirty" uses.. if you need "extreme"
customization, use the <tt>-echo stdout</tt> commmand line option to dump out the equivalent
ploticus script, and go from there.
<br>
7. Overlay and/or combine multiple <tt>pl</tt> runs using <tt>-drawdump</tt> (see below)
</ul>
<br>
<b>The pl(1) command</b>
<ul>
<a href="pl.1.html">The pl(1) command</a>
generates graphs. The <tt>-prefab</tt> command line option
selects a prefab, eg: <tt> -prefab chron</tt>.
You'll also need to specify the output format you want, eg. <tt>-png</tt>
and the desired output file name eg. <tt>-o try35.png</tt>.
Other handy command line options include <tt>-debug</tt> and <tt>-scale</tt>.
There are a lot of other command line options, almost all of which can be used with prefabs.
Be careful not to confuse pl command line options such as <tt>-scale 0.7</tt> with prefab
parameters.. they are two different things.
</ul>
<br>
<b>The PLOTICUS_PREFABS environment variable</b>
<ul>
must be set to the directory where prefab files are located. Normally this is a
directory called <tt>./prefabs</tt> in the ploticus distribution.
Another possibility is to set this when compiling ploticus (see <tt>PREFABS_DIR</tt> in the Makefile).
Note that, to avoid compatibility issues, the prefab files should be from the same ploticus version as the pl executable.
</ul>
<br>
<b>Prefab parameters</b>
<ul>
control what prefabs do.
Parameters are usually specified on the command line using the form <tt><i>parametername</i>=<i>value</i></tt>
but they may also (sometimes) be set
<a href="dataformat.html#set">from within an input data file</a> or in your <a href="config.html">ploticus config file</a>.
<p>
There are <a href="prefab_stdparms.html">standard prefab parameters</a>
which are parameters that are in common to most of the prefabs, and specify plot data fields, title, axes,
data format, legends, and so on. There are also parameters that are
specific to individual prefabs ... these are described on the individual prefab manual pages.
</ul>
<br>
<b>Commands and the shell</b>
<ul>
Ploticus prefab commands can get rather long.. most shells allow backslash for
continuing commands onto additional lines.
If a parameter value contains embedded whitespace the value should be enclosed in quotes.
You can get a multi line title by splitting it over multiple lines. Here's an example:
<tt>
<br>
pl -prefab pie1 data=data1 fld=3 label=1 \
<br>
title="Travel expenditures
<br>
By department
<br>
Fiscal year 2000"
</tt>
</ul>
<br>
<b>Input data</b>
<ul>
Input data can come from files or standard input.
It should be plain ascii text. Whitespace, tab, and comma delimited fields are supported.
You can plot various types of data including numeric, category, date, and time.
For date and time data, use the <a href="prefab_chron.html">chron prefab</a>.
</ul>
<a name=drawdump></a>
<br>
<b>Overlaying and combining plots from multiple pl runs</b>
<ul>
Beginning in version 2.30 you can use the <tt>-drawdump</tt> and <tt>-drawdumpa</tt> command line options
to overlay and/or combine plots from multiple pl runs into one graphic image / result. Example:
<ul>
<tt>
pl -prefab scat "rectangle= 1 1 3 3" .... -drawdump mydump <br>
pl -prefab scat "rectangle= 4 1 6 3" .... -drawdumpa mydump <br>
pl -prefab draw dumpfile=mydump -png -o all.png
</tt>
</ul>
<br>
Hints:
<br>
<li> if you're setting a background color this should be done only in the first <tt>pl</tt> invocation.
<li> for overlays using the same plotting area rectangle and scaling, turn off axis generation (<tt>xaxis=none yaxis=none</tt>).
<li> for overlays using same plotting area rectangle and different scaling, use eg. <tt>yaxis=left</tt> for one and <tt>yaxis=right</tt> for the other.
<li> clickmap/mouseover info is not retained in drawdump file, but can be generated by individual pl invocation for PNG (etc.)
<li> you can get a graphic result while generating a drawdump.. just specify the device argument somewhere to the right of
the -drawdump <i>filename</i> argument on the command line.
</ul>
<br>
<b>Customizing</b>
<ul>
It is possible to include chunks of ploticus script code to add annotations, etc.
(see the standard parameters <a href="prefab_stdparms.html#include">include1 and include2</a>).
Otherwise, for needs that aren't addressed by existing prefabs, you can develop a ploticus script.
Get as far as you can with the prefab, then use the
<tt>-echo stdout</tt> option to dump out an equivalent script.. then modify the script as needed.
</ul>
<br>
<b>Notes</b>
<ul>
<li> No error message is issued when an invalid prefab parameter name is used.
</ul>
<br>
<h3>Reference</h3>
<ul>
<br><a href="dataformat.html">Input data for plotting</a>
<br><a href="scaleunits.html">Data types and scaling: numeric, category, date, time</a>
<br><a href="attributetypes.html">Absolute units, scaled units, etc.</a>
<br><a href="attributetypes.html#n">Attribute types: dfield, plotvalue, locvalue, printf, string, text, multilinetext</a>
<br><a href="linedetails.html">Linedetails</a>
<br><a href="symboldetails.html">Symboldetails</a>
<br><a href="textdetails.html">Textdetails</a>
<br><a href="select.html">Select expressions</a>
<br><a href="color.html">Colors</a>
<br><a href="fonts.html">Fonts</a>
<br><a href="dates.html">Dates</a>
<br><a href="times.html">Times</a>
<br><a href="config.html">Your ploticus config file - settings to be in effect all the time</a>
<br>
<br><a href="news.html">What's new - general</a>
<br><a href="prefab_news.html">What's new - prefabs</a>
<br><a href="faq.html">FAQ</a>
<br><a href="http://groups.yahoo.com/group/ploticus">Newsgroup</a>
<br><a href="pl.1.html">pl(1) man page</a>
<br><a href="api.html">libploticus API</a>
<br><a href="web.html">Web usage notes</a>
<br><a href="clickmap.html">Imagemap, clickmap & mouseover text bubbles</a>
<br><a href="dynamic.html">Dynamic content and just-in-time usage notes</a>
<br><a href="cgi.html">Direct CGI mode</a>
<br><a href="paper.html">Paper-based report usage notes</a>
<br><a href="posters.html">Large-sized poster usage notes</a>
<br><a href="prepress.html">Pre-press work usage notes</a>
<br><a href="svg.html">SVG notes</a>
<br><a href="swf.html">SWF (shockwave-flash) notes</a>
<br><a href="http://ploticus.sourceforge.net/doc/download.html">Download</a>
<br><a href="buildinfo.html">Build instructions</a>
<br><a href="support.html">Troubleshooting & support</a>
<br><a href="limits.html">Limitations</a>
<br><a href="Copyright.html">Copyright and permissions <img src="../doc/gpl.gif" border=0></a>
<br><a href="http://ploticus.sourceforge.net/steve.html">Steve Grubb's home page</a>
</ul>
<br>
<b><a href="welcome.html">Back to ploticus home</a></b>
<br><br>
<b><a href="scripthome.html">Ploticus scripts handbook</a></b>
<br>
.>>
.ig >>
<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>
Ploticus is hosted at http://ploticus.sourceforge.net <br>
<img src="http://sourceforge.net/sflogo.php?group_id=38453" width="88" height="31" border="0" alt="SourceForge Logo">
</center>
.>>
|
