✍️ 田冬冬 , 王亮 , 陈箫翰 • 📅 2026-01-04

histogram

官方文档:: histogram
简介:: 统计并绘制直方图

histogram 模块读取文件 [或标准输入] 并检查第一列数据（或由 -i 指定的列），根据提供的直方间隔计算直方图参数。利用这些参数、缩放比例以及可选的范围参数绘制直方图。此外，还可以指定绘制累积直方图。

语法

gmt histogram [ table ] -Jx|Xparameters -T[min/max/]inc[+n|i] |-Tfile|list [ -A ] [ -B[p|s]parameters ] [ -Ccpt[+b] ] [ -D[+b][+ffont][+ooff][+r] ] [ -Ewidth[+ooffset] ] [ -F ] [ -Gfill ] [ -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[+ccol] ] [ -eregexp ] [ -fflags ] [ -hheaders ] [ -iflags ] [ -lflags ] [ -oflags ] [ -pflags ] [ -qiflags ] [ -sflags ] [ -ttransp ] [ -wflags ] [ --PAR=value ]

输入数据

table: 一个或多个ASCII或二进制表数据。若不提供表数据，则会从标准输入中读取。

必须选项

-J

-Jx|Xparameters: xscale[/yscale] 表示线性比例尺，或者使用 -JX 指定 width[/height] 宽度/高度。详细说明请参考 -JX: Linear, logarithmic, power, and time 。

-T

-T[min/max/]inc[+n|i]

指定等间隔统计直方：

-Tmin/max/inc 指定统计区间的最小值、最大值和直方间隔
-Tinc 只指定统计直方的间隔。统计区间最大和最小值由 -R 选项决定

注意：对时间数据进行统计时，时间单位默认由 TIME_UNIT 控制。也可以在 inc 后自行附加时间单位后缀。

+n ：表示 inc 是直方数量而不是默认的直方间隔。
+i ：表示 inc 是直方间隔的倒数（例如，输入 3 代表 0.3333…）。

-Tfile|list

指定不等间隔统计直方：提供一个第一列为直方间隔的文件 file ，或者一个逗号分隔的数值列表 list 。

可选选项

-A

-A: 水平绘制直方图，即从 x = 0 开始。不使用本选项默认是从 y = 0 开始垂直绘制。绘图尺寸保持不变，但两个坐标轴会发生对调。

-B

-Bparameters: 设置底图边框和轴属性。 (参数详细介绍)

-C

-Ccpt[+b]: 指定 CPT 文件，将每个直方的中点坐标作为 Z 值查询 CPT 中的颜色，颜色随 X 轴（数值区间）变化。附加 +b 改为使用每个直方的频数或百分比作为 Z 值进行查询，颜色将随 Y 轴（频数或百分比）变化。如果 -Z 涉及百分比，附加 +b 则使用计算出的百分比进行查询。

-D

-D[+b][+ffont][+ooff][+r]

为每个直方添加标注，其内容是每个直方的统计数目：

+b ：将标注放在直方的底部（默认为顶部）
+ffont ：设置标注的字体
+ooffset ：修改标注与直方的距离（默认值为6p）
+r ：将标注从水平方向旋转为垂直方向

-E

-Ewidth[+ooffset]: 设置新的直方宽度 width 覆盖 -T 中的设置，也可以附加 +o 将所有直方平移一个 offset 偏移量。 width 既可以是数据单位表示的备选宽度，也可以附加有效的绘图尺寸单位（ c|i|p ）来指定固定尺寸。与 width 一样，偏移量 offset 也可以附加单位。

-F

-F

将每个直方的中点对准 -T 选项创建的一维数组的每个值。不使用本选项默认使用每个直方的左边界进行对齐。

假设 -T 设置的范围是0到100，间隔为10。默认情况下，会将0到10作为第一个直方，10到20作为第二个直方，以此类推。若使用本选项，则第一个直方以0为中心，即-5到5是第一个直方，5到15是第二个直方，以此类推。

-G

-Gfill: 设置直方的填充色（默认无填充）。

-I

-I[o|O]

输出计算结果不绘图。

-I 输出 xmin xmax ymin ymax，即数据的最小值、最大值和统计数量的最小值、最大值。
-Io 输出各个直方的 x, y 数据的 ASCII 表，不包括 y = 0 的数据。
-IO 输出包括 y = 0 的所有数据。

注意：可以使用 -o 选项选择部分数据输出。

-L

-Ll|h|b

设置超过统计范围的数据的处理方式。

-Ll 小于第一个直方的统计范围的数据算入第一个直方
-Lh 大于最后一个直方的统计范围的数据算入最后一个直方
-Lb 小于第一个直方的统计范围的数据算入第一个直方，并且大于最后一个直方的统计范围的数据算入最后一个直方

-N

-N[mode][+ppen]

绘制等效的正态分布曲线，可附加画笔属性 [默认为 0.25p,black]。 mode 用于设定正态分布的中心位置和比例尺：

mode = 0：平均值和标准差 (默认)
mode = 1：中位数和 L1 比例尺 (1.4826 * 中值绝对偏差; MAD)
mode = 2：LMS (最小二乘中位数) 众数和比例尺

该选项可以使用多次以绘制多条曲线。注意：如果使用了 -w 选项，则仅 mode = 0 可用，此时将计算圆形冯·米塞斯分布（von Mises distribution）的参数。

-Q

-Qr: 绘制累计直方图， r 绘制反向的累计直方图。不能和 -w 一起使用。

-R

-Rxmin/xmax/ymin/ymax[+r][+uunit]: 指定数据范围。 (参数详细介绍)

-S

-S: 绘制阶梯状直方图，并且不包含直方内部的线条。

-U

-U[label][+c][+jjust][+odx/dy]: 在图上绘制GMT时间戳logo。 (参数详细介绍)

-V

-V[level]: 设置 verbose 等级 [w]。 (参数详细介绍)

-W

-Wpen: 设置直方边框（或阶梯状曲线）的画笔属性 [默认不绘制]。

-X

-Y

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

-Y[a|c|f|r][yshift[u]]: 移动绘图原点。 (参数详细介绍)

-Z

-Z[type][+w]

选择直方图的种类：

type = 0：频数 counts（默认值）
type = 1：百分比 frequency_percent
type = 2：log (1.0 + count)
type = 3：log (1.0 + frequency_percent)
type = 4：\(\log_{10}\) (1.0 + count)
type = 5：\(\log_{10}\) (1.0 + frequency_percent)

若要使用数据第二列而不是 counts 频数作为权重，可以加上 +w 。

-bi

-bi[ncols][type][w][+l|b]: 控制二进制文件的输入格式。 (参数详细介绍)

-di

-dinodata: 将输入数据某些特定值当作NaN。 (参数详细介绍)

-e

-e[~]“pattern” | -e[~]/regexp/[i]: 筛选或剔除匹配指定模式的数据记录。 (参数详细介绍)

-f

-f[i|o]colinfo: 显式指定当前输入或输出数据中每一列的数据类型。 (参数详细介绍)

-h

-h[i|o][n][+c][+d][+msegheader][+rremark][+ttitle]: 在读/写数据时跳过文件开头的若干个记录。 (参数详细介绍)

-i

-icols[+l][+sscale][+ooffset][,…][,t[word]]: 对输入的数据进行列选择以及简单的代数运算。 (参数详细介绍)

-l

-l[label][+Dpen][+Ggap][+Hheader][+L[code/]txt][+Ncols][+Ssize[/height]][+V[pen]][+ffont][+gfill][+jjust][+ooff][+ppen][+sscale][+wwidth]: 为当前绘制的符号或线段增加一个自动图例记录。 (参数详细介绍)

图例符号是一个宽高比为 3:2 的矩形。使用 +Swidth[/height] 可自定义宽度高度。

-o

-ocols[,…][,t[word]]: 对输出的数据进行列选择以及简单的代数运算。 (参数详细介绍)

-p

-p[x|y|z]azim[/elev[/zlevel]][+wlon0/lat0[/z0]][+vx0/y0]: 设置3D透视视角。 (参数详细介绍)

-qi

-qi[~]rows[+ccol][+a|f|s]: 筛选输入的行或数据范围。 (参数详细介绍)

-s

-s[cols][+a|+r]: 设置 NaN 记录的处理方式。 (参数详细介绍)

-t

-t[transp]: 设置图层透明度（百分比）。取值范围为0（不透明）到100（全透明）。 (参数详细介绍)

-w

-wy|a|w|d|h|m|s|cperiod[/phase][+ccol]: 将输入坐标转换为循环坐标。 (参数详细介绍)

-^ 或 -: 显示简短的帮助信息，包括模块简介和基本语法信息（Windows下只能使用 -）
-+ 或 +: 显示帮助信息，包括模块简介、基本语法以及模块特有选项的说明
-? 或无参数: 显示完整的帮助信息，包括模块简介、基本语法以及所有选项的说明
--PAR=value: 临时修改GMT参数的值，可重复多次使用。参数列表见配置参数

生成一维数组

下面将展示如何使用 math 生成一维数组（其中大部分操作也可通过 linux 中的 seq 命令方便地实现）

不使用任何子选项

以 0.1 为步长，生成 3.1 到 4.2 等等间隔序列

gmt math -o0 -T3.1/4.2/0.1 T =
3.1
3.2
...
4.2

+a 选项

该选项不对生成的数列进行运算操作，而是将该数列以列的形式追加到输出表数据，类似 linux 中的 paste 命令。

+b 选项

以 3 和 20 分别为起点和终点，创建一个 2 的整数幂的列表，将生成的整数幂以 1 为步长取值 -T3/20/1+b

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

+l 选项

以 7 和 135 分别为起点和终点，先创建一个 10 的整数幂的列表，当 inc 为 1 时，输出该列表；当 inc 为 2 时，同时输出该列表中每个元素的 1，2，5 倍值（不包括超出原始数据范围的部分）；当 inc 为 3 时，同时输出该列表中每个元素的 1，2，…，9 倍值（同样不包括超出原始数据范围的部分）。 -T7/135/2+l 将会生成如下数列

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

inc 为负整数时，将实现如下效果

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

+i 选项

该选项将以 1 作为默认步长，第三个数字做为每步长中的数字个数 length。假设需要在 1 分钟内每 24 秒生成一帧

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

+n 选项

生成固定长度的数列。以 3.44 和 7.82 为起点和终点，生成长度为 5 的等间隔序列

gmt math -o0 -T3.44/7.82/5+n T =
44
535
63
725
82

-T 后直接加文件或逗号分隔的数列

-T 后可以直接加文件，文件中即为要生成的列表；另外，可以直接使用逗号分隔，将列表附加到 -T 选项后，如下为 Fibonacci 数列前 6 项

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

注：如果数列只包含一个值，必须在其后加逗号以表明仍是一个数列

+u 选项

如果文件或者逗号分隔的数列中有重复数字或未排序，可以使用 +u 选项去重并排序。

+t 选项

生成绝对时间序列。在 inc 后分别添加 y ，o ，d ，h ， m 和 s 表示时间步长的单位为年，月，日，时，分，秒。在其后附加 +t 选项，可以进一步强调生成时间序列，也可以不加

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

生成距离序列

如果输入文件中包含两列以上的数据，可以使用前两列计算距离，并生成等距序列。在 inc 后分别添加 d，m，s，e，f，M，n 和 u 表示距离步长的单位为度，分，秒，米，英尺，公里，英里，海里，英尺。如果为笛卡尔坐标，使用 c 作为距离步长单位。

+e 选项

如果只给定 inc 而从数据中获取最大值和最小值，则 (max - min)/inc 可能不是整数，GMT 讲会自动对 inc 进行一定的调整。如果不想调整 inc ，则可以使用 +e 选项，GMT 会固定最小值，适当调整最大值。

示例

用包含海底深度的远程数据文件 @v3206_06.txt 绘制直方图，并使用 250 米的间距、使直方居中并绘制轮廓:

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

如果了解数据的分布情况，可以显式指定范围和比例尺。例如，用文件 errors.xy 中的 y 值（第 2 列）绘制直方图，使用 1 米的间距，绘制范围为 -10 到 +10 米， x 轴比例尺为 0.75 cm/m，y 轴比例尺为 0.01 cm/计数，每隔 2 米和 100 个计数进行标注，并使用黑色直方:

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

由于未指定 y 轴范围， histogram 将以 100 的整数倍为增量自动计算 ymax。

访问绘制直方图以查看更多示例。

histogram

语法

输入数据

必须选项

可选选项

生成一维数组

示例

相关模块