# histogram¶

Calculate and plot histograms

## Synopsis¶

**gmt histogram** [ *table* ] **-J****x**|**X***parameters*
**-T**[*min/max*/]*inc*[**+i**|**n**] |**-T***file*|*list*
[ **-A** ]
[ **-B**[**p**|**s**]*parameters* ]
[ **-C***cpt*[**+b**] ]
[ **-D**[**+b**][**+f***font*][**+o***off*][**+r**] ]
[ **-E***width*[**+o***offset*] ]
[ **-F** ]
[ **-G***fill* ]
[ **-I**[**o**|**O**] ]
[ **-Jz**|**Z***parameters* ]
[ **-L****l**|**h**|**b**] ]
[ **-N**[*mode*][**+p***pen*] ]
[ **-Q****r** ]
[ **-R***region* ]
[ **-S** ]
[ **-U**[*stamp*] ]
[ **-V**[*level*] ]
[ **-W***pen* ]
[ **-X**[**a**|**c**|**f**|**r**][*xshift*] ]
[ **-Y**[**a**|**c**|**f**|**r**][*yshift*] ]
[ **-Z**[*type*][**+w**] ]
[ **-bi**binary ]
[ **-di**nodata ]
[ **-e**regexp ]
[ **-f**flags ]
[ **-h**headers ]
[ **-i**flags ]
[ **-l**flags ]
[ **-p**flags ]
[ **-qi**flags ]
[ **-t**transp ]
[ **-w**flags ]
[ **--PAR**=*value* ]

**Note:** No space is allowed between the option flag and the associated arguments.

## Description¶

Reads *file* [or standard input] and examines the first
data column (or one set by **-i**) to calculate histogram parameters based on
the bin-width provided. Using these parameters, scaling, and optional
range parameters it will plot the histogram. A cumulative histogram may also be specified.

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

**-Jx***xscale*[/*yscale*] (Linear scale(s) in distance unit/data unit), or**-JX**with*width*[/*height*] dimensions.

**-T**[*min/max*/]*inc*[**+n**] |**-T***file*|*list*Make evenly spaced array of bin boundaries from

*min*to*max*by*inc*. If*min/max*are not given then we default to the range in**-R**. For details on array creation, see Generate 1D Array.

## Optional Arguments¶

**-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*Set map boundary frame and axes attributes. (See full description) (See cookbook information).

**-C***cpt*[**+b**]Give a CPT. The mid-coordinate for each bar is used to look up the bar color. Alternatively, append

**+b**to use the*bin*value as the look-up value, unless**-Z**involves percentages, in which case the look-up value is the*percentage*computed. If we are in modern mode and no*cpt*is given then we select the current CPT.

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

**-E***width*[**+o***offset*]Use an alternative histogram bar width than the default set via

**-T**, and optionally shift all bars by an*offset*. Here*width*is either an alternative width in data units, or the user may append a valid plot dimension unit (**c**|**i**|**p**) for a fixed dimension instead. Optionally, all bins may be shifted along the axis by*offset*. As for*width*, it may be given in data units of plot dimension units by appending the relevant unit.

**-F**Center bin on each value. [Default is left edge].

**-G***fill*(more …)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*Set z-axis scaling; same syntax as -Jx.

**-Ll**|**h**|**b**The modifiers specify the handling of extreme values that fall outside the range set by

**-T**. By default these values are ignored. Append**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**.

**-N**[*mode*][**+p***pen*]Draw the equivalent normal distribution; append desired pen [0.25p,black]. The

*mode*selects which central location and scale to use:0 = mean and standard deviation [Default];

1 = median and L1 scale (1.4826 * median absolute deviation; MAD);

2 = LMS (least median of squares) mode and scale.

The

**-N**option may be repeated to draw several of these curves.**Note**: If**-w**is used then only*mode*= 0 is available and we will determine the parameters of the circular von Mises distribution instead.

**-Q****r**Draw a cumulative histogram. Append

**r**to instead compute the reverse cumulative histogram. Cannot be used with**-w**.

**-R***xmin*/*xmax*/*ymin*/*ymax*[**+r**][**+u***unit*]Specify the region of interest. (See full description) (See cookbook information).

For perspective view

-p, optionally append /zmin/zmax. (more …) If not given, we 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**[*label*|**+c**][**+j***just*][**+o***dx*/*dy*]Draw GMT time stamp logo on plot. (See full description) (See cookbook information).

**-V**[*level*]Select verbosity level [

**w**]. (See full description) (See cookbook information).

**-W***pen*Draw bar outline (or stair-case curve) using the specified pen thickness. [Default is no outline].

**-X**[**a**|**c**|**f**|**r**][*xshift*]Shift plot origin. (See full description) (See cookbook information).

**-Y**[**a**|**c**|**f**|**r**][*yshift*]Shift plot origin. (See full description) (See cookbook information).

**-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 format for primary 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**][**+m***segheader*][**+r***remark*][**+t***title*] (more …)Skip or produce header record(s).

**-i***cols*[**+l**][**+d***divide*][**+s***scale*][**+o***offset*][,*…*][,**t**[*word*]] (more …)Select input columns and transformations (0 is first column,

**t**is trailing text, append*word*to read one word only).

**-l**[*label*][**+D***pen*][**+G***gap*][**+H***header*][**+L**[*code*/]*txt*][**+N***cols*][**+S***size*[/*height*]][**+V**[*pen*]][**+f***font*][**+g***fill*][**+j***just*][**+o***off*][**+p***pen*][**+s***scale*][**+w***width*] (more …)Add a legend entry for the symbol or line being plotted. Symbol is a rectangle with width-to-height ratio of 3:2. Use

**+S***width*[/*height*] to overwrite with custom width and optionally height.

**-p**[**x**|**y**|**z**]*azim*[/*elev*[/*zlevel*]][**+w***lon0*/*lat0*[/*z0*]][**+v***x0*/*y0*] (more …)Select perspective view.

**-qi**[~]*rows*[**+c***col*][**+a**|**f**|**s**] (more …)Select input rows or data range(s) [default is all rows].

**-t***transp*[/*transp2*] (more …)Set transparency level(s) in percent.

**-wy**|**a**|**w**|**d**|**h**|**m**|**s**|**c***period*[/*phase*][**+c***col*] (more …)Convert an input coordinate to a cyclical coordinate.

**-^**or just**-**Print a short message about the syntax of the command, then exit (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 exit.

**-?**or no argumentsPrint a complete usage (help) message, including the explanation of all options, then exit.

**--PAR**=*value*Temporarily override a GMT default setting; repeatable. See gmt.conf for parameters.

## Generate 1D Array¶

We will demonstrate the use of options for creating 1-D arrays via gmtmath.
Make an evenly spaced coordinate array from *min* to *max* in steps of *inc*, e.g.,:

```
gmt math -o0 -T3.1/4.2/0.1 T =
3.1
3.2
3.3
3.4
3.5
3.6
3.7
```

Append **+b** if we should take log2 of *min* and *max*, get their nearest integers,
build an equidistant log2-array using *inc* integer increments in log2, then undo
the log2 conversion. E.g., **-T**3/20/1**+b** will produce this sequence:

```
gmt math -o0 -T3/20/1+b T =
4
8
16
```

Append **+l** if we should take log10 of *min* and *max* and build an
array where *inc* can be 1 (every magnitude), 2, (1, 2, 5 times magnitude) or 3
(1-9 times magnitude). E.g., **-T**7/135/2**+l** will produce this sequence:

```
gmt math -o0 -T7/135/2+l T =
10
20
50
100
```

For output values less frequently than every magnitude, use a negative integer *inc*:

```
gmt math -o0 -T1e-4/1e4/-2+l T =
0.0001
0.01
1
100
10000
```

Append **+i** if *inc* is a fractional number and it is cleaner to give its reciprocal
value instead. To set up times for a 24-frames per second animation lasting 1 minute, run:

```
gmt math -o0 -T0/60/24+i T =
0
0.0416666666667
0.0833333333333
0.125
0.166666666667
...
```

Append **+n** if *inc* is meant to indicate the *number* of equidistant coordinates
instead. To have exactly 5 equidistant values from 3.44 and 7.82, run:

```
gmt math -o0 -T3.44/7.82/5+n T =
3.44
4.535
5.63
6.725
7.82
```

Alternatively, give a *file* with output coordinates in the first column,
or provide a comma-separated *list* of specific coordinates, such as the first 6
Fibonacci numbers:

```
gmt math -o0 -T0,1,1,2,3,5 T =
0
1
1
2
3
5
```

If you only want a *single* value
then you must append a comma to distinguish the list from the setting of *inc*.

If the module allows you to set up an absolute time series, append a valid time unit from the list
**y**ear, m**o**nth, **d**ay, **h**our, **m**inute, and **s**econd
to the given increment; add **+t** to ensure time column (or use **-f**). **Note**: The internal time
unit is still controlled independently by TIME_UNIT. The first 7 days of March 2020:

```
gmt math -o0 -T2020-03-01T/2020-03-07T/1d T =
2020-03-01T00:00:00
2020-03-02T00:00:00
2020-03-03T00:00:00
2020-03-04T00:00:00
2020-03-05T00:00:00
2020-03-06T00:00:00
2020-03-07T00:00:00
```

A few modules allow for **+a** which will paste the coordinate array to the output table.

Likewise, if the module allows you to set up a spatial distance series (with distances computed
from the first two data columns), specify a new increment as *inc* with a geospatial distance unit from the list
**d**egree (arc), **m**inute (arc), **s**econd (arc), m**e**ter, **f**oot, **k**ilometer,
**M**iles (statute), **n**autical miles, or s**u**rvey foot; see **-j** for calculation mode.
To interpolate Cartesian distances instead, you must use the special unit **c**.

Finally, if you are only providing an increment and will obtain *min* and *max* from the data, then it is
possible (*max* - *min*)/*inc* is not an integer, as required. If so, then *inc* will be adjusted to fit the range.
Alternatively, append **+e** to keep *inc* exact and adjust *max* instead (keeping *min* fixed).

## Examples¶

**Note**: Below are some examples of valid syntax for this module.
The examples that use remote files (file names starting with `@`

)
can be cut and pasted into your terminal for testing.
Other commands requiring input files are just dummy examples of the types
of uses that are common but cannot be run verbatim as written.

**Note**: Since many GMT plot examples are very short (i.e., one module call between the
**gmt begin** and **gmt end** commands), we will often present them using the quick
modern mode GMT Modern Mode One-line Commands syntax, which simplifies such short scripts.

To draw a histogram of the remote data v3206_06.txt containing seafloor depths, using a 250 meter bin width, center bars, and draw bar outline, use:

gmt histogram @v3206_06.txt -F -T250 -W0.25p -B -pdf plot

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 and 0.01c/count in y, annotate every 2 m and 100 counts, and use black bars, run:

gmt begin plot gmt histogram errors.xy -T1 -R-10/10/0/0 -Jx0.75c/0.01c -Bx2+lError -By100+lCounts -Gblack -i1 gmt end show

Since no y-range was specified, **histogram** will calculate *ymax* in even
increments of 100.