NAME

       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[stamp]
       ] [  -V[level] ] [  -Xx_offset ] [  -Yy_offset  ]  [   -Z[type][+w]  ]  [  -bibinary  ]  [
       -dinodata ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -pflags ] [ -ttransp ]

       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].  The
              plot dimensions remain the same, but the two axes are flipped.

       -B[p|s]parameters (more ...)
              Set map boundary frame and axes attributes.

       -Ccpt  Give a CPT. 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.

       -Rxmin/xmax/ymin/ymax[+r][+uunit] (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.

       -Z[type][+w]
              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).

              To use weights provided as a second data column instead of pure counts, append +w.

       -bi[ncols][t] (more ...)
              Select native binary input. [Default is 2 input columns].

       -dinodata (more ...)
              Replace input columns that equal nodata with NaN.

       -e[~]"pattern" | -e[~]/regexp/[i] (more ...)
              Only accept data records that match the given pattern.

       -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 and transformations (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
              just use -).

       -+ 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 all options,
              then exits.

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.

SEE ALSO

       gmt, gmtcolors, psbasemap, psrose, psxy

COPYRIGHT

       2019, P. Wessel, W. H. F. Smith, R. Scharroo, J. Luis, and F. Wobbe