Calculate and plot histograms


gmt histogram [ table ] -Jx|Xparameters -T[min/max/]inc[n] | -Tfile|list [ -A ] [ -B[p|s]parameters ] [ -Ccpt ] [ -D[+b][+ffont][+ooff][+r] ] [ -F ] [ -Gfill ] [ -Jz|Zparameters ] [ -I[o|O] ] [ -Ll|h|b] ] [ -N[mode][+ppen] ] [ -Qr ] [ -Rregion ] [ -S ] [ -U[stamp] ] [ -V[level] ] [ -Wpen ] [ -Xx_offset ] [ -Yy_offset ] [ -Z[type][+w] ] [ -bibinary ] [ -dinodata ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -ttransp ]

Note: No space is allowed between the option flag and the associated arguments.


histogram reads file [or standard input] and examines the first data column (or one set by -i) to calculate histogram parameters based on the bin-width provided. Using these parameters, scaling, and optional range parameters it will plot the histogram. A cumulative histogram may also be specified.

Required Arguments

xscale[/yscale] (Linear scale(s) in distance unit/data unit).
-T[min/max/]inc[n] | -Tfile|list
Make evenly spaced array of bin boundaries from min to max by inc. If min/max are not given then we default to the range in -R. For details on array creation, see Generate 1D Array.

Optional Arguments

One or more ASCII (or binary, see -bi[ncols][type]) data table file(s) holding a number of data columns. If no tables are given then we read from standard input.
Plot the histogram horizontally from x = 0 [Default is vertically from y = 0]. The plot dimensions remain the same, but the two axes are flipped.
-B[p|s]parameters (more ...)
Set map boundary frame and axes attributes.
Give a CPT. The mid x-value for each bar is used to look-up the bar color.
Annotate each bar with the count it represents. Append any of the following modifiers: Use +b to place the labels beneath the bars instead of above; use +f to change to another font than the default annotation font; use +o to change the offset between bar and label [6p]; use +r to rotate the labels from horizontal to vertical.
Center bin on each value. [Default is left edge].
-Gfill (more ...)
Select filling of bars [Default is no fill].
Inquire about min/max x and y after binning. The xmin xmax ymin ymax is output; no plotting is done. Append o to output an ASCII table of the resulting x,y data instead. Upper case O will output all x,y bin data even when y == 0.
-Jz|Zparameters (more ...)
Set z-axis scaling; same syntax as -Jx.
The modifiers specify the handling of extreme values that fall outside the range set by -T. By default these values are ignored. Append b to let these values be included in the first or last bins. To only include extreme values below first bin into the first bin, use l, and to only include extreme values above the last bin into that last bin, use h.

Draw the equivalent normal distribution; append desired pen [0.5p,black]. The mode selects which central location and scale to use:

  • 0 = mean and standard deviation [Default];
  • 1 = median and L1 scale;
  • 2 = LMS mode and scale.

The -N option may be repeated to draw several of these curves.

Draw a cumulative histogram. Append r to instead compute the reverse cumulative histogram.
-Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
Specify the region of interest.

For perspective view p, optionally append /zmin/zmax. (more ...) If not given, histogram will automatically find reasonable values for the region.

Draws a stairs-step diagram which does not include the internal bars of the default histogram.
-U[[just]/dx/dy/][c|label] (more ...)
Draw GMT time stamp logo on plot.
-V[level] (more ...)
Select verbosity level [c].
Draw bar outline (or stair-case curve) using the specified pen thickness. [Default is no outline].


-Y[a|c|f|r][y-shift[u]] (more ...)
Shift plot origin.

Choose between 6 types of histograms:

  • 0 = counts [Default]
  • 1 = frequency_percent
  • 2 = log (1.0 + count)
  • 3 = log (1.0 + frequency_percent)
  • 4 = log10 (1.0 + count)
  • 5 = log10 (1.0 + frequency_percent).

To use weights provided as a second data column instead of pure counts, append +w.

-bi[ncols][t] (more ...)
Select native binary input. [Default is 2 input columns].
-dinodata (more ...)
Replace input columns that equal nodata with NaN.
-e[~]“pattern” | -e[~]/regexp/[i] (more ...)
Only accept data records that match the given pattern.
-f[i|o]colinfo (more ...)
Specify data types of input and/or output columns.
-h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
Skip or produce header record(s).
-icols[+l][+sscale][+ooffset][,...] (more ...)
Select input columns and transformations (0 is first column).
-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
Select perspective view.
-t[transp] (more ...)
Set PDF transparency level in percent.
-^ or just -
Print a short message about the syntax of the command, then exits (NOTE: on Windows just use -).
-+ or just +
Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exits.
-? or no arguments
Print a complete usage (help) message, including the explanation of all options, then exits.

Generate 1D Array

Make an evenly spaced coordinate array from min to max in steps of inc. Append +b if we should take log2 of min and max and build an equidistant log2-array using inc. Append +l if we should take log10 of min and max and build an array where inc can be 1 (every magnitude), 2, (1, 2, 5 times magnitude) or 3 (1-9 times magnitude). Append +n if inc is meant to indicate the number of equidistant coordinates instead. Alternatively, give a file with output coordinates in the first column, or provide a comma-separated list of coordinates.

If the module allows you to set up an absolute time series, append a valid time unit from the list year, month, week, day, hour, minute, and second to the given increment. Note: The internal time unit is still controlled independently by TIME_UNIT.

Likewise, if the module allows you to set up a spatial distance series (with distance computed from the first two data columns), specify the increment as [±][unit]inc, where - means fast (Flat Earth) and + means slow (ellipsoidal) distance calculations [great circle], and append a geospatial distance unit from the list degree (arc), minute (arc), second (arc), meter, foot, kilometer, Miles (statute), nautical miles, or survey foot. For Cartesian distances, you must use the special unit c.


To draw a histogram of the data v3206.t containing seafloor depths, using a 250 meter bin width, center bars, and draw bar outline, use:

gmt histogram v3206.t -JXh -T250 -F -W0.5p -V -pdf plot

If you know the distribution of your data, you may explicitly specify range and scales. E.g., to plot a histogram of the y-values (2nd column) in the file errors.xy using a 1 meter bin width, plot from -10 to +10 meters @ 0.75 cm/m, annotate every 2 m and 100 counts, and use black bars, run:

gmt histogram errors.xy -T1 -R-10/10/0/0 -Jxc/0.01c
              -Bx2+lError -By100+lCounts -Gblack -i1 -V -pdf plot

Since no y-range was specified, histogram will calculate ymax in even increments of 100.