discern (1U) - MidasPlus delegate for visualizing multidimensional data

DISCERN(1U)CSF

NAME

discern - MidasPlus delegate for visualizing multidimensional data

MIDAS COMMAND SYNTAX

Command: delegate start disc discern

DESCRIPTION

Discern is a MidasPlus delegate for qualitatively visualizing three-dimensional points with additional associated values. Discern generates MIDAS object files that represent data points as ellipsoids. The center of the ellipsoid represents the Cartesian coordinates of a data point. The color, size, and lengths of the major and minor axes of the ellipsoids represent the additional values. The ellipsoids are displayed using longitudinal and latitudinal lines. By varying the number of these lines, one can get different representations. For example, using 3 longitudinal and 1 latitudinal lines yields trigonal bipyramids, while 5 and 1 yields pentagonal bipyramids. This is most useful for distinguishing data points from different data files (all data points from a given data file are displayed using the same ellipsoid representation).

The first application of discern was to display a set of points with both a calculated and an estimated potential. The ellipsoids were colored from blue to red corresponding to the calculated potential values. The sizes and axes lengths of the ellipsoids were proportional to the difference squared and ratio of the calculated and estimated potential values, respectively. This display clearly showed the potential form, and highlighted the areas where the estimated and calculated values differed significantly. In addition, it also showed whether the estimated value was too low or too high. The discern commands for setting up this display are given in the EXAMPLES section below.

     Discern is a program designed to run in conjunction with
     MIDAS using the MidasPlus delegate mechanism.  The standard
     way that discern is invoked is for the user to start a MIDAS
     session, and issue the MIDAS command
          delegate start disc discern
     which runs discern and tells MIDAS to pass commands
     beginning with disc through to discern for further
     processing.  The commands that discern can handle are
     described below.

COMMANDS

     When discern is acting as a delegate for MIDAS (as above),
     the user can give it commands by typing
          disc discern_command
     in the MIDAS command window.  The list of commands is given
     below.  Other than open and use, all discern commands are
     applied to a single selected model (there can only be one
     selected model at any given time).

open [ model_number ] datafile_name: Open the file datafile_name and display it in MIDAS as model model_number . If model_number is absent, use the lowest available model number. This command also makes the newly opened model the selected model.

use model_number: Make model model_number the selected model.

symbol [ nside ns ] [ nlayer nl ] [ aspect na ]: Redisplay the selected model using ellipsoids with ns longitudinal lines, nl latitudinal lines, with the ellipsoid compressed length-to-width by a factor of na. Any of the three specifications may be omitted, in which case the value will remain unchanged. For a newly opened object, the default values for ns, nl, and na are 6, 1 and 1.0 respectively.

property name [ formula ]: Define or list a property for use with the size, major, minor, and color commands. If formula is omitted, the formula for computing property name is listed; otherwise, the formula will be used for computing property name (any previously defined formula is discarded). The formula consists of data columns, the usual arithmetic operators, and simple function calls. Data columns are introduced by the ``$'' character, followed by the column number (columns are numbered starting from one, not zero). Arithmetic operators include ``+,'' ``-,'' ``/,'' ``*,'' and ``^'' which correspond to addition, subtraction, division, multiplication, and exponentiation respectively. The precedence of the operators is the normal arithmetic one, and parentheses may be used to override. The list of supported functions is: sqrt (square root), sin (sine), cos (cosine), acos (arccosine), exp (exponential), log (natural logarithm), and abs (absolute value). An example of a property command is property diffsq ($4 - $5) ^ 2 Properties with numeric names are predefined to correspond to data columns (e.g., ``1'' corresponds to data column 1).

size keyword-value-pair ...

          major keyword-value-pair ...
          minor keyword-value-pair ...
          color keyword-value-pair ...
               These commands redraw the selected model using
               different display parameters based on the
               keyword-value-pair arguments.  Major and minor are
               the axes lengths of the ellipsoid; size is a scale
               factor applied to both axes; color is the color of
               the ellipsoid.  The supported keywords are listed
               below.

property name: Specifies that the display parameter will be interpolated using values computed with property name. In the special case where name is none, the default display parameter will be used.

bmin value: Specifies the lower bound for the data values. If this keyword is not used, the minimum value for the specified property is used. Data points whose value is below the given lower bound are not displayed.

bmax value: Specifies the upper bound for the data values. If this keyword is not used, the maximum value for the specified property is used. Data points whose value is above the given upper bound are not displayed.

min param: Specifies the display parameter associated with the lower bound of the data values. For the color command, the value is any string corresponding to a MIDAS color; for other commands, the value is a floating point number.

max param: Specifies the display parameter associated with the upper bound of the data values. For the color command, the value is any string corresponding to a MIDAS color; for other commands, the value is a floating point number.

state: Report the current state associated with the display parameter. If no property has been associated with the parameter, the property field is reported as none.

               The display parameter associated with a data point
               is linearly interpolated using the following
               formulae:
                    fraction = (data_value - lower_bound) /
                    (upper_bound - lower_bound)
                    parameter = min_param + fraction * (max_param
                    - min_param)
               Note that min_param may be larger than max_param,
               in which case the display parameter is inversely
               proportional to the data value.  The ellipsoid
               axes' lengths are computed in angstroms; size is
               dimensionless; and color is interpolated in hue-
               saturation-value (HSV) space by MIDAS.  For a
               newly opened object, the display parameters are 1
               (for size, major, and minor) and white (for
               color), unless overridden in the data file.

axes [ x xname ] [ y yname ] [ z zname ]: Define the property values to use for Cartesian coordinates. Any of the axis specifications may be omitted, in which case the previously defined property will be used. For a newly opened object, the xname, yname, and zname properties are ``1,'' ``2,'' and ``3'' respectively (i.e., the first three columns are the Cartesian coordinates).

direction [ x xname ] [ y yname ] [ z zname ]: Define the property values to use for the direction of ellipsoid major axes. For a newly opened object, if the data file contains the directional property (see below), the xname, yname, and zname properties are ``4,'' ``5,'' and ``6'' respectively (i.e., the three columns after the Cartesian coordinates are the direction vector). If the data file does not contain the directional property, then all ellipsoids will be oriented with their major axes parallel to the z axis. Any of the axis specifications may be omitted, in which case the previously defined property is used. If no property has been defined for any of the three axes, the ellipsoids will remain parallel to the z axis.

FILE FORMAT

The format of the data file that discern will read consists of a series of property descriptions followed by the data values. The following property descriptions are mandatory:

field number: Each data point has number values associated with it. This includes the three Cartesian coordinates, so the minimum value for number is 3.

data: This must be the last property description. Subsequent lines in the file are treated as data points.

The following property descriptions are optional:

count number: There are approximately number data points. This value is only advisory, and discern will only use it to guide memory allocation strategy.

nside number: Ellipsoids will be drawn with number longitudinal lines. The default value of this property description is 5. It must be at least 3.

nlayer number: Ellipsoids will be drawn with number latitudinal lines. The default value of this property description is 1. It must be at least 1 and odd.

size number: If the user does not issue a size command, ellipsoid axes lengths will be scaled by a factor of number. The default value of this property description is 1.

directional: Normally, ellipsoids are drawn with the major axis parallel to the z axis. This property description specifies that for each data point, the three columns following the initial Cartesian coordinates form a direction vector for the major axis of the ellipsoid.

Each line following the property descriptions is treated as a single data point. Each data point is represented as a list of floating point numbers. The first three items in the list form the initial Cartesian coordinates for the data point (this may be changed using the axes command [see above]). There must be the same number of elements in the list as the number specified by the field property description.

EXAMPLES

The following is a sample data file:

field	7 size 0.2
nlayer	3 directional data 0 0 0 1.0 2.0 1.0 2.0 1 0 0 5.0 4.0 1.0 0.8 0 1 0 2.5 3.0 0.25 1.2

The following are MIDAS commands that may be used to display the data file as described in the DESCRIPTION section above.

disc open: discern.data Open the data file and display it.

disc color property 4 min blue max: red Color the data points based on column 4, and make the minimum value correspond to blue and maximum to red. Intermediate values will map to colors ranging from blue to cyan through magenta to red.

disc size property 5 min: 0.1 max 0.5 Make the ellipsoid size correspond to column 5, and map the minimum value to 0.1 angstrom and maximum to 0.5 angstrom.

BUGS

There is no way to change the direction vector from columns 4, 5, and 6.

AUTHOR

Conrad Huang, Computer Graphics Laboratory, UCSF

Chris Bayly, UCSF