---
name: "pshistogram"
section: "1gmt"
platform: "linux"
package: "gmt-common"
version: "5.4.5+dfsg-2"
release: "Debian 10 (Buster)"
platforms: ["linux"]
url: "https://new.carta.tech/pshistogram/1gmt"
---

# pshistogram(1gmt)

Calculate and plot histograms

## NAME

pshistogram - Calculate and plot histograms

## SYNOPSIS

**pshistogram** \[ *table* \]  **-Jx**\|**X***parameters*\
  **-W***bin\_width*\[**+l**\|**h**\|**b**\] \[  **-A** \] \[  **-B**\[**p**\|**s**\]*parameters* \] \[  **-C***cpt* \] \[  **-D**\[**+b**\]\[**+f***font*\]\[**+o***off*\]\[**+r**\] \] \[  **-F** \] \[  **-G***fill* \] \[  **-Jz**\|**Z***parameters* \] \[  **-I**\[**o**\|**O**\] \] \[  **-K** \] \[  **-L***pen* \] \[  **-N**\[*mode*\]\[**+p***pen*\] \] \[  **-O** \] \[ **-P** \] \[  **-Q** \] \[  **-R***region* \] \[  **-S** \] \[  **-U**\[*stamp*\] \] \[  **-V**\[*level*\] \] \[  **-X***x\_offset* \] \[  **-Y***y\_offset* \] \[  **-Z**\[*type*\]\[**+w**\] \] \[ **-bi**binary \] \[ **-di**nodata \] \[ **-e**regexp \] \[ **-f**flags \] \[ **-h**headers \] \[ **-i**flags \] \[ **-p**flags \] \[ **-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).

- **-W***bin\_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.

- **-C***cpt*

  Give a CPT. The mid x-value for each bar is used to look-up the bar color.

- **-D**\[**+b**\]\[**+f***font*\]\[**+o***off*\]\[**+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\].

- **-G***fill*

  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**\|**Z***parameters* (more ...)

  Set z-axis scaling; same syntax as **-Jx**.

- **-K** (more ...)

  Do not finalize the PostScript plot.

- **-L***pen*

  Draw bar outline using the specified pen thickness. \[Default is no outline\].

- **-N**\[*mode*\]\[**+p***pen*\]

  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***xmin*/*xmax*/*ymin*/*ymax*\[**+r**\]\[**+u***unit*\] (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\].

- **-di***nodata* (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**\]\[**+r***remark*\]\[**+r***title*\] (more ...)

  Skip or produce header record(s).

- **-i***cols*\[**+l**\]\[**+s***scale*\]\[**+o***offset*\]\[,*...*\] (more ...)

  Select input columns and transformations (0 is first column).

- **-p**\[**x**\|**y**\|**z**\]*azim*\[/*elev*\[/*zlevel*\]\]\[**+w***lon0*/*lat0*\[/*z0*\]\]\[**+v***x0*/*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., **-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, gmtcolors, psbasemap, psrose, psxy

## COPYRIGHT

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