histogram¶

Calculate and plot histograms

Synopsis¶

gmt histogram [ table ] -Jx|Xparameters -T[min/max/]inc[+i|n] |-Tfile|list [ -A ] [ -B[p|s]parameters ] [ -Ccpt[+b] ] [ -D[+b][+ffont][+ooff][+r] ] [ -Ewidth[+ooffset] ] [ -F ] [ -Gfill ] [ -Jz|Zparameters ] [ -I[o|O] ] [ -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 ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -lflags ] [ -pflags ] [ -qiflags ] [ -ttransp ] [ -wflags ] [ --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] |-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 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 (more …): Set map boundary frame and axes attributes.

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

-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 value. [Default is left edge].

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

-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][+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 (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.

-Qr: Draw a cumulative histogram. Append r to instead compute the reverse cumulative histogram.

-Rxmin/xmax/ymin/ymax[+r][+uunit] (more …): Specify the region of interest.

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][+jjust][+odx/dy] (more …): Draw GMT time stamp logo on plot.

-V[level] (more …): Select verbosity level [w].

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

-X[a|c|f|r][xshift]

-Y[a|c|f|r][yshift] (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 format for primary input. [Default is 2 input columns].

-dinodata (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][+ddivide][+sscale][+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.

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

-qi[~]rows[+ccol][+a|f|s] (more …): Select input rows or data range(s) [all].

-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 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 =
1
2
3
4
5
6
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., -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 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., -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, 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 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.