Provided by: gmt_4.5.11-1build1_amd64 bug

NAME

       pshistogram - Bin data and plot histograms

SYNOPSIS

       pshistogram  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 ]

DESCRIPTION

       pshistogram  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 histogram may also be specified.

       file   ASCII [or binary, see -b] datafile. If no file  is  given,  pshistogram  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 vertically 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 system].

       -P     Selects  Portrait  plotting  mode  [Default is Landscape, see gmtdefaults 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  latitude).   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  delimiters  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 column 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 + frequency_percent), 4 = log10 (1.0 + count),
              5 = log10 (1.0 + frequency_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  geographical  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
              (absolute 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  polygons.   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  background  colors  (use  color = - for
              transparency).  See GMT Cookbook & Technical Reference Appendix E  for  information
              on individual 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
              hexadecimal color code (#rrggbb, as used in HTML).  See the gmtcolors  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 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:

       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 calculated.  Instead, specify your interval
       in the same units as the current setting of TIME_UNIT.

SEE ALSO

       GMT(1), gmtcolors(5), psbasemap(1), psrose(1), psxy(1)