Plotly.py 风玫瑰图Wind Rose Chart完整指南用px.bar_polar与go.Barpolar绘制极坐标风速风向分布【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py导读风玫瑰图Wind Rose Chart又称极坐标条形图 polar bar chart是气象与环境领域最常用的可视化工具之一用于展示某一地点风速与风向的联合分布。本文基于 plotly.py 官方文档doc/python/wind-rose-charts.md展开先介绍 Plotly Express 高层接口px.bar_polar一行式绘图再深入go.Barpolar图形对象的手工构建方式并结合仓库源码说明参数解析、数据集结构、极坐标轴配置与底层实现原理帮助你掌握从数据准备到成图美化的完整流程。什么是风玫瑰图风玫瑰图以极坐标为坐标系圆周方向theta角度轴 angular axis表示风向如北、东北、东……径向方向r径向轴 radial axis表示风速等级出现的频率或百分比。每一个花瓣扇形代表某个风向区间内、某个风速等级的出现比例扇形越长表示该方向该风速出现越频繁。在 plotly.py 中绘制风玫瑰图有两条路径路径接口特点高层接口px.bar_polar来自 Plotly Express直接吃 DataFrame一行代码完成数据到图形的映射自动分面配色、生成图例底层接口go.Barpolar来自 Graph Objects手动指定r、theta等数组细粒度控制每个 trace 与极坐标轴适合构建复杂、定制化图表两条路径最终都生成同一个go.Figure对象参见 Plotly Express 入口源码px.bar_polar内部通过make_figure以constructorgo.Barpolar构建图形因此可以按需混用。使用 Plotly Express 快速绘制风玫瑰图Plotly Express 是 plotly.py 的高层接口它以 DataFrame 为核心输入、自动完成数据分组与样式映射相关介绍见 plotly-express.md 与 px-arguments.md。绘制风玫瑰图只需三步加载数据、调用px.bar_polar、显示图形。import plotly.express as px df px.data.wind() fig px.bar_polar( df, rfrequency, thetadirection, colorstrength, templateplotly_dark, color_discrete_sequencepx.colors.sequential.Plasma_r, ) fig.show()内置风速数据集px.data.wind()示例中的df px.data.wind()加载的是 plotly.py 内置的风速示例数据集。从源码注释可见该数据集中每一行代表某个主方位上的某个风速等级及其频率返回一个包含 128 行、3 列的数据表见 plotly/data/init.pydirection风向8 个主方位共 16 个风向区间中的方位标签strength风速强度等级如 5 m/s、5-8 m/s、8-11 m/s、11-14 m/s等共 8 级frequency该风向、该风速等级出现的频率百分比。它天然就是宽表—图形映射的教学样本r指定频率列作为径向长度theta指定风向列作为角度位置color指定风速等级列用于分组着色。px.bar_polar关键参数说明px.bar_polar的函数签名与参数默认值在 plotly/express/_chart_types.py 中定义核心参数如下参数默认值作用data_frameNone数据源 DataFrame也可传入 numpy 数组或字典rNone径向轴数据列名决定扇形长度thetaNone角度轴数据列名决定扇形方位colorNone分组/着色列名每个取值生成一个 trace 与一种颜色pattern_shapeNone分组/纹理列名可为不同组附加填充图案baseNone扇形起始径向值用于堆叠或悬浮条形animation_frame/animation_groupNone动画帧列名与分组列名支持播放式动画category_ordersNone手动指定分类顺序如风向的北→东北→东…循环顺序color_discrete_sequenceNone离散配色序列示例使用px.colors.sequential.Plasma_r反转的 Plasma 连续色阶color_discrete_mapNone手动映射类别 → 颜色barnormNone条形归一化方式fraction归一为比例或percent归一为百分比barmoderelative条形模式relative从零堆叠/overlay叠加/group分组directionclockwise角度轴方向clockwise顺时针罗盘式或counterclockwise逆时针数学式start_angle90角度轴起始角默认 90 度对应正北罗盘习惯range_r/range_thetaNone径向轴与角度轴显示范围log_rFalse径向轴是否使用对数刻度templateNone主题模板如plotly_dark、plotly、seaborntitle/subtitleNone图表标题与副标题width/heightNone画布像素尺寸值得注意的是barmoderelative是默认值它与layout_patchdict(barnormbarnorm, barmodebarmode)一起通过 make_figure 注入到最终 layout 中——这正是每个风速等级从圆心向外堆叠、彼此相接的关键也正是风玫瑰图各等级花瓣连成整片的标准形态。视觉风格控制templateplotly_dark套用暗色主题模板适合深色背景的报告与演示。color_discrete_sequencepx.colors.sequential.Plasma_r以连续色阶的反向顺序作为离散分组颜色让风速由低到高呈现从亮到深的渐变层次便于阅读。仓库中的 Percy 可视化回归测试tests/percy/plotly-express.py使用了几乎完全一致的调用方式rfrequency、thetadirection、colorstrength、templateplotly_dark、Plasma 色阶说明这就是官方认可的典型用法可直接照抄复现。使用go.Barpolar手工构建风玫瑰图当需要精细控制例如手动叠加多个风速等级、自定义标签文本时使用 Graph Objects 接口逐条添加go.Barpolartrace。下面复现官方文档中的经典示例美国内布拉斯加州 Laurel 地区的风速分布风玫瑰图。import plotly.graph_objects as go fig go.Figure() fig.add_trace(go.Barpolar( r[77.5, 72.5, 70.0, 45.0, 22.5, 42.5, 40.0, 62.5], name11-14 m/s, marker_colorrgb(106,81,163) )) fig.add_trace(go.Barpolar( r[57.5, 50.0, 45.0, 35.0, 20.0, 22.5, 37.5, 55.0], name8-11 m/s, marker_colorrgb(158,154,200) )) fig.add_trace(go.Barpolar( r[40.0, 30.0, 30.0, 35.0, 7.5, 7.5, 32.5, 40.0], name5-8 m/s, marker_colorrgb(203,201,226) )) fig.add_trace(go.Barpolar( r[20.0, 7.5, 15.0, 22.5, 2.5, 2.5, 12.5, 22.5], name 5 m/s, marker_colorrgb(242,240,247) )) fig.update_traces(text[North, N-E, East, S-E, South, S-W, West, N-W]) fig.update_layout( titledict(textWind Speed Distribution in Laurel, NE), font_size16, legend_font_size16, polar_radialaxis_ticksuffix%, polar_angularaxis_rotation90, ) fig.show()逐段拆解每个go.Barpolartrace 代表一个风速等级r为该等级在 8 个风向方位上的频率数组单位是百分比本例最大值 77.5% 表示该方向该风速的出现频率高达 77.5%name作为图例名marker_color用rgb()指定花瓣颜色。4 个 trace 从深到浅排列形成典型的风玫瑰同心分级结构。fig.update_traces(text[...])为每个数据点附加文本标签。这里传入 8 个方位名North、N-E、East、S-E、South、S-W、West、N-W默认显示在极坐标扇形的外部。fig.update_layout(...)一次性配置全局布局titledict(text...)设置标题font_size16/legend_font_size16统一调整全局字体与图例字号polar_radialaxis_ticksuffix%径向轴刻度后缀加%明确频率单位polar_angularaxis_rotation90角度轴起始位置旋转 90 度让 0° 指向正北符合罗盘惯例。go.Barpolar的核心属性go.Barpolar类定义在 plotly/graph_objs/_barpolar.py其_valid_props列出了全部受支持属性常用者包括属性类型说明r数值数组径向值频率/数值决定扇形长度theta数组角度值度数或类别标签决定扇形方位thetaunitdegrees/radians未提供类别标签时角度值的单位r0/dr数值径向起始值与步长配合等差数列使用theta0/dtheta数值角度起始值与步长dtheta默认等于子图周期除以r长度见 源码注释base数值/数组条形基准线位置径向轴单位在stackbarmode 下设置base的 trace 会被排除并按overlay绘制见 源码注释width数值/数组扇形角度宽度度数marker字典/Marker对象颜色、边框、图案等视觉属性text数组数据点文本标签hovertext/hovertemplate字符串/数组悬停文本与模板模板支持%{r}、%{theta}等变量与 d3-format 数字格式hoverinfo标志串rthetatextname组合或all/none/skip见 源码注释customdata数组附加到每个数据点的自定义数据可被悬停/点击事件读取showlegend/legendgroup/legend布尔/字符串图例显示与分组控制opacity/visible数值/枚举透明度与显隐selected/unselected字典选中/未选中状态的样式配合selectedpointssubplot字符串多极坐标子图时指定所属子图如polar2uid/uirevision字符串数据点身份与交互状态持久化控制极坐标轴的精调径向轴与角度轴风玫瑰图的观感高度依赖极坐标轴配置。在 plotly.py 的布局体系中极坐标子图的轴配置通过layout.polar.radialaxis与layout.polar.angularaxis设置并可借助polar_radialaxis_*、polar_angularaxis_*这类快捷写法直接放在update_layout中。径向轴radial axis常用属性径向轴类定义在 plotly/graph_objs/layout/polar/_radialaxis.py常用属性属性说明ticksuffix刻度标签后缀如%见 源码定义tickfont刻度字体样式range径向显示范围如[0, 100]tickmode/tickvals/ticktext刻度模式与自定义刻度gridcolor/gridwidth网格线颜色与宽度showticklabels是否显示刻度标签title径向轴标题角度轴angular axis常用属性角度轴类定义在 plotly/graph_objs/layout/polar/_angularaxis.py与风玫瑰图最相关的是方位控制属性说明rotation起始位置度。默认情况下directioncounterclockwise时 rotation 为 0对应正东数学惯例directionclockwise时 rotation 为 90对应正北罗盘惯例。数值被约束在 -180~180超出会自动换算如 270 → -90见 源码说明。示例中rotation90配合顺时针方向使 0° 指向正北directionclockwise顺时针/counterclockwise逆时针tickmodelinear/array/auto见 源码定义thetaunit角度单位degrees或radianstickvals/ticktext自定义方位刻度标签可覆盖为[N,N-E,E,...]等罗盘方位gridcolor/gridwidth角度网格线样式一个关键细节示例中同时设置了polar_angularaxis_rotation90但由于go.Barpolar默认按顺时针罗盘方向绘制且theta传入的是方位字符串而非度数Plotly 会自动按 8 个主方位等分 360°——rotation90确保第一个方位North落在正北位置这是风玫瑰图方向正确性的核心。从文档到源码官方用法的一致性印证高层封装px.bar_polar在 plotly/express/_chart_types.py 中仅一行调用make_figure(argslocals(), constructorgo.Barpolar, layout_patch...)说明它与go.Barpolar是同一图形、不同入口的关系所有px.bar_polar参数最终都汇入make_figure的统一数据处理管线plotly/express/_core.py后者完成默认值级联、DataFrame 构建、分组映射与 trace 生成。测试印证Percy 视觉回归测试 tests/percy/plotly-express.py 对px.bar_polar的用法与本文示例完全一致可作为官方标准用法的实证。数据集结构px.data.wind()返回 128 行、3 列direction/strength/frequency其 docstring 明确每行代表一个主方向上的风速等级及其频率plotly/data/init.py这是理解风玫瑰图数据模型的最佳入口。进阶技巧与注意事项堆叠模式px.bar_polar默认barmoderelative各风速等级从圆心向外堆叠形成完整花瓣若想叠加对比可改为barmodeoverlay并配合透明度。归一化设置barnormpercent可让每个风向区间的频率之和归一为 100%更符合气象统计习惯。动画若数据包含时间维度可用animation_frame生成随时间变化的风玫瑰动画。多子图通过layout.polar、layout.polar2等与subplotpolar2搭配可在一张图中并排展示多个站点的风玫瑰。风向顺序用category_orders指定风向列的顺序如[N,N-E,E,...]避免 Plotly 按字母序打乱罗盘方位。显示环境fig.show()在 Jupyter Notebook / VS Code 交互环境中直接渲染也可用fig.write_html(wind_rose.html)导出独立 HTML 文件分享。小结风玫瑰图是展示风速风向联合分布的标准图表plotly.py 提供了高层快速出图px.bar_polar 底层精细定制go.Barpolar两条互补路径快速场景px.bar_polar(df, r..., theta..., color...)一行完成数据映射、配色与堆叠定制场景go.Barpolar逐 trace 构建配合polar_radialaxis_ticksuffix、polar_angularaxis_rotation等极坐标轴属性实现罗盘式精确布局。掌握了本文中的参数、默认值、数据集结构与源码实现依据你即可在任意项目中复现官方示例并根据实际气象数据站点观测或再分析资料自由定制属于自己的风玫瑰图。更多px.bar_polar参数细节可继续查阅 styling-plotly-express.md 等主题文档。【免费下载链接】plotly.pyThe interactive graphing library for Python :sparkles:项目地址: https://gitcode.com/gh_mirrors/pl/plotly.py创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考