# barh
水平条形图
函数库: TyPlot
# 语法
barh(y)
barh(x,y)
barh(___,Key=Value)
barh(ax,___)
b = barh(___)
# 说明
barh(y) 创建一个水平条形图，每个条形对应 y 中一个元素。如果 y 是 m×n 矩阵，则 barh 创建每组包含 n 个条形的 m 个组。示例
barh(x,y) 沿垂直轴在 x 指定的位置绘制条形。示例
barh(___,Key=Value)使用一个或多个名称-值对组参数指定条形图的属性。仅使用默认"grouped"或"stacked"样式的条形图支持设置条形属性。在所有其他输入参数之后指定名称-值对组参数。示例
barh(ax,___) 在目标坐标区中显示条形图。将坐标区指定为上述任一语法中的第一个参数。示例
b = barh(___) 返回一个或多个 CBar 对象。如果 y 是向量，则 barh 返回一个 CBar 对象。如果 y 是矩阵，则 barh 为每个序列返回一个 CBar 对象。显示条形图后，使用 b 设置条形的属性。示例
# 示例
显示一个条形序列
创建一个包含四个值的向量。在一个条形图中显示这些值，每个水平条形对应一个值。
using TyPlot
y = [10 20 30 41];
barh(y)
显示具有轴标签和图例的四个条形序列
将 x 定义为一个包含三个年份值的矩阵。将 y 定义为包含四个城市的降雪数据的矩阵。在每年的组中显示四个条形序列。然后添加轴标签和图例。
using TyPlot
x = [1980, 1990, 2000]
y = [40 50 63 52; 42 55 50 48; 30 20 44 40]
labels = ["Springfield", "Fairview", "Bristol", "Jamesville"]
bars = barh(x, y)
xlabel("Snowfall")
ylabel("Year")
legend(bars, labels)
更改基准值
创建矩阵 y。然后在条形图中以 25 为基准值显示 y 值。小于 25 的值显示在基线的左侧。
using TyPlot
y = [8 15 33; 30 35 40; 50 55 62]
barh(y, basevalue = 25)
显示具有负数据的堆叠条形
将 x 定义为一个包含三个年份值的向量。将 y 定义为包含负值和正值组合的矩阵。在堆叠水平条形图中显示值。
using TyPlot
x = [1980, 1990, 2000]
y = [15 20 -5; 10 -17 21; -10 5 15]
barh(x, y, style = "stacked")
自定义垂直轴刻度标签
将 y 定义为包含四个值的向量，并在水平条形图中显示值。然后调用 yticklabels 函数来更改垂直轴上的刻度标签。
using TyPlot
x = ["April","May","June","July"]
y = [10, 20, 30, 41]
barh(y)
yticklabels(x)
指定分类数据
指示条形图类别的一种方法是将 X 指定为分类数组。barh 函数使用经过排序的类别列表，因此条形的显示顺序可能与您预期的有所不同。
将 X 定义为分类数组，然后将 Y 定义为条形长度的向量，并显示条形图。
using TyPlot
x = ["Small","Medium","Large","ExtraLarge"]
y = [10,21,33,52]
barh(x, y)
在条形末端添加标签
将 vals 定义为包含两个数据序列的矩阵。在水平条形图中显示数据，并指定输出参数。由于有两个序列，barh 返回包含两个 CBar 对象的向量。
using TyPlot
x = [1,2,3]
y = [2 3 6; 11 23 26]'
barh(x,y)
接下来，在条形序列的末端显示标签。
barh(x,y, text = y)
指定条形宽度和颜色
创建数据并在水平条形图中显示数据，该条形图中条形的宽度为 0.4，颜色为红色。
using TyPlot
y = [10,22,30,42]
barh(y, height = 0.4, color = "r")
自定义一个条形序列
创建矩阵 y，其中每列为一个数据序列。然后在条形图中显示数据，指定在调用 barh 函数时的输出参数。在本例中，barh 返回包含三个 CBar 对象的向量。每个对象对应于一个不同序列。
using TyPlot
y = [10 15 20; 30 35 40; 50 55 62]
b = barh(y)
将第二个条形序列改为绿色，并使用加粗的红边。
b[2].set_facecolor([0.2, 0.6, 0.5])
b[2].set_edgecolor([0.63, 0.08, 0.18])
b[2].set_linewidth(2)
比较不同的条形样式
创建数据，并使用使用默认的 "grouped" 样式和 "stacked" 样式在两个不同的条形图中显示数据。
using TyPlot
x = [1980, 1990, 2000]
y = [8 15 25; 30 35 40; 50 55 62]
ax1 = subplot(2,1,1)
barh(ax1, x, y)
title("Grouped Style")
ax2 = subplot(2,1,2)
barh(ax2, x, y, style="stacked")
title("Stacked Style")
tightlayout()
# 输入参数
x - 垂直轴坐标标量 | 向量 | 矩阵
垂直轴坐标，指定为标量、向量或矩阵。x 的值不需要按顺序排列，但 x 的大小取决于 y 的大小以及您要如何显示数据。下表说明了最常见的情况。
| 表示形式 | 如何指定 X 和 Y | 示例 |
|---|---|---|
| 显示一个条形序列。 | 指定 x 和 y 为相同长度的向量。x 中的值必须唯一，但 y 中的值不需要唯一。 | x = [1980 1990 2000]; y = [10 20 30]; barh(x,y)  |
| 分组显示多个条形序列。 | 指将 x 指定为唯一值的向量，并将 y 指定为矩阵。x 的长度必须等于 y 的至少一个维度的长度。y 的另一个维度包含不同条形序列的值。 | x = [1980 1990]; y = [2 6 9;11 22 32]; barh(x,y)  |
数据类型： Int16 | Int32 | Int64 | Float16 | Float32 | Float64 | DateTime
y - 条形长度标量 | 向量 | 矩阵
条形长度，指定为标量、向量或矩阵。y 的大小取决于 x 的大小以及您要如何显示数据。下表说明了最常见的情况。
| 表示形式 | 如何指定 X 和 Y | 示例 |
|---|---|---|
| 显示一个条形序列。 | 指定 x 和 y 为相同长度的向量。x 中的值必须唯一，但 y 中的值不需要唯一。 | x = [1980 1990 2000]; y = [10 20 30]; barh(x,y) |
| 分组显示多个条形序列。 | 指将 x 指定为唯一值的向量，并将 y 指定为矩阵。x 的长度必须等于 y 的至少一个维度的长度。y 的另一个维度包含不同条形序列的值。 | x = [1980 1990]; y = [2 6 9;11 22 32]; barh(x,y) |
数据类型： Int16 | Int32 | Int64 | Float16 | Float32 | Float64
ax - 目标坐标区Axes 对象
目标坐标区，指定为 Axes 对象。如果未指定坐标区，则条形图显示在当前坐标区中。
# 名称-值对组参数
指定可选的、以逗号分隔的 Key=Value 对组参数。Key 为参数名称，Value 为对应的值。您可采用任意顺序指定多个名称-值对组参数，如 Key1=Value1,...,KeyN=ValueN 所示。
示例： barh([10,20,30], edgecolor = "g") 将围绕条形的轮廓指定为绿色。
注意
- 此处所列的属性只是一部分；
- 您只能在使用默认 "grouped" 或 "stacked" 样式的条形图上设置这些属性。
height - 条形高度0.8 （默认） | 标量
条形宽度，指定为每个条形可用空间的一定比例。默认值 0.8 表示每个条形使用从上一条形到下一条形之间的空间的 80%，两端各有 10% 的空白空间。
如果宽度为 1，则组中的条形会紧挨在一起。
示例： barh([1 2 3],height = 0.5) 创建使用 50% 可用空间的条形。
style - 组样式"grouped" （默认） | "stacked" | "hist" | "histc"
组样式，使用下列值之一指定。
| 样式 | 结果 | 示例 |
|---|---|---|
| "grouped" | 将每组显示为以对应的 x 值为中心的相邻条形。 |  |
| "stacked" | 将每组显示为一个多色条形。条形的长度是组中各元素之和。如果 y 是向量，则结果与 "grouped" 相同。 |  |
| "histc" | 以直方图格式显示条形，同一组中的条形紧挨在一起。每组的尾部边缘与对应的 x 值对齐。 |  |
| "hist" | 以直方图格式显示条形。每组以对应的 x 值为中心。 |  |
labels - 图例nothing（默认） | 字符串标量
labels 图例，默认为 nothing，使用默认数据 data1，data2 标记图形对象。如果设置了图例则以图例内容标记图形对象。
edgecolor - 轮廓颜色RGB 三元组 | 十六进制颜色代码 | "r" | "g" | "b" | ...
轮廓颜色，指定为 RGB 三元组、十六进制颜色代码、颜色名称或短名称。如果有 150 个条形或更少，则默认值为 [0,0,0]，对应于黑色。
对于自定义颜色，请指定 RGB 三元组或十六进制颜色代码。
- RGB 三元组是包含三个元素的行向量，其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内，例如 [0.4,0.6,0.7]；
- 十六进制颜色代码是字符向量或字符串标量，以井号 (#) 开头，后跟三个或六个十六进制数字，范围可以是 0 到 F。这些值不区分大小写。因此，颜色代码 "#FF8800" 与 "#ff8800"、"#F80" 与 "#f80" 是等效的。
此外，还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。
| 颜色名称 | 短名称 | RGB 三元组 | 十六进制颜色代码 | 外观 |
|---|---|---|---|---|
| "red" | "r" | [1, 0, 0] | "#FF0000" |  |
| "green" | 不适用 | [0, 0.5019607843137255, 0] | "#008000" |  |
| 不适用 | "g" | [0, 0.5, 0] | "#007F00" | |
| 不适用 | 不适用 | [0, 1, 0] | "#00FF00" |  |
| "blue" | "b" | [0, 0, 1] | "#0000FF" |  |
| "cyan" | 不适用 | [0, 1, 1] | "#00FFFF" |  |
| 不适用 | "c" | [0, 0.75, 0.75] | "#00BFBF" |  |
| "magenta" | 不适用 | [1, 0, 1] | "#FF00FF" |  |
| 不适用 | "m" | [0.75, 0, 0.75] | "#BF00BF" |  |
| "yellow" | 不适用 | [1, 1, 0] | "#FFFF00" |  |
| 不适用 | "y" | [0.75, 0.75, 0] | "#BFBF00" |  |
| "black" | "k" | [0, 0, 0] | "#000000" |  |
| "white" | "w" | [1, 1, 1] | "#FFFFFF" |  |
| "none" | 不适用 | 不适用 | 不适用 | 无颜色 |
以下是 Syslab 在许多类型的绘图中使用的默认颜色的 RGB 三元组和十六进制颜色代码。
| RGB 三元组 | 十六进制颜色代码 | 外观 |
|---|---|---|
| [0, 0.4470, 0.7410] | "#0072BD" |  |
| [0.8500, 0.3250, 0.0980] | "#D95319" |  |
| [0.9290, 0.6940, 0.1250] | "#EDB120" |  |
| [0.4940, 0.1840, 0.5560] | "#7E2F8E" |  |
| [0.4660, 0.6740, 0.1880] | "#77AC30" |  |
| [0.3010, 0.7450, 0.9330] | "#4DBEEE" |  |
| [0.6350, 0.0780, 0.1840] | "#A2142F" |  |
示例： b = barh(1:10, edgecolor="red")
示例： b = barh(1:10, edgecolor=[1, 0, 1])
示例： b = barh(1:10, edgecolor="#00FF00")
facecolor - 填充颜色RGB 三元组 | 十六进制颜色代码 | 颜色名称 | "r" | "g" | "b" | ...
填充颜色，指定为 RGB 三元组、十六进制颜色代码、颜色名称或短名称。
对于自定义颜色，请指定 RGB 三元组或十六进制颜色代码。
- RGB 三元组是包含三个元素的行向量，其元素分别指定颜色中红、绿、蓝分量的强度。强度值必须位于 [0,1] 范围内，例如 [0.4,0.6,0.7]；
- 十六进制颜色代码是字符向量或字符串标量，以井号 (#) 开头，后跟三个或六个十六进制数字，范围可以是 0 到 F。这些值不区分大小写。因此，颜色代码 "#FF8800" 与 "#ff8800"、"#F80" 与 "#f80" 是等效的。
此外，还可以按名称指定一些常见的颜色。下表列出了命名颜色选项、等效 RGB 三元组和十六进制颜色代码。
| 颜色名称 | 短名称 | RGB 三元组 | 十六进制颜色代码 | 外观 |
|---|---|---|---|---|
| "red" | "r" | [1, 0, 0] | "#FF0000" | |
| "green" | 不适用 | [0, 0.5019607843137255, 0] | "#008000" | |
| 不适用 | "g" | [0, 0.5, 0] | "#007F00" | |
| 不适用 | 不适用 | [0, 1, 0] | "#00FF00" | |
| "blue" | "b" | [0, 0, 1] | "#0000FF" | |
| "cyan" | 不适用 | [0, 1, 1] | "#00FFFF" | |
| 不适用 | "c" | [0, 0.75, 0.75] | "#00BFBF" | |
| "magenta" | 不适用 | [1, 0, 1] | "#FF00FF" | |
| 不适用 | "m" | [0.75, 0, 0.75] | "#BF00BF" | |
| "yellow" | 不适用 | [1, 1, 0] | "#FFFF00" | |
| 不适用 | "y" | [0.75, 0.75, 0] | "#BFBF00" | |
| "black" | "k" | [0, 0, 0] | "#000000" | |
| "white" | "w" | [1, 1, 1] | "#FFFFFF" | |
| "none" | 不适用 | 不适用 | 不适用 | 无颜色 |
以下是 Syslab 在许多类型的绘图中使用的默认颜色的 RGB 三元组和十六进制颜色代码。
| RGB 三元组 | 十六进制颜色代码 | 外观 |
|---|---|---|
| [0, 0.4470, 0.7410] | "#0072BD" | |
| [0.8500, 0.3250, 0.0980] | "#D95319" | |
| [0.9290, 0.6940, 0.1250] | "#EDB120" | |
| [0.4940, 0.1840, 0.5560] | "#7E2F8E" | |
| [0.4660, 0.6740, 0.1880] | "#77AC30" | |
| [0.3010, 0.7450, 0.9330] | "#4DBEEE" | |
| [0.6350, 0.0780, 0.1840] | "#A2142F" | |
示例： b = bar(1:10, facecolor="red")
示例： b = bar(1:10, facecolor=[1, 0, 1])
示例： b = bar(1:10, facecolor="#D95319")
edgealpha - 边透明度1 （默认） | 介于 0 和 1（包括二者）之间的标量值
边透明度，指定为介于 0 和 1（包含这两个边界值）之间的标量值。值 1 表示完全不透明，0 则表示完全透明（不可见）。
facealpha - 面透明度1 （默认） | 介于 0 和 1（包括二者）之间的标量值
面透明度，指定为介于 0 和 1（包含这两个边界值）之间的标量值。值 1 表示完全不透明，0 则表示完全透明（不可见）。
linewidth - 条形轮廓的宽度0.5 （默认） | 正值
条形轮廓的宽度，指定为以磅为单位的正值。一磅等于 1/72 英寸。
示例： b = barh(1:10, linewidth=2.5)
数据类型： Int16 | Int32 | Int64 | Float16 | Float32 | Float64
basevalue - 基准值0 （默认） | 数值标量值
基准值，指定为数值标量值。
您指定的基准值将根据条形图的方向应用于 x 轴或 y 轴。如果您将条形图的方向由垂直更改为水平（或反之），基准值可能会改变。
# 输出参数
b - CBar 对象CBar 对象
CBar 对象。在创建具体的 CBar 对象后，可使用 b 中的元素访问和修改对象属性。CBar 对象的数量取决于 y 的大小。如果 y 是向量，则 b 是一个 CBar 对象。如果 y 是矩阵，则 b 是向量，其中包含的每个 CBar 对象都对应于 y 中一个序列。
# 版本历史记录
在 2023a 之前推出
2025a SP3：不支持对返回值图形对象取下标
返回值图形对象不再支持取下标。在以前的版本中，可以对返回值对象取下标，获取下标对应的单个条形，从而可以设置该单个条形的属性。例如：
b, = barh(1:10)
b[2].set_facecolor([1 0 0])
从 2025a SP3 开始，对返回值图形对象取下标会导致报错。在这种情况下，您需要通过 set_cdata 函数修改图形对象的 cdata 属性来修改指定条形的颜色。通过输入要修改的条形序列号和颜色，可以更改指定条形的颜色。仅当 facecolor 或 edgecolor 属性设置为 "flat"，cdata 才适用。例如：
b, = barh(1:10)
b.set_facecolor("flat")
b.set_cdata(2, [1 0 0])