Histograms

The histograms style is only relevant to 2-d plotting. It produces a bar chart from a sequence of data columns in parallel. 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 5#5n6#6 datacolumns are selected, the first cluster is centered about x=1, and contains 5#5n6#6 boxes whose heights are taken from the first entry in the corresponding 5#5n6#6 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 (p. )).

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 two columns of input for each entry. The first column is treated as the height (y-value) of that box, exactly as for the clustered style. The second column is treated as an error magnitude, and used to generate a vertical error bar at the top of the box. The appearance of the error bar is controlled by the current value of set bars and by the optional 5#5linewidth6#6 specification.

Two styles of stacked histogram are supported, chosen by the command set style histogram {rowstacked4#4columnstacked}. In these styles the data values from the selected columns are collected into stacks of boxes. 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 (p. )).

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 set 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:

To plot a data file containing multiple columns of data as a histogram of clustered boxes (the default style):

     set boxwidth 0.9 relative
     set style data histograms
     set style fill solid 1.0 border -1
     plot 'file.dat' using 2, '' using 4, '' using 6

This will produce a plot with clusters of three 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 'file.dat' using 2, '' using 4, '' using 6:xticlabels(1)

If the file contains both a magnitude and an error estimate for each value, then error bars can be added to the plot. The following commands will add error bars extending from (y-5#5error6#6) to (y+5#5error6#6), capped by horizontal bar ends drawn the same width as the box itself. The error bars and bar ends are drawn in black with linewidth 2.

     set bars fullwidth
     set style histogram errorbars gap 2 lt -1 lw 2
     plot 'file.dat' using 2:3, '' using 4:5, '' using 6:7:xticlabels(1)

To plot the same data as a rowstacked histogram:

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

This will produce a plot in which each vertical bar contains a stack of three segments, corresponding in height to the values found in columns 2, 4 and 6 of the datafile.

Finally, the commands

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

will produce three vertical stacks. 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, and the stack at x=3 a box for each entry of column 6. 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.

     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