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 ] [ -H[i][nrec]
11 ] [ -Jz|Zparameters ] [ -I[o|O] ] [ -K ] [ -Lpen ] [ -O ] [ -P ] [ -Q ]
12 [ -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). If used, the default number
52 of header records is N_HEADER_RECS. Use -Hi if only input data
53 should have header records [Default will write out header
54 records if the input data have them]. Blank lines and lines
55 starting with # are always skipped.
56 -I Inquire about min/max x and y after binning. No plotting is
58 done. Append o to output an ASCII table of the resulting x,y
59 data to stdout. Alternatively, append O to output all x,y bin
60 data even when y == 0.
61 -K More PostScript code will be appended later [Default terminates
63 the plot system].
64 -L Draw bar outline using the specified pen thickness. [Default is
66 no outline]. (See SPECIFYING PENS below).
67 -O Selects Overlay plot mode [Default initializes a new plot sys‐
69 tem].
70 -P Selects Portrait plotting mode [Default is Landscape, see gmtde‐
72 faults to change this].
73 -Q Draw a cumulative histogram.
75 -R xmin, xmax, ymin, and ymax specify the Region of interest. For
77 geographic regions, these limits correspond to west, east,
78 south, and north and you may specify them in decimal degrees or
79 in [+-]dd:mm[:ss.xxx][W|E|S|N] format. Append r if lower left
80 and upper right map coordinates are given instead of w/e/s/n.
81 The two shorthands -Rg and -Rd stand for global domain (0/360
82 and -180/+180 in longitude respectively, with -90/+90 in lati‐
83 tude). Alternatively, specify the name of an existing grid file
84 and the -R settings (and grid spacing, if applicable) are copied
85 from the grid. For calendar time coordinates you may either
86 give (a) relative time (relative to the selected TIME_EPOCH and
87 in the selected TIME_UNIT; append t to -JX|x), or (b) absolute
88 time of the form [date]T[clock] (append T to -JX|x). At least
89 one of date and clock must be present; the T is always required.
90 The date string must be of the form [-]yyyy[-mm[-dd]] (Gregorian
91 calendar) or yyyy[-Www[-d]] (ISO week calendar), while the clock
92 string must be of the form hh:mm:ss[.xxx]. The use of delim‐
93 iters and their type and positions must be exactly as indicated
94 (however, input, output and plot formats are customizable; see
95 gmtdefaults). If not given, pshistogram will automatically find
96 reasonable values for the region.
97 -S Draws a stairs-step diagram which does not include the internal
99 bars of the default histogram.
100 -T Specify which column to use for the histogram data. First col‐
102 umn is 0 [0].
103 -U Draw Unix System time stamp on plot. By adding just/dx/dy/, the
105 user may specify the justification of the stamp and where the
106 stamp should fall on the page relative to lower left corner of
107 the plot. For example, BL/0/0 will align the lower left corner
108 of the time stamp with the lower left corner of the plot.
109 Optionally, append a label, or c (which will plot the command
110 string.). The GMT parameters UNIX_TIME, UNIX_TIME_POS, and
111 UNIX_TIME_FORMAT can affect the appearance; see the gmtdefaults
112 man page for details. The time string will be in the locale set
113 by the environment variable TZ (generally local time).
114 -V Selects verbose mode, which will send progress reports to stderr
116 [Default runs "silently"].
117 -X -Y Shift plot origin relative to the current origin by (x-shift,y-
119 shift) and optionally append the length unit (c, i, m, p). You
120 can prepend a to shift the origin back to the original position
121 after plotting, or prepend r [Default] to reset the current
122 origin to the new location. If -O is used then the default (x-
123 shift,y-shift) is (0,0), otherwise it is (r1i, r1i) or (r2.5c,
124 r2.5c). Alternatively, give c to align the center coordinate (x
125 or y) of the plot with the center of the page based on current
126 page size.
127 -Z Choose between 6 types of histograms: 0 = counts [Default], 1 =
129 frequency_percent, 2 = log (1.0 + count), 3 = log (1.0 + fre‐
130 quency_percent), 4 = log10 (1.0 + count), 5 = log10 (1.0 + fre‐
131 quency_percent).
132 -bi Selects binary input. Append s for single precision [Default is
134 d (double)]. Uppercase S or D will force byte-swapping.
135 Optionally, append ncol, the number of columns in your binary
136 input file if it exceeds the columns needed by the program. Or
137 append c if the input file is netCDF. Optionally, append
138 var1/var2/... to specify the variables to be read. [Default is
139 2 input columns].
140 -c Specifies the number of plot copies. [Default is 1].
142 -f Special formatting of input and/or output columns (time or geo‐
144 graphical data). Specify i or o to make this apply only to
145 input or output [Default applies to both]. Give one or more
146 columns (or column ranges) separated by commas. Append T (abso‐
147 lute calendar time), t (relative time in chosen TIME_UNIT since
148 TIME_EPOCH), x (longitude), y (latitude), or f (floating point)
149 to each column or column range item. Shorthand -f[i|o]g means
150 -f[i|o]0x,1y (geographic coordinates).
151 SPECIFYING PENS
153 pen The attributes of lines and symbol outlines as defined by pen is
154 a comma delimetered list of width, color and texture, each of
155 which is optional. width can be indicated as a measure (points,
156 centimeters, inches) or as faint, thin[ner|nest], thick[er|est],
157 fat[ter|test], or obese. color specifies a gray shade or color
158 (see SPECIFYING COLOR below). texture is a combination of
159 dashes `-' and dots `.'.
160 SPECIFYING FILL
162 fill The attribute fill specifies the solid shade or solid color (see
163 SPECIFYING COLOR below) or the pattern used for filling poly‐
164 gons. Patterns are specified as pdpi/pattern, where pattern
165 gives the number of the built-in pattern (1-90) or the name of a
166 Sun 1-, 8-, or 24-bit raster file. The dpi sets the resolution
167 of the image. For 1-bit rasters: use Pdpi/pattern for inverse
168 video, or append :Fcolor[B[color]] to specify fore- and back‐
169 ground colors (use color = - for transparency). See GMT Cook‐
170 book & Technical Reference Appendix E for information on indi‐
171 vidual patterns.
172 SPECIFYING COLOR
174 color The color of lines, areas and patterns can be specified by a
175 valid color name; by a gray shade (in the range 0-255); by a
176 decimal color code (r/g/b, each in range 0-255; h-s-v, ranges
177 0-360, 0-1, 0-1; or c/m/y/k, each in range 0-1); or by a hexa‐
178 decimal color code (#rrggbb, as used in HTML). See the gmtcol‐
179 ors manpage for more information and a full list of color names.
180
182 To draw a histogram of the data v3206.t containing seafloor depths,
183 using a 250 meter bin width, center bars, and draw bar outline, use:
184 pshistogram v3206.t -JXh -W250 -F -LP0.5p -V > plot.ps
186 If you know the distribution of your data, you may explicitly specify
188 range and scales. E.g., to plot a histogram of the y-values (2nd col‐
189 umn) in the file errors.xy using a 1 meter bin width, plot from -10 to
190 +10 meters @ 0.75 cm/m, annotate every 2 m and 100 counts, and use
191 black bars, run:
192 pshistogram errors.xy -W1 -R-10/10/0/0 -Jx0.75c/0.01c
194 -B2:Error:/100:Counts: -Gblack -T1 -V > plot.ps
195 Since no y-range was specified, pshistogram will calculate ymax in even
197 increments of 100.
198
200 The -W option does not yet work properly with time series data (e.g.,
201 -f0T). Thus, such variable intervals as months and years are not cal‐
202 culated. Instead, specify your interval in the same units as the cur‐
203 rent setting of TIME_UNIT.
204
206 GMT(1), gmtcolors(5), psbasemap(1), psrose(1), psxy(1)
207GMT 4.5.6 10 Mar 2011 PSHISTOGRAM(1)