man/man1/rcollate.1

.\" RCSid "$Id: rcollate.1,v 1.6 2014/05/30 16:50:43 greg Exp $"
.TH RCOLLATE 1 7/8/97 RADIANCE
.SH NAME
rcollate - resize or transpose matrix data
.SH SYNOPSIS
.B rcollate
[
.B \-h[io]
][
.B \-w
][
.B \-f[afdb][N]
][
.B \-t
][
.B "\-ic in_col"
][
.B "\-ir in_row"
][
.B "\-oc out_col"
][
.B "\-or out_row"
]
[
.B input.dat
]
.SH DESCRIPTION
.I Rcollate
reads in a single matrix file (table) and reshapes it to have
the number of columns specified by the
.I \-oc
option.
By default, the file is assumed to include an information header, which
is copied to the standard output along with the command name.
The
.I \-hi
option may be used to turn off the expectation of a header on input.
The
.I \-ho
option turns off header output, and
.I \-h
by itself turns off both input and output headers.
The
.I \-w
option turns off non-fatal warning messages, such as unexpected EOD.
.PP
The input format is assumed to be ASCII, with three white-space separated words
(typically numbers) in each record.
A different input format may be specified with the
.I \-f
option.
The suboptions are
.I \-fa,
.I \-ff,
.I \-fd,
and
.I \-fb
for ASCII, float, double, and binary, respectively.
An optional count may be attached to specify the number of data elements per
record, which defaults to 1.
Thus, the default setting is
.I \-fa3.
Since
.I rcollate
does not interpret the fields, all binary options of the same
length have the same result.
On most architectures,
.I \-ff6,
.I \-fd3,
and
.I \-fb24
would all be equivalent.
Note that the lack of row separators in binary files means that
.I rcollate
does not actually do anything for binary files unless the transpose
option is given, also.
.PP
If an input header is present, it may contain the format, number of components
and matrix dimensions.
In such cases, the
.I \-ic,
.I \-ir
and
.I \-f
options are not required, but will be checked against the header
information if provided.
.PP
The transpose option,
.I \-t
swaps rows and columns on the input.
For binary files, the user must specify at least one input or output
dimension to define the matrix size.
For ASCII files,
.I rcollate
will automatically determine the number of columns based on the
position of the first EOL (end-of-line) character, and the number
of rows based on the total count of records in the file.
The user may override these determinations, allowing the matrix to
be resized as well as transposed.
If input and output dimensions are given, the number of input rows
must equal the number of output columns,
and the number of input columns must equal the number of output rows.
For large transpose operations on Unix systems, it is most efficient
to specify the input file on the command line, rather than reading
from the standard input, since
.I rcollate
can map the file directly into virtual memory.
.SH EXAMPLE
To change put 8760 color triplets per row in a matrix with no header:
.IP "" .2i
rcollate -h \-oc 8760 input.dat > col8760.dat
.PP
To transpose a binary file with 145 float triplets per input row:
.IP "" .2i
rcollate -ff3 -ic 145 -t orig.flt > transpose.flt
.PP
To create an appropriate header for a binary float matrix as required by
.I rmtxop(1)\:
.IP "" .2i
rcollate -hi -ff3 -or 145 -oc 8760 input.smx | rmtxop dcoef.dmx - > res.txt
.SH AUTHOR
Greg Ward
.SH NOTES
The
.I rcollate
command is rather inflexible when it comes to output field and record
separators for ASCII data.
It accepts any amount of white space between fields
on input, but only produces spaces as field separators
between words and tabs as record separators on output.
Output row separtors will always be an EOL, which may differ between systems.
.PP
If no options are given on the command line, or a binary file is specified
without a transpose,
.I rcollate
issues a warning and simply copies its input to its standard output.
.SH "SEE ALSO"
cnt(1), histo(1), neaten(1), rcalc(1), rlam(1), rmtxop(1), tabfunc(1), total(1)
Revision:	1.7
Committed:	Sat May 31 21:33:21 2014 UTC (10 years, 11 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R2, rad4R2P2, rad5R0, rad5R1, rad4R2, rad4R2P1
Changes since 1.6:	+8 -3 lines
Log Message:	Added rmtxop command for manipulating component matrices
#	User	Rev	Content
1	greg	1.7	.\" RCSid "$Id: rcollate.1,v 1.6 2014/05/30 16:50:43 greg Exp $"
2	greg	1.1	.TH RCOLLATE 1 7/8/97 RADIANCE
3			.SH NAME
4			rcollate - resize or transpose matrix data
5			.SH SYNOPSIS
6			.B rcollate
7			[
8	greg	1.6	.B \-h[io]
9	greg	1.1	][
10	greg	1.3	.B \-w
11			][
12	greg	1.7	.B \-f[afdb][N]
13	greg	1.1	][
14			.B \-t
15			][
16			.B "\-ic in_col"
17			][
18			.B "\-ir in_row"
19			][
20			.B "\-oc out_col"
21			][
22			.B "\-or out_row"
23			]
24			[
25			.B input.dat
26			]
27			.SH DESCRIPTION
28			.I Rcollate
29			reads in a single matrix file (table) and reshapes it to have
30			the number of columns specified by the
31			.I \-oc
32			option.
33			By default, the file is assumed to include an information header, which
34	greg	1.6	is copied to the standard output along with the command name.
35			The
36			.I \-hi
37			option may be used to turn off the expectation of a header on input.
38			The
39			.I \-ho
40			option turns off header output, and
41	greg	1.1	.I \-h
42	greg	1.6	by itself turns off both input and output headers.
43	greg	1.3	The
44			.I \-w
45			option turns off non-fatal warning messages, such as unexpected EOD.
46	greg	1.1	.PP
47			The input format is assumed to be ASCII, with three white-space separated words
48			(typically numbers) in each record.
49			A different input format may be specified with the
50			.I \-f
51			option.
52			The suboptions are
53			.I \-fa,
54			.I \-ff,
55			.I \-fd,
56			and
57			.I \-fb
58			for ASCII, float, double, and binary, respectively.
59			An optional count may be attached to specify the number of data elements per
60			record, which defaults to 1.
61			Thus, the default setting is
62			.I \-fa3.
63			Since
64			.I rcollate
65			does not interpret the fields, all binary options of the same
66			length have the same result.
67			On most architectures,
68			.I \-ff6,
69			.I \-fd3,
70			and
71			.I \-fb24
72			would all be equivalent.
73	greg	1.2	Note that the lack of row separators in binary files means that
74	greg	1.1	.I rcollate
75			does not actually do anything for binary files unless the transpose
76			option is given, also.
77			.PP
78	greg	1.5	If an input header is present, it may contain the format, number of components
79			and matrix dimensions.
80			In such cases, the
81			.I \-ic,
82			.I \-ir
83			and
84			.I \-f
85			options are not required, but will be checked against the header
86			information if provided.
87			.PP
88	greg	1.1	The transpose option,
89			.I \-t
90			swaps rows and columns on the input.
91			For binary files, the user must specify at least one input or output
92			dimension to define the matrix size.
93			For ASCII files,
94			.I rcollate
95			will automatically determine the number of columns based on the
96			position of the first EOL (end-of-line) character, and the number
97	greg	1.2	of rows based on the total count of records in the file.
98	greg	1.1	The user may override these determinations, allowing the matrix to
99			be resized as well as transposed.
100			If input and output dimensions are given, the number of input rows
101			must equal the number of output columns,
102	greg	1.2	and the number of input columns must equal the number of output rows.
103			For large transpose operations on Unix systems, it is most efficient
104	greg	1.1	to specify the input file on the command line, rather than reading
105			from the standard input, since
106			.I rcollate
107	greg	1.4	can map the file directly into virtual memory.
108	greg	1.1	.SH EXAMPLE
109			To change put 8760 color triplets per row in a matrix with no header:
110			.IP "" .2i
111			rcollate -h \-oc 8760 input.dat > col8760.dat
112			.PP
113			To transpose a binary file with 145 float triplets per input row:
114			.IP "" .2i
115			rcollate -ff3 -ic 145 -t orig.flt > transpose.flt
116	greg	1.7	.PP
117			To create an appropriate header for a binary float matrix as required by
118			.I rmtxop(1)\:
119			.IP "" .2i
120			rcollate -hi -ff3 -or 145 -oc 8760 input.smx \| rmtxop dcoef.dmx - > res.txt
121	greg	1.1	.SH AUTHOR
122			Greg Ward
123			.SH NOTES
124			The
125			.I rcollate
126			command is rather inflexible when it comes to output field and record
127			separators for ASCII data.
128	greg	1.2	It accepts any amount of white space between fields
129	greg	1.1	on input, but only produces spaces as field separators
130	greg	1.2	between words and tabs as record separators on output.
131	greg	1.1	Output row separtors will always be an EOL, which may differ between systems.
132			.PP
133			If no options are given on the command line, or a binary file is specified
134			without a transpose,
135			.I rcollate
136	greg	1.2	issues a warning and simply copies its input to its standard output.
137	greg	1.1	.SH "SEE ALSO"
138	greg	1.7	cnt(1), histo(1), neaten(1), rcalc(1), rlam(1), rmtxop(1), tabfunc(1), total(1)