st
==

simple statistics from the command line interface (CLI)

### Description

Imagine you have this sample file:

   $ cat numbers.txt
   1
   2
   3
   4
   5
   6
   7
   8
   9
   10

How do you calculate the sum of the numbers?

#### The traditional way

If you ask around, you'll come up with suggestions like these:

   $ awk '{s+=$1} END {print s}' numbers.txt
   55

   $ perl -lne '$x += $_; END { print $x; }' numbers.txt
   55

   $ sum=0; while read num ; do sum=$(($sum + $num)); done < numbers.txt ; echo $sum
   55

   $ paste -sd+ numbers.txt | bc
   55

Now imagine that you need to calculate the arithmetic mean, median,
or standard deviation...


#### Using st

"st" is a command-line tool to calculate simple statistics from a
file or standard input.

Let's start with "sum":

   $ st --sum numbers.txt
   55

That was easy!

How about mean and standard deviation?

   $ st --mean --stddev numbers.txt
   mean  stddev
   5.5   3.02765

If you don't specify any options, you'll get this output:

   $ st numbers.txt
   N     min   max   sum   mean  stddev
   10    1     10    55    5.5   3.02765

You can switch rows and columns using the "--transpose-output" option:

   $ st --transpose-output numbers.txt
   N       10
   min     1
   max     10
   sum     55
   mean    5.5
   stddev  3.02765

The "--summary" option will provide the five-number summary:

   $ st --summary numbers.txt
   min   q1    median  q3    max
   1     3.5   5.5     7.5   10

And "--complete" will print a complete description:

   $ st --complete numbers.txt
   N   min   q1    median  q3    max   sum   mean  stddev  stderr
   10  1     3.5   5.5     7.5   10    55    5.5   3.02765 0.957427

#### How does it compare with R, Octave and other analytical tools?

"R" and Octave are integrated suites for data manipulation, calculation
and graphical display.

They provide high-level interpreted languages, capabilities for the
numerical solution of linear and nonlinear problems, and for
performing other numerical experiments, including statistical tests,
classification, clustering, etc.

"st" is a simpler solution for simpler problems, focused on descriptive
statistics for small datasets, handy when you need quick results
without leaving the shell.


### Usage

   st [options] [file]

#### Options

##### Functions

   --N|n|count
   --mean|avg|m
   --stddev|sd
   --stderr|sem|se
   --sum|s
   --var|variance

   --min
   --q1
   --median
   --q3
   --max

   --percentile=<0..1>
   --quartile=<1..4>

If no functions are selected, "st" will print the default output:

   N     min  max  sum  mean  stddev

You can also use the following predefined sets of functions:

   --summary   # five-number summary (min q1 median q3 max)
   --complete  # everything

##### Formatting

   --format|fmt|f=<value>  # default: "%g"
   --delimiter|d=<value>   # default: "\t"

   --no-header|nh          # don't display header
   --transpose-output|to   # switch rows and columns

Examples of valid formats ("--format" option):

       %d    signed integer, in decimal
       %e    floating-point number, in scientific notation
       %f    floating-point number, in fixed decimal notation
       %g    floating-point number, in %e or %f notation

##### Input validation

By default, "st" skips invalid input with a warning.

You can change this behavior with the following options:

   --strict   # throws an error, interrupting process
   --quiet|q  # no warning

### Author

Nelson Ferraz <<[email protected]>>

### Contribute

Send comments, suggestions and bug reports to:

https://github.com/nferraz/st/issues

Or fork the code on github:

https://github.com/nferraz/st