man/man1/total.1

.\" RCSid "$Id: total.1,v 1.4 2005/06/02 04:47:26 greg Exp $"
.TH TOTAL 1 2/3/95 RADIANCE
.SH NAME
total - sum up columns
.SH SYNOPSIS
.B total
[
.B \-m
][
.B \-sE
|
.B \-p
|
.B \-u
|
.B \-l
][
.B \-i{f|d}[N]
][
.B \-o{f|d}
][
.B \-tC
][
.B \-N
[
.B \-r
]]
[
file ..
]
.SH DESCRIPTION
.I Total
sums up columns of real numbers from one or more files
and prints out the result on its standard output.
.PP
By default,
.I total
computes the straigt sum of each input column, but multiplication
can be specified instead with the
.I \-p
option.
Likewise, the
.I \-u
option means find the upper limit (maximum), and
.I \-l
means find the lower limit (minimum).
.PP
Sums of powers can be computed by giving an exponent with the
.I \-s
option.
(Note that there is no space between the 
.I \-s
and the exponent.)
This exponent can be any real number, positive or negative.
The absolute value of the input is always taken before the
power is computed in order to avoid complex results.
Thus,
.I \-s1
will produce a sum of absolute values.
The default power (zero) is interpreted as a straight sum without
taking absolute values.
.PP
The
.I \-m
option can be used to compute the mean rather than the total.
For sums, the arithmetic mean is computed.
For products, the geometric mean is computed.
(A logarithmic sum of absolute values is used to avoid overflow, and 
zero values are silently ignored.)
.PP
If the input data is binary, the
.I \-id
or
.I \-if
option may be given for 64-bit double or 32-bit float values, respectively.
Either option may be followed immediately by an optional
count, which defaults to 1, indicating the number of double or float
binary values to read per record on the input file.
(There can be no space between the option and this count.)\0
Similarly, the
.I \-od
and
.I \-of
options specify binary double or float output, respectively.
These options do not need a count, as this will be determined by the
number of input channels.
.PP
A count can be given as the number of lines to read before
computing a result.
By default,
.I total
reads each file to its end before producing its result, but the
.I \-N
option (where N is a decimal integer) tells
.I total
to produce a result and reset the calculation after
every N input lines.
In addition, the
.I \-r
option can be specified to override reinitialization and thus
give a running total every N lines.
If the end of file is reached, the current total is printed
and the calculation is reset before the next file (with or without the
.I \-r
option).
.PP
The
.I \-tC
option can be used to specify the input and output tab character.
The default tab character is TAB.
.PP
At least one set of totals is produced for each input file.
If no files are given, the standard input is read.
If a file contains any blank lines, then the total is reported
at that point as if it constituted the end of file, and the tallies
are reset.
.SH EXAMPLE
To compute the RMS value of colon-separated columns in a file:
.IP "" .2i
total -t: -m -s2 input
.PP
To produce a running product of values from a file:
.IP "" .2i
total -p -1 -r input
.SH BUGS
If the input files have varying numbers of columns, mean values
will certainly be off.
.I Total
will ignore missing column entries if the tab separator is a non-white
character, but cannot tell where a missing column should have been if
the tab character is white.
.SH AUTHOR
Greg Ward
.SH "SEE ALSO"
cnt(1), neaten(1), rcalc(1), rlam(1), tabfunc(1)
Revision:	1.5
Committed:	Tue Jun 21 02:34:22 2005 UTC (18 years, 11 months ago) by greg
Branch:	MAIN
Changes since 1.4:	+5 -1 lines
Log Message:	Documented new behavior with blank input lines in total(1)
#	User	Rev	Content
1	greg	1.5	.\" RCSid "$Id: total.1,v 1.4 2005/06/02 04:47:26 greg Exp $"
2	greg	1.1	.TH TOTAL 1 2/3/95 RADIANCE
3			.SH NAME
4			total - sum up columns
5			.SH SYNOPSIS
6			.B total
7			[
8			.B \-m
9			][
10			.B \-sE
11			\|
12			.B \-p
13			\|
14			.B \-u
15			\|
16			.B \-l
17			][
18	greg	1.4	.B \-i{f\|d}[N]
19			][
20			.B \-o{f\|d}
21			][
22	greg	1.1	.B \-tC
23			][
24			.B \-N
25			[
26			.B \-r
27			]]
28			[
29			file ..
30			]
31			.SH DESCRIPTION
32			.I Total
33			sums up columns of real numbers from one or more files
34			and prints out the result on its standard output.
35			.PP
36			By default,
37			.I total
38			computes the straigt sum of each input column, but multiplication
39			can be specified instead with the
40			.I \-p
41			option.
42			Likewise, the
43			.I \-u
44			option means find the upper limit (maximum), and
45			.I \-l
46			means find the lower limit (minimum).
47			.PP
48			Sums of powers can be computed by giving an exponent with the
49			.I \-s
50			option.
51			(Note that there is no space between the
52			.I \-s
53			and the exponent.)
54			This exponent can be any real number, positive or negative.
55			The absolute value of the input is always taken before the
56			power is computed in order to avoid complex results.
57			Thus,
58			.I \-s1
59			will produce a sum of absolute values.
60			The default power (zero) is interpreted as a straight sum without
61			taking absolute values.
62			.PP
63			The
64			.I \-m
65			option can be used to compute the mean rather than the total.
66			For sums, the arithmetic mean is computed.
67			For products, the geometric mean is computed.
68			(A logarithmic sum of absolute values is used to avoid overflow, and
69			zero values are silently ignored.)
70			.PP
71	greg	1.4	If the input data is binary, the
72			.I \-id
73			or
74			.I \-if
75			option may be given for 64-bit double or 32-bit float values, respectively.
76			Either option may be followed immediately by an optional
77			count, which defaults to 1, indicating the number of double or float
78			binary values to read per record on the input file.
79			(There can be no space between the option and this count.)\0
80			Similarly, the
81			.I \-od
82			and
83			.I \-of
84			options specify binary double or float output, respectively.
85			These options do not need a count, as this will be determined by the
86			number of input channels.
87			.PP
88	greg	1.1	A count can be given as the number of lines to read before
89			computing a result.
90			By default,
91			.I total
92			reads each file to its end before producing its result, but the
93			.I \-N
94			option (where N is a decimal integer) tells
95			.I total
96			to produce a result and reset the calculation after
97			every N input lines.
98			In addition, the
99			.I \-r
100			option can be specified to override reinitialization and thus
101			give a running total every N lines.
102			If the end of file is reached, the current total is printed
103			and the calculation is reset before the next file (with or without the
104			.I \-r
105			option).
106			.PP
107			The
108			.I \-tC
109			option can be used to specify the input and output tab character.
110			The default tab character is TAB.
111			.PP
112	greg	1.5	At least one set of totals is produced for each input file.
113	greg	1.1	If no files are given, the standard input is read.
114	greg	1.5	If a file contains any blank lines, then the total is reported
115			at that point as if it constituted the end of file, and the tallies
116			are reset.
117	greg	1.1	.SH EXAMPLE
118			To compute the RMS value of colon-separated columns in a file:
119			.IP "" .2i
120			total -t: -m -s2 input
121			.PP
122			To produce a running product of values from a file:
123			.IP "" .2i
124			total -p -1 -r input
125			.SH BUGS
126			If the input files have varying numbers of columns, mean values
127			will certainly be off.
128			.I Total
129			will ignore missing column entries if the tab separator is a non-white
130			character, but cannot tell where a missing column should have been if
131			the tab character is white.
132			.SH AUTHOR
133			Greg Ward
134			.SH "SEE ALSO"
135	greg	1.3	cnt(1), neaten(1), rcalc(1), rlam(1), tabfunc(1)