table_to_uniform_field

Synopsis

maps the data in an array of DBcolumn to a uniform field.

Input Ports

Parameters

Output Ports

Description

Table_to_Uniform_Field maps the data in an array of DBcolumn to a 1D, 2D, or 3D uniform field. The data to be mapped is usually query data returned by DBquery or Query.

You typically use uniform fields to represent regular data whose records form continuous 1D, 2D, or 3D uniformly spaced arrays. You can visualize a uniform field in many ways; for example, city_plot, ribbon_plot, surface_plot, contour, isosurface, or isoline.

Table_to_Uniform_Field provides a number of parameter values that control various aspects of the mapping.

Axis parameters

You use the X Axis, Y Axis, and Z Axis selection menus to select one, two, or three columns that will serve as the coordinate axes of the resulting uniform field. The number of dimensions in the output field will be one, two, or three, respectively. You use the On toggle associated with each menu to turn on the corresponding axis.

You use the Axis Setup menu to specify a column whose axis parameters you want to set. These parameter values are used when you select the column as a coordinate axis. The following axis parameters are available:

• Discrete
• Min value
• Max value
• Bin size
• normalize axis
• set labels
• index labels
• label step

The Discrete parameter specifies whether the coordinates along an axis are discrete or continuous.

If you select Discrete, discrete coordinates are used. They are the indices of an array of the unique values in a column. For example, a column that contains the values 1, 2, 3, 2, 3, 2, 10, and 20 has five unique values (1, 2, 3, 10, and 20) and therefore five indices: 0, 1, 2, 3, and 4. These indices serve as the discrete coordinates.

Discrete coordinates are particularly useful with numeric data such as area codes or with string values. For example, if a column contains the string values "John", "Bob", "Bob", "John", "Bill", the coordinates are 0, 1, and 2, where 0 is the index of "John", 1 is the index of "Bob", and 2 is the index of "Bill".

With discrete coordinates, the dimensionality of the coordinate array is always the number of unique values in the column.

If you deselect Discrete, continuous coordinates are used. They are calculated based on the values that you supply for the Min value, Max value, and Bin size parameters. The dimensionality of the coordinate array is the number of bins between Min value and Max value, and the value of the coordinates are the centers of consecutive bins.

Suppose that the values of Min value, Max value, and Bin size are 0.00, 4.00, and 1.00, respectively. The following figure illustrates how the coordinates are calculated:

 



With parameter values as noted, there are four bins from Min value to Max value, and the coordinates are 0.50, 1.50, 2.50, and 3.50.

With continuous coordinates, the data values input to Table_to_Uniform_Field are binned ; that is, they are put into the bins thus created. Data values that fall on a bin boundary are put into the immediately lower bin. In the previous figure, for example, a data value of 2.00 is put into the bin whose coordinate is 1.50. The data values in each bin are the sum or average of all of the values that fall into the bin, as specified with the field data parameters sum and average.

• Continuous coordinates cannot be used with string values.

You can normalize the value of both discrete and continuous coordinates to the range [0,1] by setting the normalize axis toggle to on.

You can use the set label toggle to cause Table_to_Uniform_Field to output a string of labels that can be used by Axis modules.

The index labels toggle produces labels that are indices of coordinates rather than real numbers. This is useful when binning data. For example, when binning days into months, the axis labels should reflect the indices of the bins (month) rather than original values (days).

The label step slider bar allows you to control the frequency with which labels are applied to the coordinates on an axis. For example, if you select 3, a label is applied to every third coordinate.

Data parameters

You use the Field Data selection menu to select the columns that will become node data components in the resulting uniform field.

Optionally, you can use the Count Records toggle in the Field Data menu to count the number of values in a bin. If you select Count Records, the first data component of the field is a value that represents the number of records in each bin. As noted previously, for the rest of the columns, the data values in each bin are the sum or average of all of the values that fall into the bin, as specified with the field data parameters sum and average.

You use the Data Setup menu to specify a column whose data parameters you want to set. These parameter values are used when you select the column using Field Data. The data parameters sum and average are available as items in a radio box: sum causes the data in each bin to be summed, while average causes the data to be averaged.

Input Ports

columns[]

An array of type DBcolumn that contains the query data returned by a SELECT statement. This is the output of a DBquery module or Query macro.

parent

The UI parent, of type UIconnection.

Parameters

X Axis

A menu from which you can choose the name of a column that will serve as the X coordinate axis. The possible values are the names of the columns in the columns[] input port.

On

A toggle, located to the right of the X Axis menu, that turns on or off the X coordinate axis. The default is on.

Y Axis

A menu from which you can choose the name of a column that will serve as the Y coordinate axis. The possible values are the names of the columns in the columns[] input port.

On

A toggle, located to the right of the Y Axis menu, that turns on or off the X coordinate axis. The default is off.

Z Axis

A menu from which you can choose the name of a column that will serve as the Z coordinate axis. The possible values are the names of the columns in the columns[] input port.

On

A toggle, located to the right of the Z Axis menu, that turns on or off the X coordinate axis. The default is off.

Axis Setup

A menu from which you can choose the name of a column whose axis parameters you want to set. These parameter values are used when you select the column as a coordinate axis.The possible values are the names of the columns in the columns[] input port.

Discrete

A toggle that specifies whether to use discrete or continuous coordinates on the axes. If selected (the default), discrete coordinates are used, otherwise continuous coordinates are used.

Continuous coordinates cannot be used with string values.

Min value

For continuous coordinates, a field in which you specify a floating-point value that specifies the lowest value used in calculating coordinates. The default is the lowest data value in the column. Min value should be less than Max value.

Max value

For continuous coordinates, a field in which you specify a floating-point value that specifies the highest value used in calculating coordinates. The default is the highest data value in the column. Max value should be greater than Min value.

Bin size

For continuous coordinates, a field in which you specify a floating-point value that specifies the size of the bins into which the axis is divided. The default is 1.00.

normalize axis

A toggle that specifies whether to normalize the value of coordinates to the range [0, 1]. If selected (the default), the values are normalized.

set labels

A toggle that causes Table_to_Uniform_Field to output an array of label strings that can be used by Axis modules. If selected (the default), the labels are produced.

index labels

A toggle that produces labels that are indices of coordinates rather than real numbers. If selected (the default), the labels are produced.

This parameter is relevant only if you have also selected set labels.

label step

A slider bar that specifies the frequency with which labels are applied to the coordinates on an axis. For a value of n , a label is applied to every n th coordinate.

This parameter is relevant only if you have also selected set labels.

Field Data

A menu from which you can choose the columns that will become data components in the output uniform field. The first possible value is Count Records (see next parameter description); the other possible values are the names of the columns in the columns[] input port.

Count Records

A toggle that causes the module to count the number of values in a bin. If selected (the default), the following happens:

The first data component of the field is a value that represents the number of records in each bin.

For the rest of the columns, the data values in each bin are calculated by an averaging or a summation of all of the values that fall into a particular bin, as specified by the sum and average parameters.

Data Setup

A menu from which you can choose the name of a column whose field data parameters (sum and average) you want to set. These parameter values are used when you select the column using Field Data.The possible values are the names of the columns in the columns[] input port.

sum average

Radio box items that specify how the data values in a bin are calculated. When you select sum (the default), the values are summed; otherwise the values are averaged. These parameters are mutually exclusive.

Output Ports

out_fld

A uniform field with its data.

out_obj

A renderable field.

axis_labels

Labels for the X, Y, and Z axes.

x_name

The name of the column selected as the X coordinate axis.

y_name

The name of the column selected as the Y coordinate axis.

z_name

The name of the column selected as the Z coordinate axis.

File

v/db.v

See also

• Read_Column_File
• table_to_scattered_field

 




---