.help ttranspose Nov94 tables
.nj
.ih
NAME
ttranspose -- Transpose or flip a table.
.ih
USAGE
ttranspose intable outtable action
.ih
DESCRIPTION
This task can be used to transpose a table
so that input rows become output columns
and input columns become output rows.
Another option is to flip the table horizontally,
that is, the first input column is the last output column.
Finally, the table can be flipped vertically,
i.e., the first input row is the last output row.
Any combination of these operations may be performed.

If the table is actually transposed
(rather than just flipped horizontally and/or vertically),
the data types of all input columns must be the same.
In addition, if the columns contain arrays rather than scalars,
all the array lengths must be the same.
The data type and array size will be preserved in the output table,
but the column names of the output table will be "c1", "c2", "c3", etc,
with default print format and null units.
Actually, some mixing of data types is permitted.
If some columns are type real and others are double precision,
the output data type will be double precision.
Similarly, short integers will be promoted to integers.
Boolean columns can be mixed with any other data type;
for numeric columns, yes becomes 1 and no becomes 0.
When the columns in the input table are character strings,
different maximum string lengths are permitted,
and the output length will be the maximum of the input lengths.
The restrictions on data type are not imposed on text tables,
which can contain mixed integer, double precision and text columns.

If the table is only flipped but not transposed,
the above restrictions on data type do not apply,
and the column names, units and print formats will be preserved.
Note that an operation such as "tht"
(which happens to be equivalent to "v")
does not actually transpose the table,
so the data types of the columns need not all be the same.

The 'tstat' task gives statistics for the values in a column,
so one application of 'ttranspose' is to get statistics on
the values in a row by first transposing the table and then running 'tstat'.

Text tables with too many rows cannot be transposed
due to the limit of 1024 on the length of each row of a text table.
.ih
PARAMETERS
.ls intable [file name template]
The list of input table names.
.le
.ls outtable [file name template]
The list of output table names.
There must be the same number of input and output names.
If the output is to be written to the standard output, however,
you can use outtable = "STDOUT" even if there several input tables.
.le
.ls action = "t" [string]
This is a string made up of the letters "t", "h", and "v"
which specify the operations to perform on the tables.
"t" means transpose (input rows become output columns),
"h" means flip horizontally (reverse the order of the columns),
and "v" means flip vertically (reverse the order of the rows).
The operations are performed in the order given from left to right.
Any combination of "t", "h", and "v" may be used,
in any order, and the letters may be repeated.

Operations such as "tt", "hh" or "vv" are valid,
and they result in a simple copy of input to output.

The symbols "/", "-" and "|" are equivalent to
the letters "t", "h" and "v" respectively.
.le
.ls verbose = yes [boolean]
Print the names of the tables as they are processed?
.le
.ih
EXAMPLES
1.  The input is the text file "in",
and the output is to be displayed on the screen.
Each of the three operations ("t", "h", "v")
and some combinations are illustrated.

.nf
	tt> type in
	one     two     three
	four    five    six
	seven   eight   nine
	ten     eleven  twelve

	tt> ttranspose in STDOUT t
	in --> STDOUT
	one    four   seven  ten   
	two    five   eight  eleven
	three  six    nine   twelve

	tt> ttranspose in STDOUT h
	in --> STDOUT
	three  two    one  
	six    five   four 
	nine   eight  seven
	twelve eleven ten  

	tt> ttranspose in STDOUT v
	in --> STDOUT
	ten   eleven twelve
	seven eight  nine  
	four  five   six   
	one   two    three 

	tt> ttranspose in STDOUT hv
	in --> STDOUT
	twelve eleven ten  
	nine   eight  seven
	six    five   four 
	three  two    one  

	tt> ttranspose in STDOUT th
	in --> STDOUT
	ten    seven  four   one   
	eleven eight  five   two   
	twelve nine   six    three 
.fi
.ih
BUGS
.ih
REFERENCES
This task was written by Phil Hodge.
.ih
SEE ALSO
Type "help ttools opt=sys" for a description of the 'tables' package.
.endhelp