/usr.bin/ministat/ministat.1

  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 June 28, 2010
 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, 95, 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 -s -w 60 -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 .