pshistogram — GMT 5.1.1 documentation

### Navigation

- index
- next
- previous
- Project Home »
- GMT 5.1.1 documentation »
- PS »
- Search:

# pshistogram

pshistogram - Calculate and plot histograms

## Synopsis

pshistogram [ table ] -Jx|Xparameters -Wbin_width [ -A ] [ -B[p|s]parameters ] [ -Ccptfile ] [ -D[+b][+ffont][+ooff][+r] ] [ -F ] [ -Gfill ] [ -Jz|Zparameters ] [ -I[o|O] ] [ -K ] [ -Lpen ] [ -N[mode][+ppen] ] [ -O ] [-P ] [ -Q ] [ -R[unit]xmin/xmax/ymin/ymax[r] ] [ -S ] [ -U[just/dx/dy/][c|label] ] [ -V[level] ] [ -X[a|c|f|r][x-shift[u]] ] [ -Y[a|c|f|r][y-shift[u]] ] [ -Ztype ] [ -bi[ncols][type][w][+L|+B] ] [ -ccopies ] [ -f[i|o]colinfo ] [ -h[i|o][n][+c][+d][+rremark][+rtitle] ] [ -icols[l][sscale][ooffset][,...] ] [ -p[x|y|z]azim/elev[/zlevel][+wlon0/lat0[/z0]][+vx0/y0] ] [ -t[transp] ]

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
  Sets the bin width used for histogram calculations.

## 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].

-B[p|s]parameters (more ...)
  Set map boundary intervals.
-Ccptfile
  Give a color palette file. 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.

-R[unit]xmin/xmax/ymin/ymax[r] (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.
-Ztype

  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[ncols][type] (more ...)
  Select binary input. [Default is 2 input columns].

-ccopies (more ...)
  Specify number of plot copies [Default is 1].

-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.

-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.

-^
  Print a short message about the syntax of the command, then exits (NOTE: on Windows use just -).
+
  Print an extensive usage (help) message, including the explanation of any module-specific option (but not the GMT common options), then exits.
-?
  Print a complete usage (help) message, including the explanation of options, then exits.
--version
  Print GMT version and exit.
--show-datadir
  Print full path to GMT share directory and exit.

## 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 \
>                     -B2:Error:/100:Counts: -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

### Navigation

- index
- next
- previous
- Project Home »
- GMT 5.1.1 documentation »
- PS »
- Search: