histogram

Calculate and plot histograms

Synopsis

gmt histogram [ table ] -T[min/max/]inc[+i|n] | -Tfile|list [ -A ] [ -B[p|s]parameters ] [ -Ccpt[+b] ] [ -D[+b][+ffont][+ooff][+r] ] [ -Ewidth[+ooffset] ] [ -F ] [ -Gfill ] [ -I[o|O] ] [ -Jx|Xparameters ] [ -Jz|Zparameters ] [ -Ll|h|b ] [ -N[mode][+ppen] ] [ -Qr ] [ -Rregion ] [ -S ] [ -U[stamp] ] [ -V[level] ] [ -Wpen ] [ -X[a|c|f|r][xshift] ] [ -Y[a|c|f|r][yshift] ] [ -Z[type][+w] ] [ -bibinary ] [ -dinodata[+ccol] ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -lflags ] [ -oflags ] [ -pflags ] [ -qiflags ] [ -sflags ] [ -ttransp ] [ -wflags ] [ --PAR=value ]

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. Note: Optional in modern mode.

-T[min/max/]inc[+n] |-Tfile|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 1-D Array. Note: If inc is given with a trailing time unit then it takes precedence over the current setting of TIME_UNIT; otherwise that setting determines the units used for the bin widths.

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 technical reference).

-Ccpt[+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][+ffont][+ooff][+r]

Annotate each bar with the count it represents. Append any of the following modifiers:

+b - Place the labels beneath the bars instead of above.
+f - Change to another font than the default annotation font.
+o - Change the offset between bar and label [6p].
+r - Rotate the labels from horizontal to vertical.

-Ewidth[+ooffset]: 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 node created via -T [Default uses the nodes to define the left edge of each bin].

-Gfill (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 directive o to output an ASCII table of the resulting x, y data instead. Upper case directive O will output all x, y bin data even when y == 0. Note: You may use -o to select a subset from this record.

-Jz|Zparameters: Set z-axis scaling; same syntax as -Jx.

-Ll|h|b

The directives specify the handling of extreme values that fall outside the range set by -T. By default these values are ignored. Choose among these:

b - Let these values be included in the first or last bins.
l - Only include extreme values below first bin into the first bin.
h - Only include extreme values above the last bin into that last bin.

-N[mode][+ppen]

Draw the equivalent normal distribution; append desired pen [0.25p,black]. The mode directive 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.

-Qr: Draw a cumulative histogram. Append r to instead compute the reverse cumulative histogram. Cannot be used with -w.

-Rxmin/xmax/ymin/ymax[+r][+uunit]: Specify the region of interest. (See full description) (See technical reference).

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][+jjustify][+odx[/dy]][+ttext]: Draw GMT time stamp logo on plot. (See full description) (See technical reference).

-V[level]: Select verbosity level [w]. (See full description) (See technical reference).

-Wpen: 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 technical reference).

-Y[a|c|f|r][yshift]: Shift plot origin. (See full description) (See technical reference).

-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 = \(\log_{10}\) (1.0 + count)
5 = \(\log_{10}\) (1.0 + frequency_percent).

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

-birecord[+b|l] (more …): Select native binary format for primary table input. [Default is 2 input columns].

-dinodata[+ccol] (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][+msegheader][+rremark][+ttitle] (more …): Skip or produce header record(s).

-icols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,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][+Dpen][+Ggap][+Hheader][+L[code/]txt][+Ncols][+Ssize[/height]][+V[pen]][+ffont][+gfill][+jjust][+ooff][+ppen][+sscale][+wwidth] (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 +Swidth[/height] to overwrite with custom width and optionally height.

-ocols[+l][+ddivisor][+sscale|d|k][+ooffset][,…][,t[word]] (more …): Select output columns and transformations (0 is first column, t is trailing text, append word to write one word only).

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0] (more …): Select perspective view.

-qi[~]rows|limits[+ccol][+a|t|s] (more …): Select input rows or data limit(s) [default is all rows].

-s[cols][+a][+r] (more …): Set handling of NaN records for output.

-ttransp[/transp2] (more …): Set transparency level(s) in percent.

-wy|a|w|d|h|m|s|cperiod[/phase][+ccol] (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 arguments: Print 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 1-D Array

We will demonstrate the use of options for creating 1-D arrays via math. 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 =
1
2
3
4
5
6
7
...

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

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

Append +l if we should take \(\log_{10}\) 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., -T7/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 =
44
535
63
725
82

Alternatively, let inc be 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

Notes: (1) If you need to pass the list nodes via a dataset file yet be understood as a list (i.e., no interpolation), then you must set the file header to contain the string “LIST”. (2) Should you need to ensure that the coordinates are unique and sorted (in case the file or list are not sorted or have duplicates) then supply the +u modifier.

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

If the module allows you to set up an absolute time series, append a valid time unit from the list year, month, day, hour, minute, and second 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 degree (arc), minute (arc), second (arc), meter, foot, kilometer, Miles (statute), nautical miles, or survey 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.