pshistogram
pshistogram - Calculate and plot histograms
Synopsis
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[just/dx/dy/][c|label] ]
[ -V[level] ]
[ -Xx_offset ]
[ -Yy_offset ]
[ -Ztype ]
[ -bi<binary> ]
[ -ccopies ]
[ -di<nodata> ]
[ -f<flags> ]
[ -h<headers> ]
[ -i<flags> ]
[ -p<flags> ]
[ -t<transp> ]
Note: No space is allowed between the option flag and the associated arguments.
Description
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
- -Jx
- xscale[/yscale] (Linear scale(s) in distance unit/data unit).
- -Wbin_width[+l|h|b]
- 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
- table
- 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.
- -A
- Plot the histogram horizontally from x = 0 [Default is vertically
from y = 0].
- -B[p|s]parameters (more ...)
- Set map boundary intervals.
- -Ccpt
- Give a CPT file. The mid x-value for each bar is used to
look-up the bar color.
- -D[+b][+ffont][+ooff][+r]
- 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.
- -F
- Center bin on each value. [Default is left edge].
- -Gfill
- Select filling of bars [Default is no fill].
- -I[o|O]
- 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.
- -Lpen
- Draw bar outline using the specified pen thickness. [Default is no outline].
- -N[mode][+ppen]
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.
- -Q
- Draw a cumulative histogram.
- -R[unit]xmin/xmax/ymin/ymax[r] (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.
- -S
- 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].
-X[a|c|f|r][x-shift[u]]
- -Y[a|c|f|r][y-shift[u]] (more ...)
- Shift plot origin.
- -Ztype
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).
- -bi[ncols][t] (more ...)
- Select native binary input. [Default is 2 input columns].
- -ccopies (more ...)
- Specify number of plot copies [Default is 1].
- -dinodata (more ...)
- Replace input columns that equal nodata with NaN.
- -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 (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 use just -).
- -+ 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
options, then exits.
- --version
- Print GMT version and exit.
- --show-datadir
- Print full path to GMT share directory and exit.
Examples
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 > plot.ps
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 > plot.ps
Since no y-range was specified, pshistogram will calculate ymax in even
increments of 100.
Bugs
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.