pshistogram(1)

1PSHISTOGRAM(1)                        GMT                       PSHISTOGRAM(1)
2
3
4

NAME

6       pshistogram - Calculate and plot histograms
7

SYNOPSIS

9       pshistogram [ table ]  -Jx|Xparameters
10        -Wbin_width[+l|h|b]  [   -A  ]  [   -B[p|s]parameters  ]  [  -Ccpt ] [
11       -D[+b][+ffont][+ooff][+r] ] [  -F ] [  -Gfill ] [  -Jz|Zparameters ]  [
12       -I[o|O]  ] [  -K ] [  -Lpen ] [  -N[mode][+ppen] ] [  -O ] [ -P ] [  -Q
13       ] [  -Rregion ] [  -S ] [  -U[stamp] ] [  -V[level] ] [  -Xx_offset ] [
14       -Yy_offset ] [  -Z[type][+w] ] [ -bibinary ] [ -dinodata ] [ -eregexp ]
15       [ -fflags ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -ttransp ]
16
17       Note: No space is allowed between the option flag  and  the  associated
18       arguments.
19

DESCRIPTION

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

REQUIRED ARGUMENTS

28       -Jx    xscale[/yscale] (Linear scale(s) in distance unit/data unit).
29
30       -Wbin_width[+l|h|b]
31              Sets  the  bin width used for histogram calculations.  The modi‐
32              fiers specify the handling of extreme values that  fall  outside
33              the  range set by -R.  By default these values are ignored.  Use
34              +b to let these values be included in the first  or  last  bins.
35              To  only  include  extreme values below first bin into the first
36              bin, use +l, and to only include extreme values above  the  last
37              bin into that last bin, use +h.
38

OPTIONAL ARGUMENTS

40       table  One  or  more ASCII (or binary, see -bi[ncols][type]) data table
41              file(s) holding a number of data columns. If no tables are given
42              then we read from standard input.
43
44       -A     Plot  the  histogram  horizontally from x = 0 [Default is verti‐
45              cally from y = 0].  The plot dimensions remain the same, but the
46              two axes are flipped.
47
48       -B[p|s]parameters (more ...)
49              Set map boundary frame and axes attributes.
50
51       -Ccpt  Give  a CPT. The mid x-value for each bar is used to look-up the
52              bar color.
53
54       -D[+b][+ffont][+ooff][+r]
55              Annotate each bar with the count it represents.  Append  any  of
56              the  following modifiers: Use +b to place the labels beneath the
57              bars instead of above; use +f to change to another font than the
58              default annotation font; use +o to change the offset between bar
59              and label [6p]; use +r to rotate the labels from  horizontal  to
60              vertical.
61
62       -F     Center bin on each value. [Default is left edge].
63
64       -Gfill Select filling of bars [Default is no fill].
65
66       -I[o|O]
67              Inquire  about min/max x and y after binning. The xmin xmax ymin
68              ymax is output; no plotting is done. Append o to output an ASCII
69              table  of the resulting x,y data instead. Upper case O will out‐
70              put all x,y bin data even when y == 0.
71
72       -Jz|Zparameters (more ...)
73              Set z-axis scaling; same syntax as -Jx.
74
75       -K (more ...)
76              Do not finalize the PostScript plot.
77
78       -Lpen  Draw bar outline using the specified pen thickness. [Default  is
79              no outline].
80
81       -N[mode][+ppen]
82              Draw  the  equivalent  normal  distribution;  append desired pen
83              [0.5p,black].  The mode selects which central location and scale
84              to use:
85
86              · 0 = mean and standard deviation [Default];
87
88              · 1 = median and L1 scale;
89
90              · 2 = LMS mode and scale.
91
92              The -N option may be repeated to draw several of these curves.
93
94       -O (more ...)
95              Append to existing PostScript plot.
96
97       -P (more ...)
98              Select "Portrait" plot orientation.
99
100       -Q     Draw a cumulative histogram.
101
102       -Rxmin/xmax/ymin/ymax[+r][+uunit] (more ...)
103              Specify the region of interest.
104
105       For perspective view p, optionally append /zmin/zmax. (more ...) If not
106       given, pshistogram will automatically find reasonable  values  for  the
107       region.
108
109       -S     Draws  a stairs-step diagram which does not include the internal
110              bars of the default histogram.
111
112       -U[[just]/dx/dy/][c|label] (more ...)
113              Draw GMT time stamp logo on plot.
114
115       -V[level] (more ...)
116              Select verbosity level [c].
117
118       -X[a|c|f|r][x-shift[u]]
119
120       -Y[a|c|f|r][y-shift[u]] (more ...)
121              Shift plot origin.
122
123       -Z[type][+w]
124              Choose between 6 types of histograms:
125
126              · 0 = counts [Default]
127
128              · 1 = frequency_percent
129
130              · 2 = log (1.0 + count)
131
132              · 3 = log (1.0 + frequency_percent)
133
134              · 4 = log10 (1.0 + count)
135
136              · 5 = log10 (1.0 + frequency_percent).
137
138              To use weights provided as a second data column instead of  pure
139              counts, append +w.
140
141       -bi[ncols][t] (more ...)
142              Select native binary input. [Default is 2 input columns].
143
144       -dinodata (more ...)
145              Replace input columns that equal nodata with NaN.
146
147       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
148              Only accept data records that match the given pattern.
149
150       -f[i|o]colinfo (more ...)
151              Specify data types of input and/or output columns.
152
153       -h[i|o][n][+c][+d][+rremark][+rtitle] (more ...)
154              Skip or produce header record(s).
155
156       -icols[+l][+sscale][+ooffset][,...] (more ...)
157              Select input columns and transformations (0 is first column).
158
159       -p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more ...)
160              Select perspective view.
161
162       -t[transp] (more ...)
163              Set PDF transparency level in percent.
164
165       -^ or just -
166              Print  a  short  message  about  the syntax of the command, then
167              exits (NOTE: on Windows just use -).
168
169       -+ or just +
170              Print an extensive usage (help) message, including the  explana‐
171              tion  of  any  module-specific  option  (but  not the GMT common
172              options), then exits.
173
174       -? or no arguments
175              Print a complete usage (help) message, including the explanation
176              of all options, then exits.
177

EXAMPLES

179       To  draw  a  histogram  of the data v3206.t containing seafloor depths,
180       using a 250 meter bin width, center bars, and draw bar outline, use:
181
182              gmt pshistogram v3206.t -JXh -W250 -F -LP0.5p -V > plot.ps
183
184       If you know the distribution of your data, you may  explicitly  specify
185       range  and  scales. E.g., to plot a histogram of the y-values (2nd col‐
186       umn) in the file errors.xy using a 1 meter bin width, plot from -10  to
187       +10  meters  @  0.75  cm/m,  annotate every 2 m and 100 counts, and use
188       black bars, run:
189
190              gmt pshistogram errors.xy -W1 -R-10/10/0/0 -Jxc/0.01c \
191                              -Bx2+lError -By100+lCounts -Gblack -i1 -V > plot.ps
192
193       Since no y-range was specified, pshistogram will calculate ymax in even
194       increments of 100.
195

BUGS

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

COPYRIGHT

206       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe
207
208
209
210
2115.4.5                            Feb 24, 2019                   PSHISTOGRAM(1)