pshistogram man page

pshistogram — Calculate and plot histograms


pshistogram [ table ]  -Jx|Xparameters
-Wbin_width[+l|h|b] [  -A ] [  -B[p|s]parameters ] [  -Ccpt ] [  -D[+b][+ffont][+ooff][+r] ] [  -F ] [  -Gfill ] [  -Jz|Zparameters ] [  -I[o|O] ] [  -K ] [  -Lpen ] [  -N[mode][+ppen] ] [  -O ] [ -P ] [  -Q ] [  -Rregion ] [  -S ] [  -U[stamp] ] [  -V[level] ] [  -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.


pshistogram reads file [or standard input] and examines the first data column (or use -i) to calculate histogram parameters based on the bin-width provided. Using these parameters, scaling, and optional range parameters it will generate PostScript code that plots a histogram. A cumulative histogram may also be specified.

Required Arguments


xscale[/yscale] (Linear scale(s) in distance unit/data unit).


Sets the bin width used for histogram calculations. The modifiers specify the handling of extreme values that fall outside the range set by -R.  By default these values are ignored.  Use +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.

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].


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.

-K (more ...)

Do not finalize the PostScript plot.


Draw bar outline using the specified pen thickness. [Default is no outline].


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.

-O (more ...)

Append to existing PostScript plot.

-P (more ...)

Select "Portrait" plot orientation.


Draw a 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, pshistogram 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].  


-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.


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 pshistogram v3206.t -JXh -W250 -F -LP0.5p -V >

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 pshistogram errors.xy -W1 -R-10/10/0/0 -Jxc/0.01c \
                -Bx2+lError -By100+lCounts -Gblack -i1 -V >

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


The -W option does not yet work properly with time series data (e.g., -f0T). Thus, such variable intervals as months and years are not calculated. Instead, specify your interval in the same units as the current setting of TIME_UNIT.

See Also

gmt, gmtcolors, psbasemap, psrose, psxy


Jun 28, 2018 5.4.4 GMT