NAME

drawasciihist - draw simple text histograms

SYNOPSIS

  generator | drawasciihist [--sort] [--width=<ncols>] [--style=<ident>]
                            [--numeric-format|nf=<printf format>]
                            [--delimiter|d=<regexp>] [--timestamp|ts]
                            [--min=X] [--max=X]

Together with the histify tool, this can easily produce simple visualizations for quickly analyzing simple data in a console. Run the script with the --man option to see an example.

The tool expects to read histogram data from STDIN, one bin per line. If a given input line has two or more columns (see the --delimiter option), the first column will be used as the bin name, the second as the numeric bin content. If an input line has only one column, the bin description will be the bin number.

By default, the output histogram will have a range from 0 to the maximum value in any bin. You can change the histogram range with the --min=X and --max=X options, providing numeric values for minimum and maximum. The --max option also allows special values of auto and total. auto is the default behaviour of --max and corresponds to the maximum bin content. --max=total will use the sum of all histogram contents instead. The --min option only understands auto which forces it to use the smallest bin content as the lower display boundary.

The output histogram width is determined automatically from your terminal size, if any. Otherwise assumes 80 columns. You can set the width explicitly using --width=ncols. The --sort option sorts the bins by content instead of input order.

If the --numeric-format option is present, then the actual numeric value is included in the histogram using the given printf format. For positive integers, you would use --nf='%u', for signed integers, use --nf='%i' and for fixed precision floats, you can use something like --nf='%.2f'.

The delimiter for splitting an input line into columns defaults to any whitespace. You can change that by supplying a Perl regular expression to the --delimiter=... option.

You can choose the character to be used for drawing histograms with the --style=[character] option. The characters '-', '=', '~' are special cased to use an arrow-like appearance.

The --timestamp option will case bin descriptions to be passed through localtime() to convert from Unix timestamps to human-readable time strings.

The --log option draws the histogram on a logarithmic scale. It is advised to use the --min option to specify an explicit minimum in this case, as the logarithm of 0 is not drawable. If no --min option is present, the --log option will change the default minimum from 0 to --min=auto.

EXAMPLE OUTPUT

  $ perl -e 'print $_*(rand()), "\n" for 1..100000' \
          | histify | drawasciihist -nf='%u' -w=70

   1:   33155|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~>|
   2:   19010|~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~>                         |
   3:   13972|~~~~~~~~~~~~~~~~~~~~~~~>                                  |
   4:   10476|~~~~~~~~~~~~~~~~~>                                        |
   5:    7919|~~~~~~~~~~~~>                                             |
   6:    5959|~~~~~~~~~>                                                |
   7:    4446|~~~~~~>                                                   |
   8:    2913|~~~~>                                                     |
   9:    1611|~>                                                        |
  10:     538|                                                          |