viewpoints -- Fast interactive linked plotting of large multivariate data sets. Version: 2.0.4 (Build 218) Date: 05 Feb 2008 Overview: The archives on this site contains the executable, documentation, a sample data file with examples, and any dynamic link libraries (dlls) that may be required for the 'viewpoints' (vp) package for Linux, Mac OSX, and Windows. The contents of these archives are listed below: File Comments ----------------------------------------------------------------- README This documentation file vp.exe viewpoints executable (MS windows only) vp.ico viewpoints icon (MS windows only) vp viewpoints executable (linux only) viewpoints.app application bundle (Mac OS X only, see below) vp_help_manual.htm HTML help manual sampledata.txt sample data libgsl.dll DLL library for GSL (Windows only) libgslcblas.dll DLL for GSL CBLAS (Windows only) OglExt.dll DLL for OGL Extension Library (Windows only) Installation: Unpack these files into a target directory, then either click on the 'vp' icon or run the code from the command line as described below. Data Organization and Format: Viewpoints can read and write data from ASCII or binary files. ASCII files consist of zero of more header lines, indicated by comment characters '!#&%', followed by a data block. The data block is assumed to consist of a line of column labels followed by successive lines of data. Words in the data block can be delimited by whitespace or some user-defined character. Binary files conists of a line of column label information followed by a block of binary data in row- or column-major format. Note that the line of column labels must NOT be preceded by a comment character unless they are specified by the user to be part of the header. Configuration Files: Viewpoints can save basic configuration information, such as axis settings, window positions, and the name of the last input or output data file, to a configuration file for later reuse. Note that this process does not save the actual data or selection information itself! If it did, this could lead to unnecessary duplication of the data files. The user must save any new or modified data they wish to associate with a configuration before they save that configuration. Usage: In its current form (Version 2.0.2, build 208) 'viewpoints' is run either by clicking on the 'vp' icon or from the command line in the directory in which it has been installed or to which a path is available. When viewpoints is run from the icon, it will come up with an array of default data. When it is run from the command line, the user must specify the input data file explicitly. Apple OS X: to run viewpoints from the command line, you will probably want to create a shell alias to the actual executable, which is located inside the application bundle. For example, if you dragged the viewpoints application "viewpoints.app" to your /Applications folder, then you will probably want to add the following to your .cshrc file (assuming you are using csh or tcsh as your shell): alias vp /Applications/viewpoints.app/Contents/MacOS/viewpoints A symbolic link will not work. Use a shell alias. If you don't care about running it from the command line, ignore the above. You can just double-click on the viewpoints.app icon to start it up. The calling sequence for the command line version is: vp [optional arguments] inputfile the optional arguments are: --format=ascii (default) [shortcut: -f a] Read an ASCII input file that consists of a header block followed by a data block. Lines in the header block are indicated by one the comment characters '!', '#', or '%'. In the absence of comment characters, the header block is assumed to consist of a number of lines specified by the '--skip_header' command below, with a default value of 0 lines. The first line of the data block contains the attribute names. By default, this is not preceeded by a comment character and is delimited by whitespace, but this can be controlled from the main menu or by command line arguments (see --delimiter, below). Successive lines in the data block contain the numeric attribute values for successive samples, delimited by the delimiter character. See the file "sampledata.txt" for an example. --format=binary [shortcut: -f b] Read a binary input file. The first record of this file consists of a line of ASCII attribute names, whitespace delimited, ending with newline (\n). This is followed by a contiguous block that contains a table of binary floating point values. --skip_header= [shortcut: -s ] (default 1) Specifies the number of lines that will be assigned to the header block in the absence of comment characters. --npoints= [shortcut: -n ] (default min(all,2000000)) Specifies the number of samples (records or rows in the data block of an ASCII file) to read. End of file will terminate read. Note the default: if you want to read more than 2 million samples, you must say so using this argument. --rows= [shortcut: -r ] (default 2) Specifies the number of rows of scatterplots --cols= [shortcut: -c ] (default 2) Specifies the number of columns of scatterplots --input_file= [shortcut: -i ] Filespec of the input file. NOTE: if this parameter is not specified, the code will assume that the final token in the command line is the input filespec. --config_file= [shortcut: -C ] Filespec of a saved configuration file. NOTE: If this parameter is specified, it will override any input filespec. --borderless [shortcut: -b] Attempt to maximize plot windows' usable area by removing window manager decorations. Note: this seems to cause problems with keyboard shortcuts in plot windows under Mac OSX. --help [shortcut: -h] Print a short help message. --ordering={rowmajor,columnmajor} ordering for binary data, default=columnmajor --nvars [shortcut -v ] The number of variables (attributes) per sample is automatically determined from the last header line in an ascii input file, or from the first line of a column-major binary file. This option is only for row major binary data, in which case one must also specfiy --npoints above. --delimiter [shortcut -d=] interpret char as field separator, default is whitespace. Delimiter characters can be escaped using the standard c-language convetions. This delimiter is also used in the header to delimit variable (attribute) names. e.g. --delimiter=, for comma delimited or --delimter=\t for tab delimited --missing_values [shortcut -M ] set the value of any unreadable, nonnumeric, empty, or missing values to NUMBER, default=0.0. NOTE: if you use the default delimiter (whitespace) then lines with one or more missing values are skipped and so this option has no effect. --no_vbo [shortcut -B] don't use openGL vertex buffer objects. Useful if you have an older graphics card or if the graphics are inconsistent or very slow. May be useful if you are attempting to look at huge datasets. --verbose [shortcut -O] print verbose output with additional diagnostics --version [shortcut -V] print version information and then exit. --expert [shortcut -x] enable expert mode, that bypasses confirmations and allows reads from stdin, etc. --help [shortcut -h] print out brief usage message and then exit. When 'viewpoints' is invoked, it will read the input file, then display a control panel along with an 'r' x 'c' array of linked scatter plots. These windows can be moved and resized in the conventional fashion. If you delete some window by accident, you can restore every window using the 'reload plots' command. (If you delete every plot window, the program may crash). You can also select a particular plot by giving it the mouse focus directly, or by clicking on its associated tab in the control panel window. Within different windows, you can use the mouse to select portions of the data set. It is in this feature that the power of 'viewpoints' resides. Rather than attempt to describe it in detail,we encourage you to experiment! Main menu bar command action -------------------- ---------- File|Open data file Read data from an input file File|Append more data Append additional samples to the existing data File|Merge another file Merge additional attributes for these samples File|Write ASCII file Write all the current data as an ASCII file File|Save all data Write all data File|Save selected data Write only the currently selected data File|Load Configuration Load basic configuration information File|Save Configuration Save basic configuration information File|Quit Quit View|Add Row Add a row of plot windows View|Add Column Add a column of plot windows View|Remove Row Remove a row of plot windows View|Remove Column Remove a column of plot windows View|Reload File Reload the existing data file View|Restore Panels Restore deleted plot windows View|Default Panels Restore the default polt window configuration Help|Help Opens a simple HELP window Help|About Information about this version Buttons and (keyboard shortcuts when a plot window has mouse focus): action key -------------------- ---------- new selection left-mouse move selection left-mouse + shift invert selection i display deselected d clear selection c kill selected points x reset view r quit q Mouse Gestures (with the cursor in one of plot windows): action gesture -------------------- ---------- select points left-mouse translate right-mouse (opt-mouse in OSX) scale middle-mouse (ctl-mouse in OSX) scale histogram middle-mouse + h (ctl-mouse + h in OSX) Controls in the control panels: The control panel consists of a set of tabbed control panels for individual windows, tabbed control panels for individual brushes, and a main control panel for the entire array of panels. For the most part, these controls should be intuitive. Some of these controls are described below: Tabbed control panels for individual windows: control action -------------------- ---------- X, Y, and Z axis Attribute to be displayed in that axis locked Lock an axis so it won't change scale Normalization scheme for that axis offset Offset data by +/-i points along this axis. Note that this is a spinner rather than a slider. histog Show histograms along that axis. 'Marginal/Selection/Conditional' corresponds to 'All points/Selected points/Fraction selected' N bins number (log) of histogram bins for that axis bin ht height of histogram bins for that axis Bkg background color (try bkg=0.5, lum2=0.2) lum successive brightness increase for overplotting psize default size of unselected points scale points Scale point sizes along with axes rot rotation angle in 3D about the y-axis. NOTE: to take advantage of this feature one must first select something for the Z-axis to display. spin continuous rotation about the y-axis. NOTE: to start this, you may have to give the rot slider a twitch. reset view Reset rotation and other display params z-buffering Use z-buffering (only for 3D plots) blending Blending scheme for brushes don't clear Don't clear selected points in this panel points Show data points unselected Show unselected data points axes Show axes labels Show axes labels scales Show axes scales ticks Show tic marks grid Show grid identity plot y vs x sum vs. diff plot plot (x+y) vs. (x-y) rank(y|x) Plot x vs the rank of y for a range about that x (e.g., rank points within a sliding bin of x-values by their value in y. The width of this bin is controlled the number of histogram bins, N bins.) fluc(y|x) Plot x vs the deviation in y for a range about that x (e.g., rank points within a sliding bin of x-values by their variation in y.) Tabbed control panels for individual brushes control action -------------------- ---------- size size of this brush, in pixels sym symbol used by this brush Alpha point opacity lum1 successive brightness increase for overplotting lum2 successive brightness increase for overplotting Color chart Color controls for this brush extend selection combine successive selections with this brush clear selection clear successive selection for this brush reset brush reset this brush Main control panel control action -------------------- ---------- show nonselected Show unselected points invert selection Invert selected and nonselected points clear selcetion Clear selection kill selection Delete all selected points unselected color Chose color of unselected points change axes Change all (unlocked) axes link axes Link similar axes Normalization schemes (per axis) Data can be normalized in several different ways. The normalization scheme for any axis can be selected from the appropriate menu. type description -------------------- ----------- none show all data, center of window at median minmax window spans maimimum to maximum. zeromax show all positive data maxabs show all data, center the window at zero trim 10^-2 window spans the 1st-99th percentile trim 10^-3 window spans the 0.1th-99.9th percentile threesigma center window at sample mean so that window spans +/- three sigma. log_10 Logarithmic axis atan Simple sigmoid rank plot rank (order) of x instead of x -- i.e. nonuniform rescaling to force a uniform marginal partial rank as 'rank' above, but overplot identical values gaussianize plot inverse of the Gaussian cummulative distribution function of x -- i.e. nonuniform rescaling to force a uniform marginal randomize Randomize Notes and warnings: The current release of the 'viewpoints' package (version 2.0.4, build 218) is still a development version. While every effort has been make to ensure that it will work -- or fail gracefully if it doesn't -- it still has many rough edges. Some of these are described below. These issues will all be addressed in future releases. 1) If you drag a window over the main control panel, the main control panel may need to be refreshed. This can be accomplished by resizing it. 2) There is, as yet, no 'print' command. Needless to say, this capability will be added as soon as possible! 3) The Load and Save Configuration commands are a comparatively new feature, and save basic session information. They may not work on every system. Also, there is not, as yet, any guarantee that old configuration files will be upward-compatible with new versions of viewpoints. 4) The Edit Column Labels tool is also a new feature, and is not guaranteed to preserve axis or scaling information. In the current release, it can only delete labels. Column labels of ASCII files can be renamed via by using an editor in a conventional fashion. Small binary files can be saved to ASCII and edited. For large binary files, it is possible, with difficulty, to rename labels by saving a small portion of the file as ASCII, editing this, reloading it, and appending the remainding portion of the original binary file. Please send any questions, bug reports, feature requests, and/or praise to: Creon Levit at creon.levit@nasa.gov or Paul Gazis at Paul.R.Gazis@nasa.gov