xref: /freebsd/usr.bin/ministat/ministat.1 (revision 1e413cf93298b5b97441a21d9a50fdcd0ee9945e)
1.\"
2.\" Copyright (c) 2007 Poul-Henning Kamp
3.\" All rights reserved.
4.\"
5.\" Redistribution and use in source and binary forms, with or without
6.\" modification, are permitted provided that the following conditions
7.\" are met:
8.\" 1. Redistributions of source code must retain the above copyright
9.\"    notice, this list of conditions and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\"
14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
24.\" SUCH DAMAGE.
25.\"
26.\" $FreeBSD$
27.\"
28.Dd December 20, 2007
29.Dt MINISTAT 1
30.Os
31.Sh NAME
32.Nm ministat
33.Nd statistics utility
34.Sh SYNOPSIS
35.Nm
36.Op Fl ns
37.Op Fl C Ar column
38.Op Fl c Ar confidence_level
39.Op Fl d Ar delimiter
40.Op Fl w Op width
41.Op Ar
42.Sh DESCRIPTION
43The
44.Nm
45command calculates fundamental statistical properties of numeric data
46in the specified files or, if no file is specified, standard input.
47.Pp
48The options are as follows:
49.Bl -tag -width Fl
50.It Fl n
51Just report the raw statistics of the input, suppress the ASCII-art plot
52and the relative comparisons.
53.It Fl s
54Print the average/median/stddev bars on separate lines in the ASCII-art
55plot, to avoid overlap.
56.It Fl C Ar column
57Specify which column of data to use.
58By default the first column in the input file(s) are used.
59.It Fl c Ar confidence_level
60Specify desired confidence level for Student's T analysis.
61Possible values are 80, 90, 85, 98, 99 and 99.5 %
62.It Fl d Ar delimiter
63Specifies the column delimiter characters, default is SPACE and TAB.
64See
65.Xr strtok 3
66for details.
67.It Fl w Ar width
68Width of ASCII-art plot in characters, default is 74.
69.El
70.Pp
71A sample output could look like this:
72.Bd -literal -offset indent
73  $ ministat -s -w 60 iguana chameleon
74  x iguana
75  + chameleon
76  +------------------------------------------------------------+
77  |x      *  x            *      +              + x           +|
78  | |________M______A_______________|                          |
79  |             |________________M__A___________________|      |
80  +------------------------------------------------------------+
81      N        Min        Max     Median        Avg       Stddev
82  x   7         50        750        200        300    238.04761
83  +   5        150        930        500        540    299.08193
84  No difference proven at 95.0% confidence
85.Ed
86.Pp
87If
88.Nm
89tells you, as in the example above, that there is no difference
90proven at 95% confidence, the two data sets you gave it are for
91all statistical purposes identical.
92.Pp
93You have the option of lowering your standards by specifying a
94lower confidence level:
95.Bd -literal -offset indent
96  $ ministat -c 80 iguana chameleon
97  x iguana
98  + chameleon
99  +------------------------------------------------------------+
100  |x      *  x            *      +              + x           +|
101  | |________M______A_______________|                          |
102  |             |________________M__A___________________|      |
103  +------------------------------------------------------------+
104      N        Min        Max     Median        Avg       Stddev
105  x   7         50        750        200        300    238.04761
106  +   5        150        930        500        540    299.08193
107  Difference at 80.0% confidence
108        240 +/- 212.215
109        80% +/- 70.7384%
110        (Student's t, pooled s = 264.159)
111.Ed
112.Pp
113But a lower standard does not make your data any better, and the
114example is only included here to show the format of the output when
115a statistical difference is proven according to Student's T method.
116.Sh SEE ALSO
117Any mathematics text on basic statistics, for instances Larry Gonicks
118excellent "Cartoon Guide to Statistics" which supplied the above example.
119.Sh HISTORY
120The
121.Nm
122command was written by Poul-Henning Kamp out of frustration
123over all the bogus benchmark claims made by people with no
124understanding of the importance of uncertainty and statistics.
125.Pp
126From
127.Fx 5.2
128it has lived in the source tree as a developer tool, graduating
129to the installed system from
130.Fx 8.0 .
131