Docs: linegraf

Introduction

Linegraf (E1) plots a graph on a display device according to formatting specifications and data which are acquired from files or from the standard input. Unlike previous incarnations of this program, the current version of linegraf can read data from separate data files or from the format file. Linegraf now utilizes the standard graphics commands and options, and the user who is unfamiliar with these should read the Multiplot User's Manual before attempting to use linegraf.

Getting Started

Linegraf is invoked as:

where plotdevice is the abbreviated name of the graphics device one wishes to use and formatfile refers to a file containing various format statements. If formatfile is "-", format commands are read from the standard input; if formatfile is "none", no file is used and format commands are taken only from the shell's command line.

Linegraf is really quite easy to use, but it is perhaps best to look at an example of a format file and the plot that it generates before reading about the details of the commands (a formal explication of the contents of the data and format files can be found after the following example). The graph generated by the format file for this example is shown in Figure 1. The file that produced Figure 1 contains the following: 


	trace data1 circle nolines color=2	# Specifies data from file 'data1'
	trace data2 square nolines color=3	# Specifies data from file 'data2'
	tmargin .2				# Leave a margin at the top
	textstyle textsize=4 complex		# Text style for legend and titles
	legend data1 "Controls"			# Legend for data1 with label "Controls"
	legend data2 "Patients"			# Legend for data2 with label "Patients"
	title "RT as a Function of Set Size" textsize=5		# Titles
	title "Patients vs. Controls"
	xtitle "Set Size" simplex
	ytitle "RT" simplex
	xmin 0					# X & Y minima, maxima, # of ticks
	xmax 5
	nxticks 6
	ymin 300
	ymax 800
	nyticks 6
	gridstyle medium			# Line style for grid
	draw					# Draw graph
	coord graph				# Change to graph coordinate system
	line 0 300.5 5 799.4 dotted color=2	# Draw regression lines
	line 0 384.0 5 732.6 dashed color=3
	coord screen				# Change back to screen coordinates
	text 0.08 1.14 "Figure 1" textsize=3 italics
While some of the specific commands may be unclear, the basic format and manner in which linegraf works should be apparent from this example. The remainder of this document simply explains the details of the linegraf commands, most of which were used in this example.

Figure 1


Data Files

The trace command is used to specify the name of a file containing the data to be plotted. Normally, the data for separate traces are stored in separate files. Each line of data represents a single point on the graph, and consists of the x value, the y value, and an optional error value. The error value can be preceded by a plus or minus if only the positive or negative half of the error bar should be plotted. For example, the file 'data1' contains: 


	1 403 10
	2 496 -20
	4 701 +28
If desired, the data can alternatively be placed in the format file, directly following the relevant trace command. This is accomplished by specifying "none" as the filename and by placing the word "end" at the end of the data, as in: 

	trace none
	1 403 10
	2 496 -20
	4 701 +28
	end
The data for multiple traces can also be placed in a single file, with the word "end" following the data for each trace. Each time a trace command occurs with a particular filename, data are read from the corresponding data file beginning at the current position and continuing until the "end" statement. For example, the data for both traces in figure 1 could be stored in a single file named "data", which would look like this: 

	1 403 10
	2 496 -20
	4 701 +28
	end
	1 458 12
	2 517 +18
	4 665 -30
and the trace commands would appear as: 

	trace data circle nolines color=2
	trace data square nolines color=3

Format Files

The parameters controlling the format of the plot are defined in a file that contains a list of commands, each having various mandatory and optional parameters. An editor such as vi (1) is typically used to create this file. Linegraf (E1) uses the standard ERPSS command processing interface, which is described in the Multiplot User's Manual. Briefly, each command consists of a command name, possibly followed by a set of mandatory parameters and finally by a set of optional parameters. Each parameter is a single argument, which means that it can contain no spaces or tabs unless enclosed in double quotes. Normally, each line consists of a single command and its parameters. Many of the linegraf commands use the standard graphics options that are described in the documentation for plotcmd (E3p), and these will be abbreviated as "line_opts", "text_opts", and "trans_opts" for line, text, and translation options, respectively.

Detailed Keyword Semantics

In addition to the commands listed above, all of the standard graphics commands that are available for multiplot (E1) are also available for linegraf (E1).

Summary of Commands

Commands specific to linegraf


	legend tracefile/tracenumber "label" [line_opts symboltype
	radius=value]
	trace datafile [x=file/line[*value[+value]] line_opts
	symboltype radius=value nolines nosymbols]
	title string [text_opts] or header string [text_opts]
	xtitle string [text_opts] or xlabel string [text_opts]
	ytitle string [text_opts] or ylabel string [text_opts]
	xmin value
	xmax value
	ymin value
	ymax value
	lmargin value
	tmargin value
	rmargin value
	bmargin value
	nxticks value
	nyticks value
	xtickstyle [format=value text_opts]
	ytickstyle [format=fw.prec text_opts]
	autoxtickoff
	autoytickoff
	xtick x_value [label=string text_opts]
	ytick y_value [label=string text_opts]
	draw
	coord screen/graph
	readfile filename [trans_opts]

Standard graphics commands


	linestyle [line options]
	gridstyle [line options]
	textstyle [line and text options]
	point x y [line options]
	line x1 y1 x2 y2 [line options]
	moveto x y
	lineto x y [line options]
	arrow x1 y1 x2 y2 length angle [line_options]
	arc mid_x mid_y radius start_degrees stop_degrees [line options]
	rect left top right bottom [line options fill=value]
	startpgon
	endpgon
	drawpgon x y [line options fill=value]
	text x y "string" [line and text options]
	translate [translation options]
	trans [translation options]
	vfile filename [translation options]
LINEGRAF
Tutorial Introduction and Reference Manual
Jonathan C. Hansen (Version 1)
Ronald Ohst (Version 2)
Steve Luck (Version 3)


© 2005 UCSD ERP Lab
Please send comments and suggestions to the ERPSS Webmaster