DOCUMENTATION FOR IDL PLOTTING FACILITIES

			Jan Pedersen
			pedersen.pa@xerox



	The IDL graphics facility consists of three high-level plotting functions, SCATTERPLOT, HISTOGRAM and BOXPLOT. These functions are built on the underlying PLOT package, but are tailored for the specific application. Some provision is also made for the construction of non-standard plots from IDL.
	The PLOT packge provides a default mouse button protocol, which is either added to or superceded in the specialized plots. The default mouse button actions follow:


DEFAULT MOUSE BUTTON ACTIONS:

LEFT BUTTON	While depressed will select the closest
		graphical object.

MIDDLE BUTTON	Pops up a menu of default actions on the
		selected object


RIGHT BUTTON	Pops up a menu of default actions on the
		plot as a whole


DEFAULT MIDDLE MENU ITEMS:

LABEL		Label/Unlabel the selected object. 
		Either a default location for the label
		is selected (point plot objects), or
		the user is queried for a location.

RELABEL		Change the object's label

DELETE		Remove the object from the
		plot (Can be later undeleted).


DEFAULT RIGHT MENU ITEMS:

LAYOUT		Create a SKETCH of the contents of the
		plot. Requires SKETCH and SKETCHSTREAM
		to be loaded.


REDRAW		Redraw the plot

RESCALE		Compute a new scale for both the X and
		the Y axis based on the objects
		currently displayed. May also rescale the
		X or Y axis separately.

EXTEND		Extend both axes slightly. Either the
		x or Y axis may be extended separately.

LABELS		Change the marginal labels. May either
		Choose a margin explicitly, or respond to
		query.

TICS		Enable or disable axis tics.

DESELECT		Deselects the current selected object.

UNDELETE		undelete the last deleted object.




	
(SCATTERPLOT Y X CONTROLLER)		(USER ENTRY POINT)
	
	Y may be a VECTOR or a MATRIX. X may be NIL, a VECTOR or a MATRIX. The usual rules of extended-apply operate here. The basic operation is to plot a VECTOR Y versus a VECTOR X. If X is NIL, then X is taken to be the VECTOR of integers from 1 to (AT (SHAPE Y) 1). Points are taken pairwise, e.g. (AT Y 1) vs (AT X 1), etc. 
	The optional argument CONTROLLER may be used to plot curves instead of points. Controller is broken down with X and Y. That is, one value for controller is supplied for each X,Y vector pair. If the relevant value is 1, then a curve is plotted instead of a collection of points.

	Returns a PLOT.

SPECIAL RIGHT MENU ITEMS:

COORDINATES 	If selected, the world coordinates
		corresponding to the current cursor
		position will be displayed in the prompt
		window. Depress any mouse button to exit
		this mode. 

REGRESS		If selected, a linear regression line
		will be displayed. It is computed from 
		the all points currently in  the
		scatterplot. The regression line also has 
		a special middle menu item, coefficients,
		which will display a summary of the
		regression coefficients.


SPECIAL MIDDLE MENU ITEMS:


COORDINATES	Displays the X and Y coordinates of the 
		selected point in the prompt window.

 
 



(HISTOGRAM BATCH NBINS)		(USER ENTRY POINT)

	BATCH must be a VECTOR of numbers. Plots a histogram of BATCH using a NBINS bins. If NBINS is not supplied, "reasonable" default is calculated depending upon the number of observations in BATCH.

	Returns a PLOT.

SPECIAL RIGHT MENU ITEMS:
	
CHANGE BINS	If selected, a dialogue ensues in the
		prompt window, with a view towards
		establishing a range (MIN , MAX) of
		interest, and a BIN WIDTH. The current
		values for MIN, MAX and BIN WIDTH are
		provided by default.

SUMMARY		Places a quantile summary of the
		HISTOGRAM in a summary window above the
		plot. The summary may be long or short
		The depth of each quantile (its rank
		nearest to either extreme value in the
		ordered data) and its value are listed.

DISPLAY QUANTILES	Overlays a graphical display of the
		sample quantiles above the histogram. The
		display is a BOXPLOT summary of the
		histogram.

	
SPECIAL MIDDLE MENU ITEMS:

VALUES		Prints out the values from BATCH that 
		fall into the selected bin.





(BOXPLOT BATCH1 BATCH2 ... ) 		(NoSpread Function)
	
	BATCH1 BATCH2 ... must be vectors. Generates and plots one boxplot for each BATCH.  
	Returns a PLOT.


SPECIAL MIDDLE MENU ITEMS:

SUMMARY		Prints out, in the summary window, a few
		empirical quantiles. The summary may be
		long or short.

LABEL		A label is associated with each
		boxplot. This menu item allows the user
		to change that label.

HISTOGRAM	A boxplot is also a summary of a
		histogram. This item breaks out a
		histogram for the data values summarized
		by the boxplot.

MOVE		For boxplots, the horizontal  axis is
		purely nominal; it serves simply as a 
		place to layout the boxplots. The MOVE
		items allows the user to rearrange the
		boxplots along the horizontal axis of
		the plot.



	The functions above all return PLOT's, which may be manipulated using the functions described in the PLOT package documentation. For convenience an interface has been provided between IDL arrays and common plot objects.

(ADDPOINTSTOPLOT plot y x pointsymbol pointlabels pointmenu nodrawflg)	(USER ENTRY POINT)

	X and y must be VECTORS. Taking x y pairs one at a time from VECTORS x and y, points are plotted on plot. Pointsymbol is the symbol to plot and may be a BITMAP. Pointlabels is either a label or a list of labels to be associated with each point. Pointmenu is a menu to a associate with each of the plotted points. Nodrawflg T supressses drawing; the points are only entered into the display list of plot.

(ADDCURVESTOPLOT plot y x curvelabel curvewidth curvemenu nodrawflg)	(USER ENTRY POINT)

	Y may be a VECTOR or a MATRIX. X may be NIL, a VECTOR or a MATRIX. X and Y are broken down according to EAPPLY rules. If X is NIL it is assumed to be a vector from 1 to the length of Y. X and Y together determine a series of x,y points through which a curve is drawn on plot. Curvelabel is a label to associate with each curve. Curvewidth must be a integer and specifies the width (in pixels) of the curve. Nodrawflg T supresses drawing, but the curve is entered into the display list of plot.


(ADDPOLYGONSTOPLOT plot y x polygonlabel polygonwidth polygonmenu nodrawflg)	(USER ENTRY POINT)

	Y may be a VECTOR or a MATRIX. X may be NIL, a VECTOR or a MATRIX. X and Y are broken down according to EAPPLY rules. If X is NIL it is assumed to be a vector from 1 to the length of Y. X and Y together determine a series of x,y points through which a polygon is drawn on plot. Polygonlabel is a label to associate with each curve. Polygonwidth must be a integer and specifies the width (in pixels) of the polygon. Nodrawflg T supresses drawing, but the polygon is entered into the display list of plot.

(ADDLINESTOPLOT plot lines linelabels linewidth linemenu nodrawflg)	(USER ENTRY POINT)

	Lines may be a VECTOR or a MATRIX, but the shape of the unkept dimension must be 2. That is, a line is determined by a slope and a constant. Lines is broken down by EAPPLY rules, and for each 2 VECTOR,
a line is drawn on plot. Linelabels may be a LITATOM, STRINGP or a LISTP. Linewidth determines the width of each line in pixels. Nodrawflg T supresses drawing, but the lines are entered into the display list of plot.

(ADDFILLEDRECTANGLESTOPLOT plot rectangles rectanglelabels rectanglewidth rectangletexture rectanglemenu nodrawflg)	(USER ENTRY POINT)

	Rectangles may be a VECTOR or a MATRIX, but the shape of the unkept dimension must be 4. That is, a line is determined by a left, bottom, width and height. Rectangles is broken down by EAPPLY rules, and for each 4 VECTOR, a filledrectangle is drawn on plot. Rectanglelabels may be a LITATOM, STRINGP or a LISTP. Rectanglewidth determines the width of the border in pixels. Rectangletexture if supplied must be a texture. Nodrawflg T supresses drawing, but the rectangles are entered into the display list of plot.
 





�������4����ø�������H��Ø�t��������������������������4����ø���������H��Ø�t��������������������������(��������������������������������������������
TIMESROMAN����������
TIMESROMAN�
����������
TIMESROMAN�
���������GACHA�
��������?�1(DEFAULTFONT 1 (GACHA 10) (GACHA 8) (TERMINAL 8))�
������������������������������)����������������������������������������
�����������������������������������������������������������������������*�������������¤��������������������������������������������������������������������������������������)���������������������������������������
�������*�����������������������������������������������������������*��������������������������������������������������������������������������������������������&�������������*�������������'�������������&�������������������������������������������������������������������������������!�������������������������������������������������������������������������������)�������������)��������������������������������������������������������������������������������������������)�������������"�������������,����������������������������������������������(�������������*���������������������������������)�������������,�������������	������������������������������������������������������������������)���������������������������������$������������������������������������������������������������������������������1�������������������������C��������������������������������������������������������������������������������������������������������%�������������&�������������+�������������+����������������������������������������������(�������������*�������������#�������������-�������������,�������������&��������������������������������������������������������������������������������������������������*�������������'�������������������������������������������������������������������������������������������,����������������������������������������������������������������������������������������������������������������������'�������������%�������������&�������������)�������������(����������������������������������������������#�������������*�������������)�������������'�������������)�������������*���������������������������������%�������������,�������������&�������������
�������������������������������������������������������������������������������)�������������������������������������������������������������������������������������������3��������������������������V��������������������������������������������������������������������������������������������+�������������*����������������������������������������������"�������������*���������������������������������������	�������"�������������$�������������+����������������������������������������������(�������������)�������������)�������������)�������������(�����������������������������������������������������������������Ý��������������������������Z�������������������������•��������������������������X�������������������������ï���������������������������������������`�������������������������ù��������������������������W��������������������������Ë�������������Ù��������������������������‡�������������������������������������������������������������������������������������������������������������������Ûµzº