-
Notifications
You must be signed in to change notification settings - Fork 6
Expand file tree
/
Copy pathvp_help_manual.htm
More file actions
executable file
·658 lines (610 loc) · 19.4 KB
/
vp_help_manual.htm
File metadata and controls
executable file
·658 lines (610 loc) · 19.4 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
<html>
<head>
<title>viewpoints Help Manual</title>
</head>
<body text="black" bgcolor="#FFFFFE">
<a name="TOP"></a>
<center>
<h1><em>viewpoints</em> Help</h1>
</center>
<h3>Contents</h3>
<a href="#Overview">Overview</a><br>
<a href="#Data_Formats">Data Formats and Organization</a><br>
<a href="#Configuration_Files">Saving and Loading Configuration Information</a><br>
<a href="#Usage">Usage</a><br>
<a href="#Main_Menu_Bar">Main Menu Bar</a><br>
<a href="#Mouse_Gestures">Mouse Gestures</a><br>
<a href="#Control_Panels">Control Panels</a><br>
<a href="#Plot_Window_Controls">Plot Window Controls</a><br>
<a href="#Brush_Controls">Brush Controls</a><br>
<a href="#Main_Control_Panel">Main Control Panel</a><br>
<a href="#Normalization_Schemes">Normalization Schemes</a><br>
<a href="#Command_Shortcuts_In_Plot_Windows">Command Shortcuts in Plot Windows</a><br>
<a href="#Notes_And_Warnings">Notes and Warnings</a><br>
<a href="#Compatibility_Issues">Compatibility Issues</a><br>
<br>
<hr>
<a name="Overview"></a>
<h3>Overview</h3>
<p>
<em><b>Viewpoints</b></em> is a high-performance visualization and analysis
tool for large, complex, multidimensional data sets. It generates multiple
linked scatterplots (millions of points in 2D & 3D) with overplotting and
brushing. It supports histograms with dynamically adjustable binwidth. It
supports several common types of normalization (linear, logarithmic, logistic,
trimmed, etc), equalization (gaussian, uniform, etc), and rudimentary outlier
detection and forward search.
</p>
<p>
<em><b>Viewpoints</b></em> is designed to take advantage of the hardware
accelerated graphics and fast processors on modern high-end workstations and
laptops. It is highly interactive, so that most parameters are modifiable in
real time with immediate visual feedback. It allows interactive exploration
of data in 100 or more dimensions with sample counts, or the number of points,
exceeding 10e6 (up to 10e8 depending on available RAM).
</p>
<a name="Data_Formats"></a>
<h3>Data Formats and Organization</h3>
<p>
<em>Viewpoints</em> can read data from ASCII or binary files. ASCII files
consist of zero or more <em>header lines</em> (indicated by comment
characters '!#%') followed by a <em>data block</em> that consists of a line
of column labels followed by successive lines of data. The column labels
and data words can be delimited by a user-defined character. Note that the
line of column labels is <em>not</em> preceded by a comment character unless
this is specified by the user.
</p>
<p>
Binary files consist of a single record containing column information
followed by a block of binary words in column- or row-major organization.
The default is column-major organization, in which successive words
represent successive values on a row.
</p>
<p>
Data can also be read directly from the input line using the --stdin command
line option described below. This allows piping on systems that support it,
which allows the user to use a wide variety of third-party applications to
read or process different data formats such as FITS, CDF, etc.
</p>
<p>
<em><b>FITS files: </b></em>
<em>Viewpoints</em> now has limited ability to read and write FITS files.
During a read operation, <em>Viewpoints</em> will search for the first ASCII
table extension, attempt to read it, and restore the existing data if
unsuccessful. During a write operation, it will create a new file,
<em><b>overwriting and destroying any original of the same name</b></em>,
and write the data to a single ASCII table extension in that file. This
FITS i/o capability is still under development and will be expanded in
future releases!
</p>
<a name="Configuration_Files"></a>
<h3>Saving and Loading Configuration Information</h3>
<p>
<em><b>Viewpoint</b></em> can save 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. <em><b>Note that this
process does not save the actual data or selection information
itself!</b></em>
If it did, this would produce unnecessary copies 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. Saved configurations
may be reloaded with or without reading the associated data file.
</p>
<p>
<em><b>Viewpoint</b></em> can save configuration information, such as axis
and brush settings, window positions, and the name of the last input or
output data file, to a <em>'configuration file'</em> for later reuse.
This is equivalent to saving a snapshot of the work session. <em><b>Note
that this process does not save the actual data or selection information
itself!</b></em>
If it did, this could lead to unnecessary duplication of the data files.
For this reason, the user must save any new or modified data they wish to
associate with a configuration before they save that configuration.
</p>
<p>
Saved configurations can be loaded with or without reading their associated
input file. When this happens, viewpoints will attempt to use the axis
indices described in the configuration file (e.g., if the configuration
used axes 1, 2, 6, 7, and 10, viewpoints will attempt to display the
corresponding columns in the current data file).
</p>
<p>
Configuration files are saved in XML format for ease of display, but
<em><b>these are not treated as conventional XML files.</b></em>
In particular, due to limitations of the BOOST serialization library,
<em><b>the contents of these files are order dependant.</b></em>
For this reason, any attempts to edit them should be performed with extreme
caution.
</p>
<a name="Usage"></a>
<h3>Usage</h3>
<p>
When <em><b>viewpoints</b></em> is invoked from the <em><b>vp</b></em> icon,
it displays a control panel at the far right along with a 2x2 array of
linked scatter plots of default data. 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 <em>View|Restore Panels</em> command from the
main menu bar.
(WARNING: In the current version of <em><b>viewpoints</b></em>', if you
delete every plot window, bad things may happen. This will be fixed in
future releases.)
</p>
<p>
You can select and move between windows by clicking on them in the
conventional fashion. You can also select a particular plot window by
clicking on the 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 <em><b>viewpoints</b></em> resides.
Rather than attempt to describe it in detail, we encourage you to experiment.
</p>
<a name="Main_Menu_Bar"></a>
<h3>Main menu bar commands</h3>
<p>
The following commands are available from the main menu bar.
<table>
<tr>
<th align="LEFT">Command</th><th align="LEFT">Action</th>
</tr>
<tr>
<td>File|Open data file</td>
<td>Read data from an input file</td>
</tr>
<tr>
<td>File|Append more data</td>
<td>Append additional samples from an input file</td>
</tr>
<tr>
<td>File|Merge another file</td>
<td>Merge additional attributes for these samples</td>
</tr>
<tr>
<td>File|Save all data</td>
<td>Write all the current data to a file</td>
</tr>
<tr>
<td>File|Save selected data</td>
<td>Write selected data to a file file</td>
</tr>
<tr>
<td>File|Load Configuration</td>
<td>Load configuration information</td>
</tr>
<tr>
<td>File|Save Configuration</td>
<td>Save configuration information</td>
</tr>
<tr>
<td>File|Current File Name</td>
<td>Shows name of current data file</td>
</tr>
<tr>
<td>File|Clear all data</td>
<td>Clear data and replace it with a small default array</td>
</tr>
<tr>
<td>File|Quit</td>
<td>Quit</td>
</tr>
<tr>
<td>View|Add Column</td>
<td>Add a column of plot windows</td>
</tr>
<tr>
<td>View|Add Column</td>
<td>Add a column of plot windows</td>
</tr>
<tr>
<td>View|Remove Row</td>
<td>Remove a row of plot windows</td>
</tr>
<tr>
<td>View|Remove Column</td>
<td>Remove a column of plot windows</td>
</tr>
<tr>
<td>View|Reload File</td>
<td>Reload current input file</td>
</tr>
<tr>
<td>View|Restore Panels</td>
<td>Restore any deleted plot windows</td>
</tr>
<tr>
<td>View|Default Panels</td>
<td>Restore default configuration</td>
</tr>
<tr>
<td>Tools|Edit Column Labels</td>
<td>Column label editor (still under development!)</td>
</tr>
<tr>
<td>Tools|Statistics</td>
<td>Selection statistics</td>
</tr>
<tr>
<td>Tools|Options</td>
<td>Options menu</td>
</tr>
<tr>
<td>Help|Help</td>
<td>Opens a simple HELP window</td>
</tr>
<tr>
<td>Help|About</td>
<td>Information about this version</td>
</tr>
</table>
</p>
<a name="Mouse_Gestures"></a>
<h3>Mouse Gestures in plot windows:</h3>
<p>
Mouse gestures combinations have the following effects
when the window manager focus is on a plot window.
<table>
<tr>
<th align="LEFT">Action</th><th align="LEFT">Gesture</th>
</tr>
<tr>
<td>select points</td><td>left-mouse</td>
</tr>
<tr>
<td>move selection</td><td>shift + left-mouse</td>
</tr>
<tr>
<td>translate</td><td>right-mouse (opt-mouse on OSX)</td>
</tr>
<tr>
<td>scale</td><td>middle-mouse (ctl-mouse on OSX)</td>
</tr>
<tr>
<td>scale both x and y</td><td>middle-wheel</td>
</tr>
<tr>
<td>scale histogram</td><td>middle-mouse + h (ctl-mouse + h on OSX)</td>
</tr>
</table>
</p>
<a name="Control_Panels"></a>
<h3>Controls in the control panels</h3>
<p>
The control panel consists of a set of tabbed control panels for individual
<em>windows</em>, tabbed control panels for individual <em>brushes</em>,
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.
</p>
<a name="Plot_Window_Controls"></a>
<table>
<tr><td colspan="2"><b>Tabbed control panels for <em>windows</em></b></td></tr>
<tr>
<th align="LEFT">Control</th><th align="LEFT">Action</th>
</tr>
<tr>
<td>lock X, Y, or Z</td><td>Lock axis so it won't change when invoking "change axes"</td>
</tr>
<tr>
<td>plot</td><td>Attribute to be displayed in that axis</td>
</tr>
<tr>
<td>scale</td><td>Normalization scheme for that axis</td>
</tr>
<tr>
<td>offset</td><td>Offset data by +/-i points along this axis. Note that this control<br>
is a spinner rather than a slider.</td>
</tr>
<tr>
<td align="TOP">histog</td>
<td>Show histograms along that axis. 'Marginal/Selection/Conditional'<br>
corresponds to 'All points/Selected points/Fraction selected'</td>
</tr>
<tr>
<td>N bins</td><td>number (log) of histogram bins for that axis</td>
</tr>
<tr>
<td>bin ht</td><td>height of histogram bins for that axis</td>
</tr>
<tr>
<td>bkgrnd</td><td>background color (try bkg=0.5, lum2=0.2)</td>
</tr>
<tr>
<td>lumin</td><td>luminosity for all points</td>
</tr>
<tr>
<td>pntsize</td><td>default size of unselected points</td>
</tr>
<tr>
<td>scale</td><td>Scale point sizes along with axes</td>
</tr>
<tr>
<td valign="TOP">rotate</td>
<td>rotation angle in 3D about the y-axis. NOTE: to take advantage<br>
of this feature, one must first select something for the 3rd axis<br>
to display.</td>
</tr>
<tr>
<td valign="TOP">spin</td>
<td>continuous rotation about the y-axis. NOTE: to start this, you<br>
may have to give the <em>rot</em> slider a twitch.</td>
</tr>
<tr>
<td>reset view</td><td>Reset rotation and other display params</td>
</tr>
<tr>
<td>z-buffering</td><td>Use z-buffering (only for 3D plots)</td>
</tr>
<tr>
<td>blending</td><td>Blending scheme for brushes</td>
</tr>
<tr>
<td>don't clear</td><td>Don't clear selected points in this panel</td>
</tr>
<tr>
<td>points</td><td>Show data points</td>
</tr>
<tr>
<td>unselected</td><td>Show unselected data points</td>
</tr>
<tr>
<td>axes</td><td>Show axes</td>
</tr>
<tr>
<td>ticks</td><td>Show tic marks</td>
</tr>
<tr>
<td>grid</td><td>Show grid</td>
</tr>
<tr>
<td>identity</td><td>plot y vs x</td>
</tr>
<tr>
<td>sum vs. diff plot</td><td>plot (x+y) vs. (x-y)</td>
</tr>
<tr>
<td valign="TOP">rank(y|x)</td>
<td>Plot <em>x</em> vs the rank of <em>y</em> for a range about that <em>x</em>
(e.g., rank points<br>
within a sliding bin of <em>x</em>-values by their value in <em>y</em>. The width of<br>
this bin is controlled the number of histogram bins, N bins.)</td>
</tr>
<tr>
<td valign="TOP">fluc(y|x)</td>
<td>Plot <em>x</em> vs the deviation in <em>y</em> for a range about that <em>x</em>
(e.g., rank<br>
points within a sliding bin of <em>x</em>-values by their variation in <em>y</em>.)</td>
</tr>
</table>
</p>
<a name="Brush_Controls"></a>
<table>
<tr><td colspan="2"><b>Tabbed control panels for <em>brushes</em></b></td></tr>
<tr>
<th align="LEFT">Control</th><th align="LEFT">Action</th>
</tr>
<tr>
<td>size</td><td>size of this brush, in pixels</td>
</tr>
<tr>
<td>reset brush</td><td>reset this brush</td>
</tr>
<tr>
<td>alpha</td><td>point opacity</td>
</tr>
<tr>
<td>symb</td><td>symbol used by this brush</td>
</tr>
<tr>
<td>cutoff</td><td>alpha cutoff for this brush</td>
</tr>
<tr>
<td>lum1</td><td>initial luminosity for this brush</td>
</tr>
<tr>
<td>lum2</td><td>accumulated luminosity when overplotting this brush</td>
</tr>
<tr>
<td>Color Chart</td><td>Color controls for this brush</td>
</tr>
<tr>
<td>clear selection</td><td>clear successive selection for this brush</td>
</tr>
<tr>
<td>extend selection</td><td>combine successive selections with this brush</td>
</tr>
<tr>
<td>paint</td><td>'dribble paint' while dragging the selection box</td>
</tr>
</table>
</p>
<a name="Main_Control_Panel"></a>
<p>
<table>
<tr><td colspan="2"><b>Main control panel</b></td></tr>
<tr>
<th align="LEFT">Control</th><th align="LEFT">Action</th>
</tr>
<tr>
<td>show nonselected</td><td>Show/don't show unselected points in all plots</td>
</tr>
<tr>
<td>mask nonselected</td><td>Mask out unselected points in all plots</td>
</tr>
<tr>
<td>invert selection</td><td>Invert selected and nonselected points</td>
</tr>
<tr>
<td>clear selcetion</td><td>Clear all selections</td>
</tr>
<tr>
<td>kill selection</td><td>Delete all selected points and renormalize (useful after selecting outliers)</td>
</tr>
<tr>
<td>change axes</td><td>Change all (unlocked) axes in all plots. Good for browsing.</td>
</tr>
<tr>
<td>link axes</td><td>Link similar axes so they translate and scale together</td>
</tr>
<tr>
<td>defer redraw</td><td>Update selections on mouse-up only (for large data)</td>
</tr>
</table>
</p>
<a name="Normalization_Schemes"></a>
<h3>Normalization Schemes</h3>
<p>Several different normalization or scaling schemes are available.
These are chosen on a per-axis basis.
<table>
<tr>
<th align="LEFT">Scheme</th><th align="LEFT">Effect</th>
</tr>
<tr>
<td>none</td><td>show all data, center of window at median</td>
</tr>
<tr>
<td>minmax</td><td>stadard min-max scaling</td>
</tr>
<tr>
<td>zeromax</td><td>show all positive data</td>
</tr>
<tr>
<td>maxabs</td><td>show all data, center of window at data zero</td>
</tr>
<tr>
<td>trim 10<sup>-2</sup></td>
<td>Window spans 1st to 99th percentile</td>
</tr>
<tr>
<td>trim 10<sup>-3</sup></td>
<td>Window spans 0.1th to 99.9th percentile</td>
</tr>
<tr>
<td>threesigma</td><td>center of window at sample mean, window spans +/- three sigma.</td>
</tr>
<tr>
<td>log_10</td>
<td>Logarithmic axis</td>
</tr>
<tr>
<td>atan</td>
<td>Simple sigmoid</td>
</tr>
<tr>
<td>rank<br> </td>
<td>plot rank of x (instead of x)<br>(i.e. nonuniform rescaling to force uniform marginal)</td>
</tr>
<tr>
<td>partial rank </td>
<td>rank as above, but overplot similar values</td>
</tr>
<tr>
<td>gaussianize<br> </td>
<td>plot inverse of Gaussian cummulative distribution function of x<br>(i.e. nonuniform rescaling to force Gaussian marginal)</td>
</tr>
<tr>
<td>randomize </td>
<td>Randomize</td>
</tr>
</table>
</p>
<a name="Command_Shortcuts_In_Plot_Windows"></a>
<h3>Keys & Buttons in plot windows:</h3>
<p>
The following keyboard shortcuts can be used
while the window manager focus is on a plot window:
<table>
<tr>
<th align="LEFT">Action</th><th align="LEFT">Key</th>
</tr>
<tr>
<td>new selection</td><td>left-mouse</td>
</tr>
<tr>
<td>move selection</td><td>left-mouse + shift</td>
</tr>
<tr>
<td>invert selection</td><td>i</td>
</tr>
<tr>
<td>display deselected</td><td>d</td>
</tr>
<tr>
<td>clear selection</td><td>c</td>
</tr>
<tr>
<td>search x-axis strings </td><td>F</td>
</tr>
<tr>
<td>search y-axis strings </td><td>f</td>
</tr>
<tr>
<td>kill selected points</td><td>x</td>
</tr>
<tr>
<td>reset view</td><td>r</td>
</tr>
<tr>
<td>quit</td><td>q</td>
</tr>
</table>
</p>
<a name="Notes_And_Warnings"></a>
<h3>Notes and warnings:</h3>
<p>
The current release of the <em><b>Viewpoints</b></em> package
(version 2.2.4, build 258)
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.
</p>
<p>
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.
<p>
2) The Load and Save Configuration commands are a comparatively new feature.
For this reason, they are still evolving. While every effort has been made
to ensure that old configuration files are upward-compatible with new
versions of viewpoints, it is advisable to resave a new version of these
files if the package warns you to do so.
</p>
<p>
3) The FITS file i/o capability is new, and is not yet guaranteed to work on
every system. It will undergo substantial improvement in future releases.
</p>
<p>
4) The Edit Column Labels tool is also a new feature, and is not guaranteed
against unexpected behavior. In the current release, it can only
delete labels. For ASCII files, column labels can be renamed 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.
</p>
<a name="Compatibility_Issues"></a>
<p>
<b>Compatibility:</b> The Linux version has been tested on Fedora Core 4
while the MacOS versions have been tested on MacOS 10.4.8 on G4, G5 and
Intel macs. The Windows version should run on any recent system with the
necessary functionality from OpenGL 1.2 through 1.6. It will not run on
older systems that are restricted to OpenGL 1.1.
</p>
<p>
Please note that <b><em>Viewpoints</em> (vp)</b> is in development.
While each version is tested before release to make certain
that it will function properly (or fail gracefully in the event
something goes wrong), we are continuing to updated and modify the
package and add features in response to experience, suggestions, and
the requirements of the user community. For detailed information
about this release see the README file. If you have any comments or
suggestions, please feel free to contact the project team:
<a href="mailto:creon.levit@nasa.gov">Creon Levit</a> or
<a href="mailto:Paul.R.Gazis@nasa.gov">Paul R. Gazis</a>.
</p>
<p>
This project was funded by a grant from NASA's
Applied Information Systems Research Program.
If you find this package useful in your research, we would appreciate
it if you could acknowledge this project in the relevant publications.
Thank you.
</p>
</body>
</html>