man/man1/total.1

.\" RCSid "$Id: total.1,v 1.11 2019/07/20 00:57:43 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 "\-in M"
][
.B "\-on M"
][
.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.
If a power is also specified using the
.I \-s
option, the inverse power will be applied to the averaged result.
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.
Normally,
.I total
reads each file to its end before producing its result, 
but this behavior may be overridden by inserting blank lines in
the input.
For each blank input line, total produces a result as if the
end-of-file had been reached.
If two blank lines immediately follow each other, total closes
the file and proceeds to the next one (after reporting the result).
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 (or every blank line).
This option also turns off the usual output flushing at each total.
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 \-in
option if present, will limit the number of input records read
(per input file).
The
.I \-on
option may be used to limit the total number of outut records produced.
.PP
The
.I \-tC
option can be used to specify the input and output tab character.
The default tab character is TAB.
.PP
If no files are given, the standard input is read.
.SH EXAMPLES
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), rcollate(1), rlam(1), rsplit(1), tabfunc(1)
Revision:	1.12
Committed:	Tue Nov 16 03:30:45 2021 UTC (3 years, 5 months ago) by greg
Branch:	MAIN
CVS Tags:	rad5R4, HEAD
Changes since 1.11:	+2 -1 lines
Log Message:	feat(total): added automatic output flushing unless -r option is present
#	User	Rev	Content
1	greg	1.12	.\" RCSid "$Id: total.1,v 1.11 2019/07/20 00:57:43 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.9	.B "\-in M"
23			][
24			.B "\-on M"
25			][
26	greg	1.1	.B \-tC
27			][
28			.B \-N
29			[
30			.B \-r
31			]]
32			[
33			file ..
34			]
35			.SH DESCRIPTION
36			.I Total
37			sums up columns of real numbers from one or more files
38			and prints out the result on its standard output.
39			.PP
40			By default,
41			.I total
42			computes the straigt sum of each input column, but multiplication
43			can be specified instead with the
44			.I \-p
45			option.
46			Likewise, the
47			.I \-u
48			option means find the upper limit (maximum), and
49			.I \-l
50			means find the lower limit (minimum).
51			.PP
52			Sums of powers can be computed by giving an exponent with the
53			.I \-s
54			option.
55			(Note that there is no space between the
56			.I \-s
57			and the exponent.)
58			This exponent can be any real number, positive or negative.
59			The absolute value of the input is always taken before the
60			power is computed in order to avoid complex results.
61			Thus,
62			.I \-s1
63			will produce a sum of absolute values.
64			The default power (zero) is interpreted as a straight sum without
65			taking absolute values.
66			.PP
67			The
68			.I \-m
69			option can be used to compute the mean rather than the total.
70			For sums, the arithmetic mean is computed.
71	greg	1.10	If a power is also specified using the
72			.I \-s
73			option, the inverse power will be applied to the averaged result.
74	greg	1.1	For products, the geometric mean is computed.
75			(A logarithmic sum of absolute values is used to avoid overflow, and
76			zero values are silently ignored.)
77			.PP
78	greg	1.4	If the input data is binary, the
79			.I \-id
80			or
81			.I \-if
82			option may be given for 64-bit double or 32-bit float values, respectively.
83			Either option may be followed immediately by an optional
84			count, which defaults to 1, indicating the number of double or float
85			binary values to read per record on the input file.
86			(There can be no space between the option and this count.)\0
87			Similarly, the
88			.I \-od
89			and
90			.I \-of
91			options specify binary double or float output, respectively.
92			These options do not need a count, as this will be determined by the
93			number of input channels.
94			.PP
95	greg	1.1	A count can be given as the number of lines to read before
96			computing a result.
97	greg	1.6	Normally,
98	greg	1.1	.I total
99	greg	1.6	reads each file to its end before producing its result,
100			but this behavior may be overridden by inserting blank lines in
101			the input.
102			For each blank input line, total produces a result as if the
103			end-of-file had been reached.
104			If two blank lines immediately follow each other, total closes
105			the file and proceeds to the next one (after reporting the result).
106			The
107	greg	1.1	.I \-N
108			option (where N is a decimal integer) tells
109			.I total
110			to produce a result and reset the calculation after
111			every N input lines.
112			In addition, the
113			.I \-r
114			option can be specified to override reinitialization and thus
115	greg	1.6	give a running total every N lines (or every blank line).
116	greg	1.12	This option also turns off the usual output flushing at each total.
117	greg	1.1	If the end of file is reached, the current total is printed
118			and the calculation is reset before the next file (with or without the
119			.I \-r
120			option).
121			.PP
122			The
123	greg	1.9	.I \-in
124			option if present, will limit the number of input records read
125			(per input file).
126			The
127			.I \-on
128			option may be used to limit the total number of outut records produced.
129			.PP
130			The
131	greg	1.1	.I \-tC
132			option can be used to specify the input and output tab character.
133			The default tab character is TAB.
134			.PP
135			If no files are given, the standard input is read.
136	greg	1.11	.SH EXAMPLES
137	greg	1.1	To compute the RMS value of colon-separated columns in a file:
138			.IP "" .2i
139	greg	1.7	total \-t: \-m \-s2 input
140	greg	1.1	.PP
141			To produce a running product of values from a file:
142			.IP "" .2i
143	greg	1.7	total \-p \-1 \-r input
144	greg	1.1	.SH BUGS
145			If the input files have varying numbers of columns, mean values
146			will certainly be off.
147			.I Total
148			will ignore missing column entries if the tab separator is a non-white
149			character, but cannot tell where a missing column should have been if
150			the tab character is white.
151			.SH AUTHOR
152			Greg Ward
153			.SH "SEE ALSO"
154	greg	1.11	cnt(1), neaten(1), rcalc(1), rcollate(1), rlam(1), rsplit(1), tabfunc(1)