Version 2, last updated by creon levit at May 10 20:26 2008 UTC
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=<integer> [shortcut: -s <int>] (default 1)
Specifies the number of lines that will be assigned to the header block
in the absence of comment characters.
--npoints=<integer> [shortcut: -n <int>] (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=<integer> [shortcut: -r <int>] (default 2)
Specifies the number of rows of scatterplots
--cols=<integer> [shortcut: -c <int>] (default 2)
Specifies the number of columns of scatterplots
--input_file=<filespec> [shortcut: -i <filespec>]
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=<filespec> [shortcut: -C <filespec>]
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 <int>]
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=<char>]
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 <number>]
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