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

# histogram

官方文档:

  histogram

简介:

  统计并绘制直方图

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

## 语法

gmt histogram [ table ] `-J` x|X parameters `-T`[min/max/]inc[+n|i] |`-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] ] [ `-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[+c col] ] [ `-e` regexp ] [ `-f` flags ] [ `-h` headers ] [ `-i` flags ] [ `-l` flags ] [ `-o` flags ] [ `-p` flags ] [ `-qi` flags ] [ `-s` flags ] [ `-t` transp ] [ `-w` flags ] [ --PAR=value ]

## 输入数据

table

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

## 必须选项

-J

-J x|X parameters

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

-T

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

  指定等间隔统计直方：

  - `-T` min/max/inc 指定统计区间的最小值、最大值和直方间隔

  - `-T` inc 只指定统计直方的间隔。统计区间最大和最小值由 `-R` 选项决定

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

  - +n ：表示 inc 是直方数量而不是默认的直方间隔。

  - +i ：表示 inc 是直方间隔的倒数（例如，输入 3 代表 0.3333...）。

-T file|list

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

详情请参见 生成一维数组 。

## 可选选项

-A

-A

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

-B

-B parameters

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

-C

-C cpt[+b]

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

-D

-D[+b][+f font][+o off][+r]

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

  - +b ：将标注放在直方的底部（默认为顶部）

  - +f font ：设置标注的字体

  - +o offset ：修改标注与直方的距离（默认值为6p）

  - +r ：将标注从水平方向旋转为垂直方向

-E

-E width[+o offset]

  设置新的直方宽度 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

-G fill

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

-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][+p pen]

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

  - mode = 0：平均值和标准差 (默认)

  - mode = 1：中位数和 L1 比例尺 (1.4826 * 中值绝对偏差; MAD)

  - mode = 2：LMS (最小二乘中位数) 众数和比例尺

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

-Q

-Q r

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

-R

-R xmin/xmax/ymin/ymax[+r][+u unit]

  指定数据范围。 (参数详细介绍)

-S

-S

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

-U

-U[label][+c][+j just][+o dx/dy]

  在图上绘制GMT时间戳logo。 (参数详细介绍)

-V

-V[level]

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

-W

-W pen

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

-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

-di nodata

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

-e

-e[~]"pattern" | -e[~]/regexp/[i]

  筛选或剔除匹配指定模式的数据记录。 (参数详细介绍)

-f

-f[i|o]colinfo

  显式指定当前输入或输出数据中每一列的数据类型。 (参数详细介绍)

-h

-h[i|o][n][+c][+d][+m segheader][+r remark][+t title]

  在读/写数据时跳过文件开头的若干个记录。 (参数详细介绍)

-i

-i cols[+l][+s scale][+o offset][,...][,t[word]]

  对输入的数据进行列选择以及简单的代数运算。 (参数详细介绍)

-l

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

  为当前绘制的符号或线段增加一个自动图例记录。 (参数详细介绍)

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

-o

-o cols[,...][,t[word]]

  对输出的数据进行列选择以及简单的代数运算。 (参数详细介绍)

-p

-p[x|y|z]azim[/elev[/zlevel]][+w lon0/lat0[/z0]][+v x0/y0]

  设置3D透视视角。 (参数详细介绍)

-qi

-qi[~]rows[+c col][+a|f|s]

  筛选输入的行或数据范围。 (参数详细介绍)

-s

-s[cols][+a|+r]

  设置 NaN 记录的处理方式。 (参数详细介绍)

-t

-t[transp]

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

-w

-wy|a|w|d|h|m|s|c period[/phase][+c col]

  将输入坐标转换为循环坐标。 (参数详细介绍)

-^ 或 -

  显示简短的帮助信息，包括模块简介和基本语法信息（Windows下只能使用 -）

-+ 或 +

  显示帮助信息，包括模块简介、基本语法以及模块特有选项的说明

-? 或无参数

  显示完整的帮助信息，包括模块简介、基本语法以及所有选项的说明

--PAR=value

  临时修改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。

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

## 相关模块

basemap, rose, plot