PLOT1D [TOC]


by Ben-chin Cha (05/09/01)


INTRODUCTION

PLOT1D provides the IDL user with a general purpose multiple line(s) plot package. It accepts flexible types of 1D input data array: vector, scattering vector, or multiple lines 2D vector array.

It is a widget application and provides simple user interface for tailoring various plot options and labeling features on the final plot. It allows the user dynamically to reset the selected lines, line styles, plot title, plot margins, X label, Y label, legends, comments, etc.. Two types of PS plot are available: drawing area dump or PS plot.

Many plot options can be settable on the command line through the keyword specification.

The widget window associated with PLOT1D program is readjustable by the window manager.

Command Syntax

Please refer User's Reference Guide for PLOT1D for command syntax.


SYSTEM SETUP

Setup Requirement for Unix System

At APS all IDL programs are installed in the /usr/local/epics/extensions/bin/$HOST_ARCH directory. For proper operation of these programs, a user first has to make sure that the IDL 5.3 or later is used. For example, use IDL 5.3 release, set the following :
 
	source /usr/local/rsi/idl_5.3/bin/idl_setup 
	
In order to access IDL programs installed in the local epics/extensions/bin, a user has to make sure that the following two environment variables are set before invoking IDL :
         setenv EPICS_EXTENSIONS /usr/local/epics/extensions
         setenv IDL_STARTUP $EPICS_EXTENSIONS/bin/$HOST_ARCH/viewer_startup.pro 
	
and make sure the directory /usr/local/epics/extensions/bin/$HOST_ARCH is in his/her IDL search path.

Access PLOT1D Program

To access the PLOT1D program in IDL just enter the following command at the IDL prompt:
	IDL> plot1d, [X,] Y 
This commnad will automatically load the plot1d.pro, PS_open.pro and xdisplayfile.pro program into the IDL session and initially all the lines defined in the data array Y are plotted. The optional variable X specifies the independent X vector values. The variable Y should contains either a single line of 1D vector or multiple lines of 1D data vectors (i.e. a 2D array).

The number of data points in X vector and Y array must be the same. If the variable X is not specified by the user on the command line the index vector of the number of the data point in Y vector is assumed.

A user then can use the various features of plot1d program to tailor the line plot according to his desire.

USER INTERFACE

The main window consists of the drawing area and a row of button widgets. The button widgets allow the user to access the various features of the plot1d program.

The buttons labeled with the suffix ... indicates there is a window or widgets associated with it.

If the background color is red a user may have problem to see the red curve drawned, a user can reverse the background color or try to use a different color table.

Drawing Area

The default drawing area is 350x350 pixels. The initial plot of selected curves is plotted based on the default option settings by the PLOT1D. Most default options can be overrided by the keyword specifications on the command line.

The drawing area plot dynamically reflects the plot option changes through the features in the user interface in the plot1dSetup dialog.

Plot1d Options

The presence of 'Data...' button depends on the command line setting of the keyword DATA.
Data...   - Tabulate plot data in plot1d.txt file , 
	    call xdisplayfile to display data, and pop up 
	    rename_dialog to save as a permanent file
Rvs Bkg   - Reverse the background color
Options...- Pop up plot1dSetup dialog.
Printer...- Pop up PS printer setup dialog.
Print     - Dump the drawing area to PS printer
PS Plot   - Send plot to PS driver
Close     - Close the plot1d program
If the 'Data...' button is pressed, then the file 'plot1d.txt' will be created in the current working directory. It should contains tabulated columns of X, Y data array. A user has the option of save it as a permanent file through the reanme_dialog.

If any other intermediate report text file to be displayed by plot1d, the user can use the keyword REPORT='Rptname' to add 'Rptname...' report button.

Both the 'Print' and 'PS Plot' buttons will save the POSTSCRIPT file 'idl.ps' and send the PS plot to the default or selected printer.

plot1DSetup Dialog

Popup the plot1dSetup dialog. Different buttons or fields apply to different type of plot options. They are group as below:

Plot Region

The initial drawing area for PLOT1D is 350x350 pixels. The X margin is counted in number of characters, the Y margin is counted in number of character lines. The initial xmargin=[10,3], ymargin=[5,3] are used in PLOT1D.
X Size - Field to specify drawing area width in pixels, default 350
Y Size - Field to specify drawing area height in pixels, default 350

Margins: - Increase or decrease boundary margins
	Zoom out   - Increase boundary margins
	Zoom in    - Decrease boundary margins

Plot Style

Xstyle: - Droplist to set the X axis plot style 1 - Force exact axis range, default 2 - Extend axis range 4 - Suppress entire axis 8 - Suppress box style axis 16 - Inhibit setting Y axis mininum to 0 Ystyle: - Droplist to set the Y axis plot style 1 - Force exact axis range, default 2 - Extend axis range 4 - Suppress entire axis 8 - Suppress box style axis 16 - Inhibit setting Y axis mininum to 0 CharSize: - Droplist to set the character size of comment lines 1 - set charsize to 1, default 2 - set charsize to 2 AutoScl/UserScl - Auto scaled or user scaled axes, default AutoScl Thickn - Slider to set line thinkness, default 2 Linestyle: - Droplist to set line style Off - Solid line only, default On - Dash, dot ... line styles Grid: - Droplist to set grid line on/off, default off Off - Suppress grid line, default On - Show grid line Stamp: - Droplist to show timestamp Off - Suppress timestamp, default On - Show timestamp Y+: - Droplist to set 10% Y axis expansion if AutoScl is on Off - Suppress Y axis expansion On - Expand Y axis 10% , default Bg: - Droplist to set background color Blk - Set background to black Wht - Set background to white, default

UserScl Ranges

Initial user scaled plot ranges are automatically calculated from the input data array X, and Y. The following four text widgets are active only if the 'UserScl' is set. At the user scaled plot mode, a user can modify these fields to tailor the X and Y plot ranges.
XMin: - Field to set X axis minimum value
XMax: - Field to set X axis maximum value
YMin: - Field to set Y axis minimum value
YMax: - Field to set Y axis maximum value

Plot Titles

The plot titles consists of three text widgets: Title, XTitle, and Yitle. To modify the text field by highlighting the text field and typing directly in the field. To finish the modification of the field text by pressing the Return key.
Title  - Field to set plot title
XTitle - Field to set X axis plot title
YTitle - Field to set Y axis plot title

Select Curves Widgets

The select curves dialog box allows the user to select the curves to be plotted. The default setting is every curve in the Y data array is included in the plot.
All     - Toggle button for all curves from Y array
Help... - Help info about multiple selection list
Even #  - Select even number of curves from Y array
Odd #   - Select odd number of curves from Y array
List    - Scroll curve list for multiple selection
Press the toggle button 'All' selects all curves or just first curve. Click any item # from the scroll list just selects that curve. Click a # from the list while hold down CNTL key adds the item to the selected list. Click a # from the list while hold down SHIFT key adds all the items between the current and last clicks.

Comment Text Widget

The scroll text widget contains the comment lines associated with the plot. At most 10 comment lines can be recorded on a plot. This text area is modifiable by the user by directly type into the text window. The plot area will be updated with the new scroll comment text lines as long as the Return key is pressed.

Addtional Options

Comment: - Droplist to set comment on/off
	Off - Suppress the comment lines
	On  - Draw the comment lines on the plot, default

Legend: - Droplist to set legend on/off
	Off - Suppress the legend drawing, default 
	On  - Draw the curve legend 

Xlog: - Droplist to set X axis logarithm
	Off - Linear X axis, default
	On  - Logarithm X axis 

Ylog: - Droplist to set Y axis logarithm
	Off - Linear Y axis, default
	On  - Logarithm Y axis 

Symb: - Droplist to set symbol on/off
	Off - Supress symbol plot, default
	On  - Plot symbol at data point

Close - Button to close the plot1dSetup dialog

Legend Widgets

The legend widgets show up only if the 'Legend:' droplist is set to 'On'. They consists of legend location widgets 'XLegend', and 'YLegend', and legend strings widget 'LegendStr'. The 'XLegend', and 'YLegend' specifies the normalized location of the first line of the legend block.
XLegend    - Slider to set normalized X location for legend strings
YLegend    - Slider to set normalized Y location for legend strings
LegendStr: - Text widget to show legend strings of selected curves 
Drawing the legend strings with the curves is meaningful only if a few curves are plotted. The defualt legend string is composed of 'curve'+'#'. To modify the legend string by highlighting the string and typing directly on the string and finished with the press of the Return key.

Analysis Tools

Calc Statistics

For each data curve selected, the 'STATISTIC...' button provides the feature of simple statistic calculation. For each curve the following calculated approximation is provided:
	Peak   X=...  Y=...  < X Position at Peak Y>
	H-Peak Y=...         < Half Value of Peak Y>
	Centroid  ...        < X position of Centroid>
	FWHM      ...        < Full-Width-Half-Maximum at the Peak>
	Mean         = ...   < Mean of data points>
	Standard Dev = ...   < Standard Deviation of data >
	Mean Abs Dev = ...   < Mean Absolute Deviation of data >
	Variance     = ...   < Variance of data >
	Skewness     = ...   < Skewness of data >
	Kurtosis     = ...   < Kurtosis of data >
	

Calc FWHM of Data

The 'FWHM...' button provides the feature of calculating the tentative Full-Width-Half-Maximum values for all selected curves. A 1D plot window of the curve plus the FWHM line are plotted, the possible values of FWHM are also plotted on the plot, a user has to examine the graph and values to verify which set is the real FWHM value. Since the real curve data may behave quite randomly, it is possilbe there is no FWHM existing for the picked data curve.

Since each curve has it's own FWHM window, if more than 10 curves selected only the first 10 selected curves will pop up. A user can use the SelectCurves list widget to pick different curves to be examined.

There is a 'fwhm.rpt...' button to access the current fwhm report. The temp file 'fwhm.rpt' is used for storing the detailed data information. Since all FWHM windows share the same report filename, therefore only the most current FWHM calculation is accessible thru this button. If user want to view detail fwhm report, one curve should be picked at a time.

Calc FWHM of Data Slope

This feature is essentially the same as the feature of 'FWHM...' discussed above. The 'FWHM DY/DX...' button provides the feature of calculating the derivatives of the data curve first and then calculating the corresponding Full-Width-Half-Maximum values.

Curve Fittings

The FITTING... button provide the feature of accessing various fitting functions avalable within the EZ_FIT package. This feature will automatically pass all the curves into ez_fit program. A user can assess any data curve and use the appropriate fitting method within the fitting package. Please refer EZ_FIT package for details about fitting user interface.