vwhere

 SYNOPSIS

   A graphical version of the S-Lang where command, providing a simple
   yet powerful mechanism for visually exploring and filtering datasets.

 USAGE

	Array_Type = vwhere( structure | 1Darray, 1Darray, ...)

   Input to vwhere should contain at least 2 numeric vectors, all of equal
   length.  These vectors should be passed in the form of either a comma-
   separated list of 1-D arrays or a single structure containing two or
   more fields.  Structure fields will be ignored if they are non-numeric
   in type, or of unequal length, or have names prefixed with an underscore.

 PLOTTING

   Filtering in vwhere amounts to manipulating regions of interest on
   plots generated from the input dataset.  The number of plots that
   may be created, and the number of region filters applied to each,
   is effectively unlimited.
   
   Plots are generated from the axis expression window, which contains
   two editable text fields (one for each of the X and Y axes) whose
   contents respectively default to the names of the first and second input
   vectors.  In general each axis expression may contain any valid S-Lang
   statement, even calls to C or FORTRAN functions imported from external
   modules.  The only constraints upon an axis expression are that it
   be less than 256 characters long, and (when evaluated) generates a
   numeric vector equal in length to that of the input dataset.

   Plots may also be deleted, panned, and zoomed -- providing a rapid
   means of data exploration -- as well as customized through a number
   of preferences.

   In contrast with command line tools, users may find visually interactive
   construction of complex, multi-dimensional filters to be more intuitive,
   as well as faster, cleaner, and more powerful.  Filtering may be performed
   upon either in-memory arrays or disk files, with no filter syntax required,
   multiple iterations through disk files are avoided, no file litter is
   created while one experiments with filter ranges, filters may be applied
   incrementally (instead of all at once), as well as combined with arbitrary
   S-Lang, C, or FORTRAN numerical functions.

 REGION FILTERS

   The following region filters may be applied after visualizing a plot:

	rectangle		click MouseButton1, then drag mouse to
				define bounding box

	ellipse  		same as rectangle

	polygon  		click MouseButton1 to add vertices
				click MouseButton2 to close polygon
				click MouseButton3 to cancel

   Filters may be deleted (by hitting the BACKSPACE or DELETE key),
   moved, or resized after initial placement.
   
   Points on or within the boundary of at least one region filter are
   considered "selected," and will be drawn in the foreground line
   style and symbol color.  All other points are considered "filtered"
   or "excluded," and will be drawn, when requested, in the background
   line style and color.  Line styles and symbol colors may be adjusted
   from within the preferences dialogs.

 INCREMENTAL FILTERING

   One of the more powerful features of vwhere is the incremental manner in
   which the dataset may be filtered.  In contrast with file in / file out
   filtering method offered by command line tools, which applies the entire
   set of filters to the entire input dataset -- conceptually in just one
   pass -- vwhere provides the option of filtering some axes of the dataset,
   by applying region filters to currently displayed plots, prior to
   filtering other axes.
   
   This provides a powerful mechanism for exploring relationships within
   your data, and can also speed up subsequent plotting and filtering.
   When incremental filtering is on (the default) only points selected by
   the current filters will be colored in subsequent plots.  Filtered points
   will either be drawn grayed out on subsequent plots (the default) or not
   drawn at all (a faster option for large datasets), per the current
   preferences.  The next section describes how filters are incrementally
   combined.

 RETURN VALUE

   The vwhere guilet return value matches that of the native S-Lang where
   function: an array of numbers, each representing an index into the
   vector(s) given to the comparison operator(s) of the where expression.
   These indices may then be applied to related datasets, or used to create
   filtered output files, etcetera.

   Filters applied to a single plot are unioned to form the set of points
   selected by that plot.  If only one plot is visualized then this set
   completely specifies the indices returned by vwhere.  When multiple plots
   are visualized the incremental selections from each are either intersected
   (the default) or unioned (when chosen in the preferences dialog) to
   generate the aggregate set of selected points.

   If zero region filters have been applied the entire input dataset will be
   returned.  Dismissing the guilet by any means other than pressing "Done"
   in the plots window will return the empty dataset.

 EXAMPLES

   The following explores the curves y = x^2 and z = x^3 over [1,100] :

		result = vwhere([1:100], [1:100]^2, [1:100]^3);

   The following explores a hypothetical binary table read from disk:

		tab = your_favorite_FITS_file_reader ("table.fits");
		result = vwhere(tab);

   If the tab structure contained CCD_ID, PHA, and TIME fields, then valid
   expressions by which two plots could generated from this table might be:

	PLOT 1:
			X :	  ccd_id
			Y :	  pha
	PLOT 2:
			X :	  time
			Y :	  log10(pha)

 SEE ALSO

   where
