Main Content

本页翻译不是最新的。点击此处可查看最新英文版本。

Binscatter 属性

bin 化散点图的外观和行为

Binscatter 的属性可以控制分 bin 散点图的外观和行为。通过更改属性值,您可以修改显示的各个方面。使用圆点表示法引用特定的对象和属性:

h = binscatter(randn(1,100),randn(1,100));
N = h.NumBins
h.NumBins = [3 3]

bin

全部展开

bin 数量,指定为标量或二元素向量 [Nx Ny]

  • 如果 NumBins 指定为二元素向量 [Nx Ny],则 binscatter 在 x 维度上划分 Nx 个 bin,在 y 维度上划分 Ny 个 bin。

  • 如果 NumBins 指定为标量,则 NxNy 都设置为标量值。

未放大坐标区时,binscatter 在初始绘图上沿 x 和 y 维度分别划分 NxNy 个 bin。(当 XLimModeYLimMode 属性都设置为 'auto' 时,不会放大坐标区。)缩放时,binscatter 将调整 bin 的数量,以保持一个合适的 bin 大小,使绘图的可见部分大约划分为 Nx×Ny 个 bin。

每个维度中的最大 bin 数为 250。默认 bin 数量是根据数据大小和标准差计算得出的,不超过 100。

示例: [10 20]

数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

bin 数量的选择模式,指定为 'auto''manual'。如果使用默认值 'auto',将按照 Scott 规则 [3.5*std(X(:))*numel(X)^(-1/4), 3.5*std(Y(:))*numel(Y)^(-1/4)] 根据数据的多少计算 bin 的数量。

如果您指定 bin 数量,'NumBinsMode' 的值将被设置为 'manual'

开启或关闭空 bin 的显示,指定为 'off''on',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

如果指定 'on'true,将为绘图中落在 bin 范围内但无数据点的图块着色。

此 属性 为只读。

x 维度的 bin 边界,以向量形式返回。

数据类型: single | double | datetime | duration

此 属性 为只读。

y 维度的 bin 边界,以向量形式返回。

数据类型: single | double | datetime | duration

x 维度的数据范围,指定为二元素向量 [Xmin Xmax]

binscatter 仅显示落在指定数据范围 XminXXmax(含边界值)内的数据点。

示例: [0 10]

数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

x 维度数据范围的选择模式,指定为 'auto''manual'。默认值为 'auto',即根据 x 轴上的数据自动调整 bin 范围。

如果您显式指定 XLimits,则 XLimitsMode 自动设置为 'manual'。在这种情况下,将 XLimitsMode 指定为 'auto' 可将 bin 范围重新调整为该数据。

y 维度的数据范围,指定为二元素向量 [Ymin Ymax]

binscatter 仅显示落在指定数据范围 YminYYmax(含边界值)内的数据点。

示例: [0 10]

数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

y 维度数据范围的选择模式,指定为 'auto''manual'。默认值为 'auto',即根据 y 轴上的数据自动调整 bin 范围。

如果您显式指定 YLimits,则 YLimitsMode 自动设置为 'manual'。在这种情况下,将 YLimitsMode 指定为 'auto' 可将 bin 范围重新调整为该数据。

数据

全部展开

数据的 x 坐标,指定为向量。

数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

数据的 y 坐标,指定为向量。

数据类型: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | datetime | duration

此 属性 为只读。

bin 值,以双精度矩阵形式返回。Values 中的第 (i,j) 个条目指定 x 边界为 [XBinEdges(i), XBinEdges(i+1)] 且 y 边界为 [YBinEdges(j), YBinEdges(j+1)] 的 bin 的 bin 计数。

不同编号的 bin 在 Values 中的分布情况及其相对于 x 和 y 轴的方向如下图所示:

例如,bin (1,1) 包括落在每个维度第一个边界上的值。右下角的最后一个 bin 包括落在其任何边界上的值。

透明度

全部展开

图块的透明度,指定为介于 01 之间(含边界值)的一个标量值。binscatter 对所有图块使用相同的透明度。值 1 表示完全不透明,0 则表示完全透明(不可见)。

示例: binscatter(X,Y,'FaceAlpha',0.5) 创建具有半透明 bin 的分 bin 散点图。

图例

全部展开

图例使用的文本,指定为字符向量。文本显示在 binscatter 的图标旁边。

示例: 'Text Description'

对于多行文本,请使用 sprintf 和换行符 \n 创建字符向量。

示例: sprintf('line one\nline two')

您也可以使用 legend 函数指定图例文本。

  • 如果您将该文本指定为 legend 函数的输入参数,则图例将使用该指定文本,同时将 DisplayName 属性设置为与之相同的值。

  • 如果未将该文本指定为 legend 函数的输入参数,则图例将使用 DisplayName 属性中的文本。DisplayName 的默认值是下列值之一。

    • 对于数值输入,DisplayName 是一个字符向量,代表用来构建直方图的输入数据的变量名称。如果输入数据没有变量名称,则 DisplayName 为空,即 ''

    • 对于分类数组输入,DisplayName 为空,即 ''

如果 DisplayName 属性不包含任何文本,则该图例将生成一个字符向量。该字符向量的形式为 'dataN',其中 N 是基于 binscatter 对象在图例条目列表中的位置指定给它的编号。

如果您以交互方式编辑现有图例中的字符向量,则 MATLAB® 会将 DisplayName 属性更新为编辑的字符向量。

在图例中包含对象,指定为 Annotation 对象。将 Annotation 对象的基础 IconDisplayStyle 属性设置为以下值之一:

  • "on" - 在图例中包含对象(默认值)。

  • "off" - 不在图例中包含对象。

例如,要从图例中排除名为 objBinscatter 对象,请将 IconDisplayStyle 属性设置为 "off"

obj.Annotation.LegendInformation.IconDisplayStyle = "off";

您也可以使用 legend 函数控制图例中的项目。将第一个输入参数指定为要包含的图形对象的向量。如果未在第一个输入参数中指定现有图形对象,则该图形对象不会显示在图例中。但在创建图例后添加到坐标区的图形对象会显示在图例中。请考虑在创建所有绘图后创建图例以避免出现额外的项。

交互性

全部展开

可见性状态,指定为 "on""off",或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 "on" 等效于 true"off" 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • "on" - 显示对象。

  • "off" - 隐藏对象而不删除它。您仍然可以访问不可见对象的属性。

数据提示内容,指定为 DataTipTemplate 对象。您可以通过修改底层 DataTipTemplate 对象的属性来控制数据提示中显示的内容。有关属性列表,请参阅 DataTipTemplate 属性

有关修改数据提示的示例,请参阅创建自定义数据提示

注意

findobjfindall 不返回 DataTipTemplate 对象,copyobj 也不复制该对象。

上下文菜单,指定为 ContextMenu 对象。使用此属性在您右键点击对象时显示上下文菜单。使用 uicontextmenu 函数创建上下文菜单。

注意

如果 PickableParts 属性设置为 'none' 或者 HitTest 属性设置为 'off',该上下文菜单将不显示。

选择状态,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true,'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 已选择。如果您在绘图编辑模式下点击对象,则 MATLAB 会将其 Selected 属性设置为 'on'。如果 SelectionHighlight 属性也设置为 'on',则 MATLAB 将在对象周围显示选择句柄。

  • 'off' - 未选择。

选择时显示选择句柄,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true,'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 在 Selected 属性设置为 'on' 时显示选择句柄。

  • 'off' - 永远不显示选择句柄,即使 Selected 属性设置为 'on' 也是如此。

回调

全部展开

鼠标点击回调,指定为下列值之一:

  • 函数句柄

  • 元胞数组,包含一个函数句柄和其他参数

  • 作为有效 MATLAB 命令或函数(在基础工作区中计算)的字符向量(不推荐)

使用此属性在您点击对象时执行代码。如果使用函数句柄指定此属性,则 MATLAB 在执行回调时将向回调函数传递两个参数:

  • 点击的对象 - 从回调函数中访问点击的对象的属性。

  • 事件数据 - 空参数。在函数定义中将其替换为波浪号字符 (~) 以指示不使用此参数。

有关如何使用函数句柄定义回调函数的详细信息,请参阅Create Callbacks for Graphics Objects

注意

如果 PickableParts 属性设置为 'none' 或者 HitTest 属性设置为 'off',则不执行此回调。

对象创建函数,指定为下列值之一:

  • 函数句柄。

  • 第一个元素是函数句柄的元胞数组。元胞数组中的后续元素是传递到回调函数的参数。

  • 包含有效 MATLAB 表达式的字符向量(不推荐)。MATLAB 在基础工作区计算此表达式。

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息,请参阅Create Callbacks for Graphics Objects

此属性指定要在 MATLAB 创建对象时执行的回调函数。MATLAB 将在执行 CreateFcn 回调之前初始化所有属性值。如果不指定 CreateFcn 属性,则 MATLAB 执行默认的创建函数。

对现有组件设置 CreateFcn 属性没有任何作用。

如果将此属性指定为函数句柄或元胞数组,则可以使用回调函数的第一个参数访问正在创建的对象。否则,使用 gcbo 函数访问该对象。

对象删除函数,指定为下列值之一:

  • 函数句柄。

  • 第一个元素是函数句柄的元胞数组。元胞数组中的后续元素是传递到回调函数的参数。

  • 包含有效 MATLAB 表达式的字符向量(不推荐)。MATLAB 在基础工作区计算此表达式。

有关将回调指定为函数句柄、元胞数组或字符向量的详细信息,请参阅Create Callbacks for Graphics Objects

此属性指定在 MATLAB 删除对象时要执行的回调函数。MATLAB 在销毁对象的属性之前执行 DeleteFcn 回调。如果不指定 DeleteFcn 属性,则 MATLAB 执行默认的删除函数。

如果将此属性指定为函数句柄或元胞数组,则可以使用回调函数的第一个参数访问要删除的对象。否则,使用 gcbo 函数访问该对象。

回调执行控件

全部展开

回调中断,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

此属性确定是否可以中断运行中回调。有以下两种回调状态要考虑:

  • 运行中回调是当前正在执行的回调。

  • 中断回调是试图中断运行中回调的回调。

每次执行处理回调队列的命令时,MATLAB 都会确定回调中断行为。这些命令包括 drawnowfigureuifiguregetframewaitforpause

如果运行中回调不包含上述命令之一,则不会发生中断。MATLAB 首先完成执行运行中回调,然后执行中断回调。

如果运行中回调确实包含上述命令之一,则由运行中回调所属对象的 Interruptible 属性来确定是否发生中断:

  • 如果 Interruptible 的值为 'off',则不会发生中断。此时,由中断回调所属对象的 BusyAction 属性确定中断回调是被丢弃还是添加到回调队列中。

  • 如果 Interruptible 的值为 'on',则发生中断。下次 MATLAB 处理回调队列时,它会停止运行中回调的执行,并执行中断回调。在中断回调完成后,MATLAB 将继续执行运行中回调。

注意

回调的中断和执行在以下情况下会有不同的表现:

  • 如果中断回调是 DeleteFcnCloseRequestFcnSizeChangedFcn 回调,则无论是否存在 Interruptible 属性值都会发生中断。

  • 如果运行中回调当前正在执行 waitfor 函数,则无论是否存在 Interruptible 属性值都会发生中断。

  • 如果中断回调由 Timer 对象所有,则回调将根据调度执行,而不考虑 Interruptible 属性值。

注意

发生中断时,MATLAB 不保存属性状态或显示内容。例如,gcagcf 命令返回的对象可能会在另一个回调执行时发生改变。

回调排队,指定为 'queue''cancel'BusyAction 属性决定 MATLAB 如何处理中断回调的执行。有以下两种回调状态要考虑:

  • 运行中回调是当前正在执行的回调。

  • 中断回调是试图中断运行中回调的回调。

BusyAction 属性仅在同时满足以下两个条件时才确定回调排队行为:

在这些情况下,由中断回调所属对象的 BusyAction 属性确定 MATLAB 如何处理中断回调。以下是 BusyAction 属性的可能值:

  • 'queue' - 将中断回调放入队列中,以便在运行中回调执行完毕后进行处理。

  • 'cancel' - 不执行中断回调。

捕获鼠标点击的能力,指定为以下值之一:

  • 'visible' - 仅当对象可见时才捕获鼠标点击。Visible 属性必须设置为 'on'HitTest 属性决定是 Binscatter 对象响应点击还是前代响应点击。

  • 'none' - 无法捕获鼠标点击。点击 Binscatter 对象会将点击操作传递给图窗窗口的当前视图中该对象下方的对象。Binscatter 对象的 HitTest 属性没有任何作用。

对捕获的鼠标点击的响应,指定为 'on''off',或者指定为数值或逻辑值 1 (true) 或 0 (false)。值 'on' 等效于 true,'off' 等效于 false。因此,您可以使用此属性的值作为逻辑值。该值存储为 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值。

  • 'on' - 触发 Binscatter 对象的 ButtonDownFcn 回调。如果您已定义 ContextMenu 属性,则调用上下文菜单。

  • 'off' - 触发满足以下条件之一的 Binscatter 对象的最近前代的回调:

    • HitTest 属性设置为 'on'

    • PickableParts 属性所设置的值允许前代捕获鼠标点击

注意

PickableParts 属性决定 Binscatter 对象是否可以捕获鼠标点击。如果无法捕获,则 HitTest 属性没有任何作用。

此 属性 为只读。

删除状态,以 matlab.lang.OnOffSwitchState 类型的 on/off 逻辑值形式返回。

DeleteFcn 回调开始执行时,MATLAB 会将 BeingDeleted 属性设置为 'on'BeingDeleted 属性将一直保持 'on' 设置状态,直到组件对象不再存在为止。

在查询或修改对象之前,请先检查其 BeingDeleted 属性的值,以确认它不是待删除项。

父级/子级

全部展开

父级,指定为 Axes 对象。

子级,以空的 GraphicsPlaceholder 数组或 DataTip 对象数组形式返回。使用此属性来查看在图上绘制的数据提示的列表。

不能使用 Children 属性添加或删除子级。要向此列表中添加子级,请将 DataTip 对象的 Parent 属性设置为图对象。

父级的 Children 属性中对象句柄的可见性,指定为下列值之一:

  • "on" - 对象句柄始终可见。

  • "off" - 对象句柄始终不可见。该选项用于防止另一函数无意中对其进行更改。将 HandleVisibility 设置为 "off" 可在执行该函数时暂时隐藏句柄。

  • "callback" - 对象句柄在回调或回调所调用的函数中可见,但在从命令行调用的函数中不可见。此选项阻止通过命令行访问对象,但允许回调函数访问对象。

如果父级的 Children 属性中未列出该对象,则通过搜索对象层次结构或查询句柄属性获取对象句柄的函数无法返回该对象。此类函数的示例包括 getfindobjgcagcfgconewplotclaclfclose 函数。

隐藏的对象句柄仍有效。将根 ShowHiddenHandles 属性设置为 "on" 以列出所有对象句柄,而不管其 HandleVisibility 属性设置如何。

标识符

全部展开

此 属性 为只读。

图形对象的类型,以 'binscatter' 形式返回。使用该属性在绘制层次结构中查找指定类型的所有对象,例如,使用 findobj 搜索该类型。

对象标识符,指定为字符向量或字符串标量。您可以指定唯一的 Tag 值作为对象的标识符。如果需要访问您代码中其他位置的对象,可以使用 findobj 函数基于 Tag 值搜索对象。

用户数据,指定为任何 MATLAB 数组。例如,您可以指定标量、向量、矩阵、元胞数组、字符数组、表或结构体。使用此属性存储对象上的任意数据。

如果您在 App 设计工具中工作,请在该 App 中创建公共或私有属性以共享数据,而不是使用 UserData 属性。有关详细信息,请参阅在用 App 设计工具创建的 App 内共享数据

版本历史记录

在 R2017b 中推出

全部展开

另请参阅