DATAMANIP commands


PROGRAM NAME

kimportasc - Import ASCII Data File to Data Segment

DESCRIPTION

This routine will import an ASCII data file and insert it into a specified data object. The new segment will be inserted into this data object. If a source object was specified, then all of its data segments and the global object attributes will be copied to the destination. If no source object was specified, then the resulting output object will contain only the imported segment.

There are four attributes of the new segment that can be specified: dimension, index order, size and data type. The number of indices and sizes specified must be equal to the dimension.

The parameter dimension must be greater than 0 and and less than or equal to 5.

The segment size is an optional argument specified by five different size variables: 'wsize', 'hsize', 'dsize', 'tsize', and 'esize'. Each size variable must be >= to 1. Note that although the size variables are optional, if no size variables are specified, the output will be of size 1.

The index order is also specified by five different variables: 'windex', 'hindex', 'dindex', 'tindex', and 'eindex'. The value for each index variable must be unique and range from 1 to 5. Note that the index order dictates how data is stored and retrieved. For example if the index order is specified as windex 1, hindex 2, dindex 3, tindex 4, eindex 5 then data will be accessed along width first, followed by height, depth, time, and elements. If, however the index order is specified as eindex 1, windex 2, hindex 3, dindex 4, tindex 5 then data will be accessed along elements first, followed by width, height, depth, and time.

The start offset specifies the point in the ASCII data from which to start importing in the data into the specified segment. All points before the start offset are ignored.

The skip factor specifies the number of points to skip in the ASCII data between reads.

The number of reads specifies the number of points to read before skipping. For example, if the number of reads is 2 and the skip factor is 3, two values will be read, three will be skipped, followed by two more reads, three skips, etc. until all the data has been read.

If the segment_name is one of the Polymorphic segments, the correct dimensionality must be provided :

         Segment Name               Dimension
       ---------------------------------------------------
             KDA_SEGMENT_VALUE         5
             KDA_SEGMENT_MAP           5
             KDA_SEGMENT_MASK          5
             KDA_SEGMENT_LOCATION      4
             KDA_SEGMENT_TIME          1

When importing ASCII data to either the value, map, or mask segment, all five size variables (wsize, hsize, dsize, tsize, and esize) may be specified since these segments are five dimensional. Likewise, a five dimensional index order may be provided.

When importing ASCII data to the locations segment, only four size variables (wsize, hsize, dsize, and esize) may be specified since the location segment is four dimensional. Likewise only a four dimensional index order (windex, hindex, dindex, eindex) may be provided.

When importing ASCII data to the time segment, only one size variable (tsize) may be specified since the location segment is one dimensional. Likewise only a one dimensional index order (tindex) may be provided.

Complex values in ASCII are represented by number pairs, surrounded by parenthesis and separated by a comma. These numbered pairs correspond to the real and imaginary values respectively. For example, (8, 3) represents the complex number 8+3i.

REQUIRED ARGUMENTS

-i1
type: infile
desc: ASCII input data file containing new data segment
-o
type: outfile
desc: output data object

OPTIONAL ARGUMENTS

-i2
type: infile
desc: data object input to insert the new segment into
default: {none}
-so
type: integer
desc: starting point in ASCII input file to start importing at
default: 0
bounds: value >= 0
-sf
type: integer
desc: number of points in ASCII file to skip between reads
default: 0
bounds: value >= 0
-nr
type: integer
desc: number of points in ASCII file to read between skips
default: 1
bounds: value > 0
-segment
type: string
desc: The name of the segment to insert the ASCII data into
default: Value
-dim
type: integer
desc: dimension of the segment
default: 5
bounds: value > 0
-type
type: list
desc: data type to store ascii data as
default: 11 "Double"

Mutually Inclusive Group; if desired, specify ALL of:

-wsize
type: integer
desc: size of width dimension in index specified
default: 1
bounds: value > 0
AND
-windex
type: list
desc: position in the index order for the width dimension
default: 1 "First"

Mutually Inclusive Group; if desired, specify ALL of:

-hsize
type: integer
desc: size of height dimension in index specified
default: 1
bounds: value > 0
AND
-hindex
type: list
desc: position in the index order for the height dimension
default: 2 "Second"

Mutually Inclusive Group; if desired, specify ALL of:

-dsize
type: integer
desc: size of depth dimension in index specified
default: 1
bounds: value > 0
AND
-dindex
type: list
desc: position in the index order for the depth dimension
default: 3 "Third"

Mutually Inclusive Group; if desired, specify ALL of:

-tsize
type: integer
desc: size of time dimension in index specified
default: 1
bounds: value > 0
AND
-tindex
type: list
desc: position in the index order for the time dimension
default: 4 "Fourth "

Mutually Inclusive Group; if desired, specify ALL of:

-esize
type: integer
desc: size of elements dimension in index specified
default: 1
bounds: value > 0
AND
-eindex
type: list
desc: position in the index order for the elements dimension
default: 5 "Fifth "

EXAMPLES

Consider a simple ASCII input file which looks as follows:

	file:  "ascii_data"

1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4 1 2 3 4

This data can be imported into the 'value' segment in any number of ways which is illustrated in the following four examples.

Value Segment Example 1

% kimportasc -i1 ascii_data -o output -wsize 2 -hsize 5 -dsize 1 -tsize 1 -esize 1 -so 0 -sf 1 -nr 1 -windex 1 -hindex 2 -dindex 3 -tindex 4 -eindex 5 -segment value -type 6

This will import the above ASCII data into the value segment of a polymorphic data object such that the size is "2x5x1x1x1", index order is "w,h,d,t,e", and data type is integer. The output from kimportasc would conceptually look as follows:

	1 3
	1 3
	1 3
	1 3
	1 3

Value Segment Example 2

% kimportasc -i1 ascii_data -o output -wsize 1 -hsize 5 -dsize 1 -tsize 1 -esize 1 -so 1 -sf 3 -nr 1 -windex 1 -hindex 2 -dindex 3 -tindex 4 -eindex 5 -segment value -type 4

This will import the above ASCII data into the value segment of a polymorphic data object such that the size is "1x5x1x1x1", index order is "w,h,d,t,e", and data type is short. The output from kimportasc would conceptually look as follows:

	2
	2
	2
	2
	2

Value Segment Example 3

% kimportasc -i1 ascii_data -o output -wsize 3 -hsize 5 -dsize 1 -tsize 1 -esize 1 -so 1 -sf 1 -nr 3 -windex 1 -hindex 2 -dindex 3 -tindex 4 -eindex 5 -segment value -type 10

This will import the above ASCII data into the value segment of a polymorphic data object such that the size is "3x5x1x1x1", index order is "w,h,d,t,e", and data type is float. The output from kimportasc would conceptually look as follows:

	2 3 4
	2 3 4
	2 3 4
	2 3 4
	2 3 4

Value Segment Example 4

% kimportasc -i1 ascii_data -o output -wsize 5 -hsize 4 -dsize 1 -tsize 1 -esize 1 -so 0 -sf 0 -nr 20 -segment value -type 8

This will import the above ASCII data into the value segment of a polymorphic data object such that the size is "4x5x1x1x1", index order is "w,h,d,t,e", and data type is long. The output from kimportasc would conceptually look as follows:

	1 2 3 4 1 
	2 3 4 1 2 
	3 4 1 2 3 
	4 1 2 3 4

The same input data can be imported into the 'map' segment which is illustrated in the following example.

Map Segment Example

% kimportasc -i1 ascii_data -i2 data_without_map -o output -wsize 4 -hsize 5 -dsize 1 -tsize 1 -esize 1 -so 0 -sf 0 -nr 1 -windex 1 -hindex 2 -dindex 3 -tindex 4 -eindex 5 -segment map -type 6

This will import the above ASCII data into the map segment of the polymorphic data object specified by the input file "data_without_map" such that the size of the map is "4x5x1x1x1", index order is "mw,mh,md,mt,me", and data type is integer, where "mw,mh,md,mt,me" coorespond to map width, map height, map depth, map time, and map elements respectively. The map segment output from kimportasc would conceptually look like the input ASCII data.

	1 2 3 4
	1 2 3 4
	1 2 3 4
	1 2 3 4
	1 2 3 4

Mask Segment Example

The following input data can be imported into the 'mask' segment which is illustrated in the following example.

	file:  "map_ascii_data"

1 0 0 1 0 0 1 0 1 1 0 0 1 1 1 1 1 0 1 0

% kimportasc -i1 map_ascii_data -i2 data_without_mask -o output -wsize 4 -hsize 5 -dsize 1 -tsize 1 -esize 1 -so 0 -sf 0 -nr 1 -windex 1 -hindex 2 -dindex 3 -tindex 4 -eindex 5 -segment mask -type 6

This will import the above ASCII data into the mask segment of the polymorphic data object specified by the input file "data_without_mask" such that the size of the mask is "4x5x1x1x1", index order is "w,h,d,t,e" and data type is integer. The mask segment output from kimportasc would conceptually look like the ASCII input.

Time Segment Example

The following input data can be imported into the 'time' segment which is illustrated in the following example.

	file: "time_ascii_data"

1 5 10 15 19 36 40 52

% kimportasc -i1 time_ascii_data -i2 data_with_time_series -o output -tsize 8 -so 0 -sf 0 -nr 1 -tindex 1 -segment time -type 6 -dim 1

This will import the above ASCII data into the time segment of the polymorphic data object specified by the input file "data_with_time_series" such that the size of the explicit time segment is "8", index order is "t", and data type is integer. The time segment output from kimportasc would conceptually look like the ASCII input.

Location Segment Example

The following input data can be imported into the 'location'segment which is illustrated in the following example.

	file:  "location_ascii_data"

1 3 5 7 9 11 13 15 17 19 21 23 25 27 29 31 33 35 37 39

% kimportasc -i1 location_ascii_data -i2 data_without_locations -o output -wsize 4 -hsize 5 -dsize 1 -esize 1 -so 0 -sf 0 -nr 1 -windex 1 -hindex 2 -dindex 3 -eindex 4 -segment location -type 6 -dim 4

This will import the above ASCII data into the location segment of the polymorphic data object specified by the input file "data_without_locations" such that the size of the explicit location segment is "4x5x1x1", index order is "w,h,d,e", and data type is integer. The location segment output from kimportasc would conceptually look like the ASCII input.

SEE ALSO

kasc2val, kasc2mask, kasc2loc, kasc2time, kasc2map

RESTRICTIONS

If no size variables are specified (wsize, hsize, dsize, tsize, or esize), the output data object will be of size 1.

REFERENCES

COPYRIGHT

Copyright (C) 1993 - 1997, Khoral Research, Inc. ("KRI") All rights reserved.