1PSHISTOGRAM(1) Generic Mapping Tools PSHISTOGRAM(1)
2
6 pshistogram - Bin data and plot histograms
7
9 pshistogram file -Jx|Xparameters -Wbin_width [ -A ] [ -B[p|s]parameters
10 ] [ [ -Ccptfile ] ] [ -Eazimuth/elevation ] [ -F ] [ -Gfill ] [
11 -H[i][nrec] ] [ -Jz|Zparameters ] [ -I[o|O] ] [ -K ] [ -Lpen ] [ -O ] [
12 -P ] [ -Q ] [ -Rxmin/xmax/ymin/ymax[r] ] [ -S ] [ -Tcol ] [
13 -U[just/dx/dy/][c|label] ] [ -V ] [ -X[a|c|r][x-shift[u]] ] [
14 -Y[a|c|r][y-shift[u]] ] [ -Ztype ] [ -ccopies ] [
15 -bi[s|S|d|D[ncol]|c[var1/...]] ] [ -f[i|o]colinfo ]
16
18 pshistogram reads file [or standard input] and examines data column col
19 to calculate histogram parameters based on the bin-width provided.
20 Using these parameters, scaling, and optional range parameters it will
21 generate PostScript code that plots a histogram. A cumulative his‐
22 togram may also be specified.
23 file ASCII [or binary, see -b] datafile. If no file is given, pshis‐
25 togram will read standard input.
26 -Jx xscale[/yscale] (Linear scale(s) in distance unit/data unit).
28 -W Sets the bin width used for histogram calculations.
30
32 No space between the option flag and the associated arguments.
33 -A Plot the histogram horizontally from x = 0 [Default is verti‐
35 cally from y = 0].
36 -B Sets map boundary annotation and tickmark intervals; see the
38 psbasemap man page for all the details.
39 -C Give a color palette file. The mid x-value for each bar is used
41 to look-up the bar color.
42 -E Sets the viewpoint's azimuth and elevation (for perspective
44 view) [180/90].
45 -F Center bin on each value. [Default is left edge].
47 -G Select filling of bars [Default is no fill]. (See SPECIFYING
49 FILL below).
50 -H Input file(s) has Header record(s). Number of header records
52 can be changed by editing your .gmtdefaults4 file. If used, GMT
53 default is 1 header record. Use -Hi if only input data should
54 have header records [Default will write out header records if
55 the input data have them]. Blank lines and lines starting with #
56 are always skipped.
57 -I Inquire about min/max x and y after binning. No plotting is
59 done. Append o to output an ASCII table of the resulting x,y
60 data to stdout. Alternatively, append O to output all x,y bin
61 data even when y == 0.
62 -K More PostScript code will be appended later [Default terminates
64 the plot system].
65 -L Draw bar outline using the specified pen thickness. [Default is
67 no outline]. (See SPECIFYING PENS below).
68 -O Selects Overlay plot mode [Default initializes a new plot sys‐
70 tem].
71 -P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
73 faults to change this].
74 -Q Draw a cumulative histogram.
76 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
78 geographic regions, these limits correspond to west, east,
79 south, and north and you may specify them in decimal degrees or
80 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
81 and upper right map coordinates are given instead of w/e/s/n.
82 The two shorthands -Rg and -Rd stand for global domain (0/360
83 and -180/+180 in longitude respectively, with -90/+90 in lati‐
84 tude). For calendar time coordinates you may either give (a)
85 relative time (relative to the selected TIME_EPOCH and in the
86 selected TIME_UNIT; append t to -JX|x), or (b) absolute time of
87 the form [date]T[clock] (append T to -JX|x). At least one of
88 date and clock must be present; the T is always required. The
89 date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
90 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
91 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
92 iters and their type and positions must be exactly as indicated
93 (however, input, output and plot formats are customizable; see
94 gmtdefaults). If not given, pshistogram will automatically find
95 reasonable values for the region.
96 -S Draws a stairs-step diagram instead of histogram.
98 -T Specify which column to use for the histogram data. First col‐
100 umn is 0 [0].
101 -U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
103 user may specify the justification of the stamp and where the
104 stamp should fall on the page relative to lower left corner of
105 the plot. For example, BL/0/0 will align the lower left corner
106 of the time stamp with the lower left corner of the plot.
107 Optionally, append a label, or c (which will plot the command
108 string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
109 UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
110 man page for details. The time string will be in the locale set
111 by the environment variable TZ (generally local time).
112 -V Selects verbose mode, which will send progress reports to stderr
114 [Default runs "silently"].
115 -X -Y Shift plot origin relative to the current origin by (x-shift,y-
117 shift) and optionally append the length unit (c, i, m, p). You
118 can prepend a to shift the origin back to the original position
119 after plotting, or prepend r [Default] to reset the current
120 origin to the new location. If -O is used then the default (x-
121 shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
122 r2.5c). Alternatively, give c to align the center coordinate (x
123 or y) of the plot with the center of the page based on current
124 page size.
125 -Z Choose between 6 types of histograms: 0 = counts [Default], 1 =
127 frequency_percent, 2 = log (1.0 + count), 3 = log (1.0 + fre‐
128 quency_percent), 4 = log10 (1.0 + count), 5 = log10 (1.0 + fre‐
129 quency_percent).
130 -bi Selects binary input. Append s for single precision [Default is
132 d (double)]. Uppercase S or D will force byte-swapping.
133 Optionally, append ncol, the number of columns in your binary
134 input file if it exceeds the columns needed by the program. Or
135 append c if the input file is netCDF. Optionally, append
136 var1/var2/... to specify the variables to be read. [Default is
137 2 input columns].
138 -c Specifies the number of plot copies. [Default is 1].
140 -f Special formatting of input and/or output columns (time or geo‐
142 graphical data). Specify i or o to make this apply only to
143 input or output [Default applies to both]. Give one or more
144 columns (or column ranges) separated by commas. Append T (abso‐
145 lute calendar time), t (relative time in chosen TIME_UNIT since
146 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
147 to each column or column range item. Shorthand -f[i|o]g means
148 -f[i|o]0x,1y (geographic coordinates).
149 SPECIFYING PENS
151 pen The attributes of lines and symbol outlines as defined by pen is
152 a comma delimetered list of width, color and texture, each of
153 which is optional. width can be indicated as a measure (points,
154 centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
155 fat[ter|test], or obese. color specifies a grey shade or color
156 (see SPECIFYING COLOR below). texture is a combination of
157 dashes `-' and dots `.'.
158 SPECIFYING FILL
160 fill The attribute fill specifies the solid shade or solid color (see
161 SPECIFYING COLOR below) or the pattern used for filling poly‐
162 gons. Patterns are specified as pdpi/pattern, where pattern
163 gives the number of the built-in pattern (1-90) or the name of a
164 Sun 1-, 8-, or 24-bit raster file. The dpi sets the resolution
165 of the image. For 1-bit rasters: use Pdpi/pattern for inverse
166 video, or append :Fcolor[B[color]] to specify fore- and back‐
167 ground colors (use color = - for transparency). See GMT Cook‐
168 book & Technical Reference Appendix E for information on indi‐
169 vidual patterns.
170 SPECIFYING COLOR
172 color The color of lines, areas and patterns can be specified by a
173 valid color name; by a grey shade (in the range 0-255); by a
174 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
175 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
176 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
177 ors manpage for more information and a full list of color names.
178
180 To draw a histogram of the data v3206.t containing seafloor depths,
181 using a 250 meter bin width, center bars, and draw bar outline, use:
182 pshistogram v3206.t -JXh -W250 -F -LP0.5p -V > plot.ps
184 If you know the distribution of your data, you may explicitly specify
186 range and scales. E.g., to plot a histogram of the y-values (2nd col‐
187 umn) in the file errors.xy using a 1 meter bin width, plot from -10 to
188 +10 meters @ 0.75 cm/m, annotate every 2 m and 100 counts, and use
189 black bars, run:
190 pshistogram errors.xy -W1 -R-10/10/0/0 -Jx0.75c/0.01c
192 -B2:Error:/100:Counts: -Gblack -T1 -V > plot.ps
193 Since no y-range was specified, pshistogram will calculate ymax in even
195 increments of 100.
196
198 The -W option does not yet work properly with time series data (e.g.,
199 -f0T). Thus, such variable intervals as months and years are not cal‐
200 culated. Instead, specify your interval in the same units as the cur‐
201 rent setting of TIME_UNIT.
202
204 GMT(1), psbasemap(1), psrose(1), psxy(1)
205GMT 4.3.1 15 May 2008 PSHISTOGRAM(1)