plotly 添加标注(annotation)

添加标注 annotation

import plotly.io as pio
import plotly.express as px
import plotly.graph_objects as go
import pandas as pd
import numpy as np

# 设置plotly默认主题
pio.templates.default = 'plotly_white'

# 设置pandas打印时显示所有列
pd.set_option('display.max_columns', None)

annotation 常用参数介绍及示例

详细参数见：

• https://plotly.com/python/reference/layout/annotations/

• https://plotly.com/python-api-reference/generated/plotly.graph_objects.layout.html#plotly.graph_objects.layout.Annotation

• x：设置 annotation 的 x 轴位置。如果坐标轴的类型是 log，那么你传入的 x 应该与取 log 后的值相对应；如果坐标轴的类型是 date，那么你传入的 x 也必须是日期字符串；如果坐标轴的类型是 category，那么你传入的 x 应该是一个整数，代表你期望标记的第 x 个类别，注：类别从0开始，按照出现的顺序依次递增。

  • 浮点数、整数、字符串

• y：设置 annotation 的 y 轴位置。如果坐标轴的类型是 log，那么你传入的 y 应该与取 log 后的值相对应；如果坐标轴的类型是 date，那么你传入的 y 也必须是日期字符串；如果坐标轴的类型是 category，那么你传入的 y 应该是一个整数，代表你期望标记的第 y 个类别，注：类别从0开始，按照出现的顺序依次递增。

  • 浮点数、整数、字符串

• text：设置与此 annotation 相关联的文本。plotly支持部分HTML标签，比如：换行（<br>）、粗体（<b></b>）、斜体（<i></i>）、超链接（<a href='...'></a>）等，标签 <em>、<sup>、<sub>、<span>也支持。

  • 字符串类型
  • 可以转换为字符串的数字

• opacity：设置 annotation 的不透明度，包括 text 和 arrow。

  • [0, 1] 之间的浮点数

• showarrow：是否显示指向箭头。如果为 True，则 text 放置在箭头尾部；如果为 False，则text会放在指定的 (x, y) 位置

  • 布尔类型

• arrowcolor：设置整个箭头的颜色

  • 十六进制字符串，如 #ff0000
  • rgb/rgba 字符串，如 rgb(255,0,0)
  • hsl/hsla 字符串，如 hsl(0,100%,50%)
  • hsv/hsva 字符串，如 hsv(0,100%,100%)
  • CSS 颜色字符串，如 darkblue、lightyellow 等

• arrowhead：设置 annotation 箭头头部的样式。

  • 可取 [0, 8] 之间的整数，（经测试 8 不可用）

• arrowside：设置箭头头部的位置。

  • 字符串，可取 end、start 或者 end+start、none。 end+start 表示双向箭头

• arrowsize：设置箭头头部的大小，与 arrowwidth 属性有关（经测试，该值必须小于 arrowwidth 一定的范围， 如果 arrowwidth 设置为3 ，那么该值不能超过 2.3）。

  • 可取 [0.3, inf] 之间的浮点数或整数，默认为1

• arrowwidth：设置整个箭头的线条宽度

  • 可取 [0.1, inf] 之间的浮点数或整数

• font：设置 text 的字体。

  • 字典类型，支持三个属性：
    • color：设置字体颜色，字符串
    • family：设置字体，字符串，可以为 Arial、Balto、Courier New、Droid Sans、Droid Serif、Droid Sans Mono、Gravitas One、Old Standard TT、Open Sans、Overpass、PT Sans Narrow、Raleway、Times New Roman
    • size：设置字体大小

fig = go.Figure()

fig.add_trace(go.Scatter(
    x=[0, 1, 2, 3, 4, 5, 6, 7, 8],
    y=[0, 1, 3, 2, 4, 3, 4, 6, 5],
))

fig.add_trace(go.Scatter(
    x=[0, 1, 2, 3, 4, 5, 6, 7, 8],
    y=[0, 4, 5, 1, 2, 2, 3, 4, 2]
))

# 使用 fig.add_annotation 添加标注
fig.add_annotation(
    x=2, y=5,
    text='with arrow',
    font={'color': 'red', 'size': 14, 'family': 'Arial'},
    showarrow=True, arrowhead=4, arrowwidth=2, arrowside='end', arrowsize=0.7, arrowcolor='red',
    opacity=0.5,
)

fig.add_annotation(
    x=4, y=4,
    text='without arrow',
    font={'color': 'blue', 'size': 14},
    showarrow=False,
)

fig.write_image('../pic/annotation_1.png', scale=10)
fig.show()

• xanchor：设置 text 框的水平锚点，这个锚点与 x 参数相关。例如：如果 x 设为 1，xref 设为 “paper”，并且 xanchor 设为 “right”，那么标注的最右边将位于图的最右侧。

  • 字符串，可取 auto， left， center，right

• yanchor：设置 text 框的竖直锚点，这个锚点，与 y 参数相关。例如：如果 y 设为 1，yref 设为 “paper”，并且 yanchor 设为 “top”，那么标注的顶部将位于图的最上方。

  • 字符串，可取 auto， top， middle， bottom

• ax：设置箭头尾部关于箭头头部的 x 分量。如果 axref为 “pixel”，正（负）分量值对应于一个从右到左（从左到右）的箭头。如果 axref 不是 “pixel”，并且与 xref 完全相同，那么 ax就是该轴上的一个绝对值，就像 x 与 xref 的工作方式一样。

  • 接受任何类型，实际传入一个浮点数/整数/字符串，与 x 类似

• ay：设置箭头尾部关于箭头头部的 y 分量。如果 ayref为 “pixel”，正（负）分量值对应于一个从下到上（从上到下）的箭头。如果 ayref 不是 “pixel”，并且与 yref 完全相同，那么 ay 就是该轴上的一个绝对值，就像 y 与 yref 的工作方式一样。

  • 接受任何类型，实际传入一个浮点数/整数/字符串，与 y 类似

• axref：与 xref 类似，其中 “pixel” 相当于 xref 中的 “paper”。为了使箭头的绝对定位发挥作用，axref 必须与 xref 完全相同，否则无论 axref 设置为什么值，都将变为 “pixel”。 对于相对定位，axref 可以设置为 “pixel”， 在这种情况下，ax 的值是以相对于 x 的像素来指定的。绝对定位对趋势线的标注很有用，它在缩放时会继续显示正确的趋势，相对定位对于指定标注点的文本偏移很有用。

  • 可以取 pixel, 或者满足正则表达式 ^x([2-9]|[1-9][0-9]+)?( domain)?$ 的字符串

• ayref：与 yref 类似，其中 “pixel” 相当于 yref 中的 “paper”。为了使箭头的绝对定位发挥作用，ayref 必须与 yref 完全相同，否则无论 ayref 设置为什么值，都将变为 “pixel”。 对于相对定位，ayref 可以设置为 “pixel”， 在这种情况下，ay 的值是以相对于 y 的像素来指定的。绝对定位对趋势线的标注很有用，它在缩放时会继续显示正确的趋势，相对定位对于指定标注点的文本偏移很有用。

  • 可以取 pixel, 或者满足正则表达式 ^y([2-9]|[1-9][0-9]+)?( domain)?$ 的字符串

• xref：设置标注的 x 坐标轴。如果设置为一个x轴id（例如：“x” 或 “x2”），那么 x 参数将代表对这个坐标轴的操作。如果设置为 “paper”，那么 x 参数代表整个绘画区域的绝对坐标，即 0（1）表示左侧（右侧）。如果在 x轴id后面加上 “domain”（空格分隔，如 “x2 domain”），那么其与 “paper” 的效果类似，但是以该轴的长度为基准，不再以整个绘画区域为基准，因此此时的相对坐标，相对的是这个轴，而不是整个绘画区域，例如：“x2 domain” 指的是第二个x轴的值域，此时参数 x=0.5 表示第二个x轴值域的中间点。

  • 可以取 paper，或者满足正则表达式 ^x([2-9]|[1-9][0-9]+)?( domain)?$ 的字符串

• yref：设置标注的 y 坐标轴。如果设置为一个y轴id（例如：“y” 或 “y2”），那么 y 参数将代表对这个坐标轴的操作。如果设置为 “paper”，那么 y 参数代表整个绘画区域的绝对坐标，即 0（1）表示下侧（上侧）。如果在 y轴id后面加上 “domain”（空格分隔，如 “y2 domain”），那么其与 “paper” 的效果类似，但是以该轴的长度为基准，不再以整个绘画区域为基准，因此此时的相对坐标，相对的是这个轴，而不是整个绘画区域，例如：“y2 domain” 指的是第二个y轴的值域，此时参数 y=0.5 表示第二个y轴值域的中间点。

  • 可以取 paper，或者满足正则表达式 ^y([2-9]|[1-9][0-9]+)?( domain)?$ 的字符串

• align：设置 text 的水平对准方式。只有当 text 占据了两行及以上（使用了 <br> 换行标签）或者显式指明了 width 时才有效。

  • 可取 left, center, right

• valign：设置 text 的竖直对准方式。只有显式指明了 height 才有效。

  • 可取 top, middle, bottom

• width：显示指明 text 框的宽度，默认为 null， 即根据 text 自动设置宽度，过宽的 text 会被裁剪，不会自动换行，可以使用 <br> 标签进行换行。

  • 可取 [1, inf] 之间的浮点数或整数

• height：显式指明 text 框的高度，默认为 null，即根据 text 自动设置高度，过高的 text 会被裁剪。

  • 可取 [1, inf] 之间的浮点数或整数

fig = go.Figure()

fig.add_trace(go.Scatter(
    x=[0, 1, 2, 3, 4, 5, 6, 7, 8],
    y=[0, 1, 3, 2, 4, 3, 4, 6, 5],
))

fig.add_trace(go.Scatter(
    x=[0, 1, 2, 3, 4, 5, 6, 7, 8],
    y=[0, 4, 5, 1, 2, 2, 3, 4, 2]
))

# 使用 fig.update_layout 添加标注
fig.update_layout(
    annotations=[
        dict(
            x=2, y=5,
            text='max=5',
            showarrow=True, arrowhead=4, arrowwidth=2, arrowsize=0.7,
            xanchor='left',
            yanchor='bottom',
            axref='pixel', ax=20,
        ),
        dict(
            x=3, y=1,
            text='value=1',
            showarrow=True, arrowhead=4, arrowwidth=2, arrowsize=0.7,
            axref='x domain', ax=-30,
            ayref='y domain', ay=30,
        ),
        dict(
            x=0.5, xref='x domain', y=0.5, yref='y domain',
            text='middle annotation',
            font={'size': 16, 'color': '#b6beab'},
            showarrow=False,
            yanchor='bottom'
        )
    ]
)


fig.write_image('../pic/annotation_2.png', scale=10)
fig.show()

• bgcolor：设置包裹 text 的文本框的背景颜色。
  • 十六进制字符串，如 #ff0000
  • rgb/rgba 字符串，如 rgb(255,0,0)
  • hsl/hsla 字符串，如 hsl(0,100%,50%)
  • hsv/hsva 字符串，如 hsv(0,100%,100%)
  • CSS 颜色字符串，如 darkblue、lightyellow 等
• bordercolor：设置包裹 text 的文本框的边框颜色。
  • 十六进制字符串，如 #ff0000
  • rgb/rgba 字符串，如 rgb(255,0,0)
  • hsl/hsla 字符串，如 hsl(0,100%,50%)
  • hsv/hsva 字符串，如 hsv(0,100%,100%)
  • CSS 颜色字符串，如 darkblue、lightyellow 等
• borderpad：设置包裹 text 的文本框的四周填充大小。
  • 可取 [0, inf] 中的浮点数或整数
• borderwidth：设置包裹text的文本框的边框宽度。
  • 可取 [0, inf] 中的浮点数或整数
• startarrowhead：设置起始标注箭头头部的样式，当 arrowside 为 “start” 或 "end+start"时有效。与 arrowside作用一样。
  • 可取 [0, 8] 之间的整数，（经测试 8 不可用）
• startarrowsize：设置起始标注箭头头部大小，当 arrowside 为 “start” 或 "end+start"时有效。与 arrowsize作用一样，查看 arrowsize。
  • 可取 [0.3, inf] 之间的浮点数或整数，默认为1
• textangle：设置 text 的水平旋转角度。
  • [-180, 180]之间的浮点数或整数，超过此范围的数将被转换为等价的值，例如 270度等价于-90度。
• visible：设置是否显示此标注。
  • 布尔类型
• xshift：将整个标注向右（正值）或向左（负值）移动这些像素值。
  • 整数或浮点数
• yshift： 将整个标注向上（正值）或向下（负值）移动这些像素值。
  • 整数或浮点数
• standoff：将结束箭头的头部远离指定标注点一定距离。
  • [0, inf] 之间的浮点数或整数
• startstandoff：将开始箭头的头部远离 text 一定距离。
  • [0, inf] 之间的浮点数或整数

fig = go.Figure()

fig.add_trace(go.Scatter(
    x=[0, 1, 2, 3, 4, 5, 6, 7, 8],
    y=[0, 1, 3, 2, 4, 3, 4, 6, 5],
))

fig.add_trace(go.Scatter(
    x=[0, 1, 2, 3, 4, 5, 6, 7, 8],
    y=[0, 4, 5, 1, 2, 2, 3, 4, 2]
))

# 使用 fig.update_layout 添加标注
fig.update_layout(
    annotations=[
        dict(
            x=2, y=5,
            text='max=5',
            showarrow=True, startarrowhead=4, arrowwidth=2, startarrowsize=0.7, arrowside='start',
            xanchor='left',
            yanchor='bottom',
            axref='pixel', ax=20,
            xshift=5, yshift=5,
            
        ),
        dict(
            x=3, y=1,
            text='value=1',
            showarrow=True, arrowhead=4, arrowwidth=2, arrowsize=0.7,
            axref='x domain', ax=-30,
            ayref='y domain', ay=30,
            font={'size': 16, 'color': '#ffffff', 'family': 'Courier New, monospace'},
            bgcolor='#ff7f0e', borderpad=4, bordercolor='#c7c7c7', borderwidth=2,
            standoff=5, 
        ),
        dict(
            x=0.5, xref='x domain', y=0.5, yref='y domain',
            text='middle annotation', textangle=-30,
            font={'size': 24, 'color': '#b6beab'},
            showarrow=False,
        )
    ]
)


fig.write_image('../pic/annotation_3.png', scale=10)
fig.show()