./No warranty whatsoever is provided for this software. See the
./file "License" in the source-package, or run "% sede show [c|w]".
./
.TH NADDI "1" "Jun 20 2006" "1.3"
.SH NAME
naddi \- compute distribution
.SH SYNOPSIS
\fBnaddi\fR [\fIOPTIONS...\fR] [\fIINFILE\fR [\fIOUTFILE\fR]]
.SH OVERVIEW
Compute "naddi" data distribution index.  Reads pairs of numbers
separated by whitespace. First number: the value, second number:
the frequency.

Example:

echo -e "10000 10\\n1000 10\\n5000 20\\n" | naddi
.br
84.4%
.SH OPTIONS
.TP
\fB-a\fR, \fB--average\fR
Print the total value, the number of elements, and the
element value average (in that order).
.TP
\fB-d\fR\fIDIVIDE\fR\fR[\fB%\fR], \fB--divide=\fR\fIDIVIDE\fR[\fB%\fR]
Use another fraction for --extreme, --extreme-index and --share then the
default 50%.
With `%' assumes a percentage, without `%' a fraction between 0 and 1.
.TP
\fB-e\fR, \fB--extreme\fR
Print the minimum, the \fIDIVIDE%\fR, and maximum element values.

The \fIDIVIDE%\fR element is the first element encountered in the input,
which makes the number of elements so far encountered, larger or equal then
\fIDIVIDE%\fR of the total number of elements.
\fIDIVIDE%\fR is 50% unless otherwise specified by --divide=\fIDIVIDE\fR.
Sort(1) input on numerical value.
.TP
\fB-E\fR, \fB--extreme-index\fR
Print element distribution minimum, \fIDIVIDE%\fR and maximum, as fractions.
(See --divide.)
Sort(1) input on numerical value.
.TP
\fB-f\fR, \fB--fraction\fR 
Print distribution index as fraction.
.TP
\fB--formula\fR
Print distribution algorithm.
.TP
\fB--fizz\fR
Print --share in `The top ...% corresponds to ...', give 2 times
for `The bottom ...% ...'.
.TP
\fB-h\fR, \fB--help\fR
Print usage.
.TP
\fB-o\fR\fIVALUE\fR, \fB--offset=\fR\fIVALUE\fR
Give an offset for all values before computing the distribution index.

--offset=0 is special: it adjusts all values equally, so that the
minimum element value is 0.
.TP
\fB-p\fR\fIN\fR, \fB--precision=\fR\fIN\fR
Set the precision (program uses `long double' data type, which is not
infinite).
.TP
\fB-s\fR, \fB--share\fR
Total value encountered in the input stream, until the \fIDIVIDE%\fR
value, which is added to the share proportionally.
Prints in the same format (fraction or percentage) as the --divide
argument was given in.
Sort(1) input on numerical value.
.TP
\fB--version\fR
Print version.
.TP
\fB-v\fR[\fIN\fR], \fB--verbose\fR[\fB=\fR\fIN\fR]
Verbose level, max 4.
.SH DETAIL
negative values

If a value is negative, all values are adjusted
upwards until the minimum value is 0 when computing the distribution
index (the formula does not handle negative numbers properly). The
negative adjustment is determined before --offset has taken effect.
.SH RETURN VALUE
Returns 0 on success, 1 for input error, 2 for computation error, 3
for system error.
.SH COPYRIGHT
This software is released under the terms of the Free Software
Foundation's `General Public Licence' (GPL). This License is
Copyrighted by Free Software Foundation, 
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301  USA

This utility comes without any warranty whatsoever.
.SH BUGS
Report bugs to joshb@xs4all.nl

Anomaly when using --offset:

Usually the index is expected to be closer to 100% if all values are
adjusted upwards. However, relatively close to --offset=0, sometimes the index
falls first slightly (up to about 1%) for an increased --offset, reaches a
minimum, and then increases as expected. This is probably because 
slight increases of values near zero and therefore their element-distribution
indexes also near zero, do not have any effect on the outcome with a higher
--offset yet, whereas the changes of larger values takes an effect
immediately for a rising offset. This will make the high indexes go up
while the low indexes remain practically `near zero', resulting in a
greater disparity between high and low element indexes, which results
in a "less equal" distribution index (lower index).
.SH AUTHOR
Jos Boersema