2.11 histograms

The histograms style is only relevant to 2D plotting. It produces a bar chart from a sequence of parallel data columns. Each element of the ‘plot‘ command must specify a single input data source (e.g. one column of the input file), possibly with associated tic values or key titles. Four styles of histogram layout are currently supported.

      set style histogram clustered {gap <gapsize>}
      set style histogram errorbars {gap <gapsize>} {<linewidth>}
      set style histogram rowstacked
      set style histogram columnstacked

The default style corresponds to ‘set style histogram clustered gap 2‘. In this style, each set of parallel data values is collected into a group of boxes clustered at the x-axis coordinate corresponding to their sequential position (row #) in the selected datafile columns. Thus if <n> datacolumns are selected, the first cluster is centered about x=1, and contains <n> boxes whose heights are taken from the first entry in the corresponding <n> data columns. This is followed by a gap and then a second cluster of boxes centered about x=2 corresponding to the second entry in the respective data columns, and so on. The default gap width of 2 indicates that the empty space between clusters is equivalent to the width of 2 boxes. All boxes derived from any one column are given the same fill color and/or pattern (see ‘set style fill‘).

Each cluster of boxes is derived from a single row of the input data file. It is common in such input files that the first element of each row is a label. Labels from this column may be placed along the x-axis underneath the appropriate cluster of boxes with the ‘xticlabels‘ option to using.

The errorbars style is very similar to the ‘clustered‘ style, except that it requires additional columns of input for each entry. The first column holds the height (y value) of that box, exactly as for the ‘clustered‘ style.

     2 columns:        y yerr          bar extends from y-yerr to y+err
     3 columns:        y ymin yman     bar extends from ymin to ymax

The appearance of the error bars is controlled by the current value of bars and by the optional <linewidth> specification.

Two styles of stacked histogram are supported, chosen by the command ‘set style histogram {rowstacked|columnstacked}‘. In these styles the data values from the selected columns are collected into stacks of boxes. Positive values stack upwards from y=0; negative values stack downwards. Mixed positive and negative values will produce both an upward stack and a downward stack. The default stacking mode is ‘rowstacked‘.

The ‘rowstacked‘ style places a box resting on the x-axis for each data value in the first selected column; the first data value results in a box a x=1, the second at x=2, and so on. Boxes corresponding to the second and subsequent data columns are layered on top of these, resulting in a stack of boxes at x=1 representing the first data value from each column, a stack of boxes at x=2 representing the second data value from each column, and so on. All boxes derived from any one column are given the same fill color and/or pattern (see ‘set style fill‘).

The ‘columnstacked‘ style is similar, except that each stack of boxes is built up from a single data column. Each data value from the first specified column yields a box in the stack at x=1, each data value from the second specified column yields a box in the stack at x=2, and so on. In this style the color of each box is taken from the row number, rather than the column number, of the corresponding data field.

Box widths may be modified using the boxwidth command. Box fill styles may be set using the ‘set style fill‘ command.

Histograms always use the x1 axis, but may use either y1 or y2. If a plot contains both histograms and other plot styles, the non-histogram plot elements may use either the x1 or the x2 axis.

Examples: Suppose that the input file contains data values in columns 2, 4, 6, ... and error estimates in columns 3, 5, 7, ... This example plots the values in columns 2 and 4 as a histogram of clustered boxes (the default style). Because we use iteration in the plot command, any number of data columns can be handled in a single command. See iteration.

      set boxwidth 0.9 relative
      set style data histograms
      set style histogram cluster
      set style fill solid 1.0 border lt -1
      plot for [COL=2:4:2] 'file.dat' using COL

This will produce a plot with clusters of two boxes (vertical bars) centered at each integral value on the x axis. If the first column of the input file contains labels, they may be placed along the x-axis using the variant command

      plot for [COL=2:4:2] 'file.dat' using COL:xticlabels(1)

If the file contains both magnitude and range information for each value, then error bars can be added to the plot. The following commands will add error bars extending from (y-<error>) to (y+<error>), capped by horizontal bar ends drawn the same width as the box itself. The error bars and bar ends are drawn with linewidth 2, using the border linetype from the current fill style.

      set bars fullwidth
      set style fill solid 1 border lt -1
      set style histogram errorbars gap 2 lw 2
      plot for [COL=2:4:2] 'file.dat' using COL:COL+1

To plot the same data as a rowstacked histogram. Just to be different, this example lists the separate columns explicitly rather than using iteration.

      set style histogram rowstacked
      plot 'file.dat' using 2, '' using 4:xtic(1)

This will produce a plot in which each vertical bar corresponds to one row of data. Each vertical bar contains a stack of two segments, corresponding in height to the values found in columns 2 and 4 of the datafile.

Finally, the commands

      set style histogram columnstacked
      plot 'file.dat' using 2, '' using 4

will produce two vertical stacks, one for each column of data. The stack at x=1 will contain a box for each entry in column 2 of the datafile. The stack at x=2 will contain a box for each parallel entry in column 4 of the datafile. Because this interchanges gnuplot’s usual interpretation of input rows and columns, the specification of key titles and x-axis tic labels must also be modified accordingly. See the comments given below.

      set style histogram columnstacked
      plot '' u 5:key(1)            # uses first column to generate key titles
      plot '' u 5 title columnhead  # uses first row to generate xtic labels

Note that the two examples just given present exactly the same data values, but in different formats.