table_to_uniform_field

Synopsis

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

Input Port

columns[]	array of Data_Array
parent	UIconnection

Parameters

X_Axis	UIoptionMenu	selects a column for the field's X axis
On	UItoggle	if set, use the X axis
Y_Axis	UIoptionMenu	selects a column for the field's Y axis
On	UItoggle	if set, use the Y axis
Z_Axis	UIoptionMenu	selects a column for the field's Z axis
On	UItoggle	if set, use the Z axis
Axis_Setup	UIoptionMenu	selects a column whose axis parameters are to be set
Discrete	UItoggle	toggles the column between discrete and continuous values
Min_value	UIfield	minimum value for coordinates
Max_value	UIfield	maximum value for coordinates
Bin_size	UIfield	size of the bin
normalize_axis	UItoggle	if set, normalizes coordinates to the [0, 1] range
set_labels	UItoggle	if set, creates labels for the axis
index_labels	UItoggle	if set, uses indices instead of values for labels
label_step	UIslider	number to skip for labels
Field_Data	UIoptionBox	selects columns for field node data
Count_Records	UItoggle	if set, counts the number of values in a bin
Data_Setup	UIoptionMenu	selects a column whose data parameters are to be set
sum	UIradioBox	sums the data in each bin
average	UIradioBox	averages the data in each bin

Output Port

out_fld	Mesh_Unif+Node_Data
out_obj	DefaultObject
axis_labels	group
x_name	string
y_name	string
z_name	string

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:

{bmc BULLET.BMP} Discrete

{bmc BULLET.BMP} Min_value

{bmc BULLET.BMP} Max_value

{bmc BULLET.BMP} Bin_size

{bmc BULLET.BMP} normalize_axis

{bmc BULLET.BMP} set_labels

{bmc BULLET.BMP} index_labels

{bmc BULLET.BMP} 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.

{bmc BULLET.BMP} 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

columns[]

parent

Parameters

X_Axis

On

Y_Axis

On

Z_Axis

On

Axis_Setup

Discrete

Min_value

Max_value

Bin_size

normalize_axis

set_labels

index_labels

label_step

Field_Data

Count_Records

Data_Setup

sum average

Output Port

out_fld

out_obj

axis_labels

x_name

y_name

z_name

Example

Not available

File

v/db.v

See also related modules