PSHISTOGRAM(1) Generic Mapping Tools PSHISTOGRAM(1)NAMEpshistogram - Bin data and plot histograms
SYNOPSISpshistogram file -Jx|Xparameters -Wbin_width [ -A ] [ -B[p|s]parameters
] [ -Ccptfile ] [ -Eazimuth/elevation ] [ -F ] [ -Gfill ] [ -H[i][nrec]
] [ -Jz|Zparameters ] [ -I[o|O] ] [ -K ] [ -Lpen ] [ -O ] [ -P ] [ -Q ]
[ -Rxmin/xmax/ymin/ymax[r] ] [ -S ] [ -Tcol ] [
-U[just/dx/dy/][c|label] ] [ -V ] [ -X[a|c|r][x-shift[u]] ] [
-Y[a|c|r][y-shift[u]] ] [ -Ztype ] [ -ccopies ] [
-bi[s|S|d|D[ncol]|c[var1/...]] ] [ -f[i|o]colinfo ]
DESCRIPTIONpshistogram reads file [or standard input] and examines data column col
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 his‐
togram may also be specified.
file ASCII [or binary, see -b] datafile. If no file is given, pshis‐
togram will read standard input.
-Jx xscale[/yscale] (Linear scale(s) in distance unit/data unit).
-W Sets the bin width used for histogram calculations.
OPTIONS
No space between the option flag and the associated arguments.
-A Plot the histogram horizontally from x = 0 [Default is verti‐
cally from y = 0].
-B Sets map boundary annotation and tickmark intervals; see the
psbasemap man page for all the details.
-C Give a color palette file. The mid x-value for each bar is used
to look-up the bar color.
-E Sets the viewpoint's azimuth and elevation (for perspective
view) [180/90].
-F Center bin on each value. [Default is left edge].
-G Select filling of bars [Default is no fill]. (See SPECIFYING
FILL below).
-H Input file(s) has header record(s). If used, the default number
of header records is N_HEADER_RECS. Use -Hi if only input data
should have header records [Default will write out header
records if the input data have them]. Blank lines and lines
starting with # are always skipped.
-I Inquire about min/max x and y after binning. No plotting is
done. Append o to output an ASCII table of the resulting x,y
data to stdout. Alternatively, append O to output all x,y bin
data even when y == 0.
-K More PostScript code will be appended later [Default terminates
the plot system].
-L Draw bar outline using the specified pen thickness. [Default is
no outline]. (See SPECIFYING PENS below).
-O Selects Overlay plot mode [Default initializes a new plot sys‐
tem].
-P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
faults to change this].
-Q Draw a cumulative histogram.
-R xmin, xmax, ymin, and ymax specify the Region of interest. For
geographic regions, these limits correspond to west, east,
south, and north and you may specify them in decimal degrees or
in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
and upper right map coordinates are given instead of w/e/s/n.
The two shorthands -Rg and -Rd stand for global domain (0/360
and -180/+180 in longitude respectively, with -90/+90 in lati‐
tude). Alternatively, specify the name of an existing grid file
and the -R settings (and grid spacing, if applicable) are copied
from the grid. For calendar time coordinates you may either
give (a) relative time (relative to the selected TIME_EPOCH and
in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
time of the form [date]T[clock] (append T to -JX|x). At least
one of date and clock must be present; the T is always required.
The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
string must be of the form hh:mm:ss[.xxx]. The use of delim‐
iters and their type and positions must be exactly as indicated
(however, input, output and plot formats are customizable; see
gmtdefaults). 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.
-T Specify which column to use for the histogram data. First col‐
umn is 0 [0].
-U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
user may specify the justification of the stamp and where the
stamp should fall on the page relative to lower left corner of
the plot. For example, BL/0/0 will align the lower left corner
of the time stamp with the lower left corner of the plot.
Optionally, append a label, or c (which will plot the command
string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
man page for details. The time string will be in the locale set
by the environment variable TZ (generally local time).
-V Selects verbose mode, which will send progress reports to stderr
[Default runs "silently"].
-X -Y Shift plot origin relative to the current origin by (x-shift,y-
shift) and optionally append the length unit (c, i, m, p). You
can prepend a to shift the origin back to the original position
after plotting, or prepend r [Default] to reset the current
origin to the new location. If -O is used then the default (x-
shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
r2.5c). Alternatively, give c to align the center coordinate (x
or y) of the plot with the center of the page based on current
page size.
-Z Choose between 6 types of histograms: 0 = counts [Default], 1 =
frequency_percent, 2 = log (1.0 + count), 3 = log (1.0 + fre‐
quency_percent), 4 = log10 (1.0 + count), 5 = log10 (1.0 + fre‐
quency_percent).
-bi Selects binary input. Append s for single precision [Default is
d (double)]. Uppercase S or D will force byte-swapping.
Optionally, append ncol, the number of columns in your binary
input file if it exceeds the columns needed by the program. Or
append c if the input file is netCDF. Optionally, append
var1/var2/... to specify the variables to be read. [Default is
2 input columns].
-c Specifies the number of plot copies. [Default is 1].
-f Special formatting of input and/or output columns (time or geo‐
graphical data). Specify i or o to make this apply only to
input or output [Default applies to both]. Give one or more
columns (or column ranges) separated by commas. Append T (abso‐
lute calendar time), t (relative time in chosen TIME_UNIT since
TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
to each column or column range item. Shorthand -f[i|o]g means
-f[i|o]0x,1y (geographic coordinates).
SPECIFYING PENS
pen The attributes of lines and symbol outlines as defined by pen is
a comma delimetered list of width, color and texture, each of
which is optional. width can be indicated as a measure (points,
centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
fat[ter|test], or obese. color specifies a gray shade or color
(see SPECIFYING COLOR below). texture is a combination of
dashes `-' and dots `.'.
SPECIFYING FILL
fill The attribute fill specifies the solid shade or solid color (see
SPECIFYING COLOR below) or the pattern used for filling poly‐
gons. Patterns are specified as pdpi/pattern, where pattern
gives the number of the built-in pattern (1-90) or the name of a
Sun 1-, 8-, or 24-bit raster file. The dpi sets the resolution
of the image. For 1-bit rasters: use Pdpi/pattern for inverse
video, or append :Fcolor[B[color]] to specify fore- and back‐
ground colors (use color = - for transparency). See GMT Cook‐
book & Technical Reference Appendix E for information on indi‐
vidual patterns.
SPECIFYING COLOR
color The color of lines, areas and patterns can be specified by a
valid color name; by a gray shade (in the range 0-255); by a
decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
ors manpage for more information and a full list of color names.
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:
pshistogram v3206.t -JX h -W 250 -F -L P0.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 col‐
umn) 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:
pshistogram errors.xy -W 1 -R-10/10/0/0 -Jx 0.75c/0.01c -B
2:Error:/100:Counts: -G black -T 1 -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.,
-f 0T). Thus, such variable intervals as months and years are not cal‐
culated. Instead, specify your interval in the same units as the cur‐
rent setting of TIME_UNIT.
SEE ALSOGMT(1), gmtcolors(5), psbasemap(1), psrose(1), psxy(1)GMT 4.5.14 1 Nov 2015 PSHISTOGRAM(1)
