Python rho-plus(rho_plus)全量技术文档

rho_plus（PyPI包名：rho-plus/rho_plus，最新稳定版0.6.0）是Python跨库数据可视化美化工具包，面向Matplotlib/Seaborn/Plotly/Bokeh/Altair五大主流绘图库，统一图表主题、配色、绘图快捷工具，主打一站式规范可视化样式、降低多库统一美化成本，MIT开源协议，作者Nicholas Miklaucic。

区分：地球物理Rhoplus大地电磁校正算法≠本Python可视化rho-plus包。

一、包整体核心功能

1. 统一跨平台明暗主题系统（核心功能1）

内置Light浅色、Dark深色两套成套主题，一键全局配置Matplotlib、Seaborn、Plotly、Bokeh、Altair全部绘图引擎，实现全项目图表风格统一，避免多绘图库配色、字体、边框割裂问题。

• 自动适配：坐标轴、图例、网格、刻度、画布背景、字体大小、线条粗细全参数自动化配置。

2. 自研专业色板（核心功能2）

内置12套科学定量配色方案（inferna、veridian、sundown、frost等），全部注册为matplotlib原生colormap，支持正向/反向（后缀_r），色板特点：

• 色阶均匀、色盲友好、明暗模式下色差值稳定，适配科研论文、热力图、等高线、分类填充图；
• 三种调用格式：rho_xxx(matplotlib色板)、list_xxx(颜色RGB列表)、直接字符串rho_inferna。

3. 绘图快捷工具集（辅助功能）

1. 自动画布布局：一键生成多子图规整布局，替代繁琐plt.subplots()参数配置；
2. 坐标轴优化：自动隐藏冗余边框、智能刻度格式化、科学计数一键切换；
3. Jupyter交互增强：图表自动自适应单元格尺寸、暗色环境自动切换Dark主题；
4. 批量导出：统一dpi、透明背景、标准尺寸保存图片（png/svg/pdf）。

4. 生态兼容

无缝对接Pandas/Numpy，直接适配DataFrame内置绘图、Seaborn高级统计绘图（箱线/小提琴/聚类热力）。

二、安装教程

1. 基础安装（推荐）

# 最新版0.6.0（支持Python3.8~3.12）
pip install rho_plus -U
# 指定历史稳定版0.5.1（3.8~3.11）
pip install rho-plus==0.5.1

PyPI包名两种写法均可：rho_plus/rho-plus，底层为同一个包。

2. 完整依赖一键安装（全绘图库环境）

pip install rho_plus matplotlib seaborn plotly bokeh altair numpy pandas hsluv>=5.0.3,<6.0.0

硬性依赖：numpy>=1.21、hsluv[5.0.3~6.0.0)；Python版本约束：3.8 ≤ Python ≤3.12（0.6.0）。

3. 源码安装（开发调试）

git clone https://github.com/nicholas-miklaucic/rho-plus.git
cd rho-plus
pip install .

三、核心语法与关键参数

基础导入

import rho_plus as rp
import matplotlib.pyplot as plt
import seaborn as sns

1. 全局主题配置：rp.mpl_setup()（最常用API）

函数原型

rp.mpl_setup(is_dark:bool=False, setup_all:bool=True, font_scale:float=1.0)

参数	取值	说明
is_dark	True/False	True启用深色主题，False浅色（默认）
setup_all	True/False	True=一次性配置matplotlib+seaborn，False仅matplotlib
font_scale	浮点(0.5~2.0)	全局字体缩放系数，论文绘图常用1.2

示例：rp.mpl_setup(is_dark=True, font_scale=1.1)全局深色+放大字体。

2. 色板调用三大语法

# 方式1：matplotlib直接传参（字符串前缀rho_）
plt.contourf(data, cmap="rho_inferna")
# 方式2：rp内置matplotlib色板对象
cmap = rp.mpl_inferna_r # _r代表反转色阶
# 方式3：获取RGB颜色列表（seaborn/pandas用）
color_list = rp.list_veridian

内置色板清单：inferna、veridian、sundown、frost、ember、glacier、twilight、coast八大常用定量色板。

3. 多引擎主题统一：rp.setup_all_engines()

# 一键配置Plotly/Bokeh/Altair全库主题
rp.setup_all_engines(is_dark=False)

4. 快捷画布生成：rp.figure()

替代plt.subplots，自动优化边距、布局

fig, ax = rp.figure(nrows=2,ncols=1,figsize=(8,6),tight=True)

|参数|说明|
|nrows/ncols|子图行列数|
|tight|自动紧凑布局，默认True|
|figsize|画布尺寸|

四、8个落地实战案例（可直接运行）

全部案例基于rho_plus==0.6.0，附带numpy/pandas模拟数据

案例1：Matplotlib折线图+浅色主题（基础单图）

import numpy as np
import rho_plus as rp
rp.mpl_setup(is_dark=False,font_scale=1.0) #启用浅色主题
x = np.linspace(0,10,100)
y1 = np.sin(x);y2=np.cos(x)
fig,ax=rp.figure()
ax.plot(x,y1,label="sin",color=rp.list_inferna[0],lw=2)
ax.plot(x,y2,label="cos",color=rp.list_inferna[3],lw=2)
ax.legend();ax.grid(alpha=0.3)
plt.show()

案例2：深色主题热力图（科研数据分布）

import seaborn as sns
import numpy as np
import rho_plus as rp
rp.mpl_setup(is_dark=True)
data = np.random.randn(12,15)
fig,ax=rp.figure(figsize=(7,5))
#使用rho自研色板
sns.heatmap(data,cmap=rp.mpl_veridian_r,ax=ax,cbar_kws={"shrink":0.8})
ax.set_title("Darkmode Heatmap")
plt.show()

案例3：Seaborn分类箱线图（业务统计）

import pandas as pd,seaborn as sns
import rho_plus as rp
rp.mpl_setup()
df=pd.DataFrame({"group":["A","B","C"]*30,"value":np.random.normal(50,8,90)})
fig,ax=rp.figure()
sns.boxplot(data=df,x="group",y="value",palette=rp.list_sundown,ax=ax)
plt.show()

案例4：Plotly交互式图表（网页看板）

import plotly.express as px
import pandas as pd
import rho_plus as rp
rp.setup_all_engines(is_dark=False) #统一plotly主题
df=pd.DataFrame({"x":range(20),"y":np.random.rand(20)})
fig=px.line(df,x="x",y="y",color_discrete_sequence=rp.list_frost)
fig.show()

案例5：Bokeh交互式散点图（数据分析交互）

from bokeh.plotting import show,figure
import numpy as np
import rho_plus as rp
rp.setup_all_engines(is_dark=True)
p=figure(width=600,height=350)
x=np.random.rand(50);y=np.random.rand(50)
p.circle(x,y,color=rp.list_ember[2],size=8)
show(p)

案例6：多子图组合（2行2列科研复合图）

import numpy as np
import rho_plus as rp
rp.mpl_setup(font_scale=1.1)
fig,axes=rp.figure(nrows=2,ncols=2,figsize=(10,8))
#子图1折线
axes[0,0].plot(np.random.rand(30),color=rp.list_coast[1])
#子图2柱状
axes[0,1].bar(range(5),np.random.rand(5),color=rp.list_glacier[:5])
#子图3散点
axes[1,0].scatter(np.random.rand(20),np.random.rand(20),c=rp.list_twilight[3])
#子图4填充
axes[1,1].fill_between(range(10),np.random.rand(10),alpha=0.6,color=rp.list_inferna[2])
plt.tight_layout()
plt.show()

案例7：等高线填色图（地理/仿真数据可视化）

import numpy as np
import rho_plus as rp
rp.mpl_setup(is_dark=True)
x,y=np.meshgrid(np.linspace(-3,3,100),np.linspace(-3,3,100))
z=np.exp(-(x**2+y**2))*np.cos(x*y)
fig,ax=rp.figure()
cs=ax.contourf(x,y,z,cmap=rp.mpl_sundown_r,levels=20)
fig.colorbar(cs,ax=ax)
plt.show()

案例8：Altair静态统计图表（报表出图）

import altair as alt
import pandas as pd
import rho_plus as rp
rp.setup_all_engines()
df=pd.DataFrame({"cat":["X","Y","Z"]*25,"val":np.random.normal(10,3,75)})
chart=alt.Chart(df).mark_bar().encode(
    x="cat",y="val",color=alt.Color("cat",scale=alt.Scale(range=rp.list_frost[:3]))
)
chart.show()

五、常见报错与解决方案

报错1：ModuleNotFoundError: No module named 'rho_plus'

原因：安装包名错误（混用rho-plus/rho_plus）、多环境共存。
解决：pip uninstall rho-plus rho_plus;pip install rho_plus -U

报错2：ValueError: colormap rho_xxx not found

原因：色板名字拼写错误、未执行rp.mpl_setup()注册色板。
解决：绘图前先执行rp.mpl_setup()，核对色板名（无空格、前缀rho_）。

报错3：Python版本报错requires Python >=3.8,<=3.12

原因：3.7及以下/3.13+超高版本不兼容0.6.0。
解决：降级Python到3.9~3.11，或安装旧版pip install rho-plus==0.5.1。

报错4：Seaborn调色报错palette length mismatch

原因：rp.list_xxx颜色列表长度不足分类数。
解决：rp.list_inferna*3复制扩充颜色列表。

报错5：Plotly主题不生效

原因：仅执行mpl_setup，未调用rp.setup_all_engines()。
解决：需要跨引擎统一时必须执行全引擎配置函数。

六、使用注意事项

1. 主题生效顺序：rp.mpl_setup()必须在所有绘图代码之前运行，后置配置不会修改已生成画布；
2. 明暗切换规则：Jupyter notebook暗色cell环境建议默认is_dark=True，导出论文PDF使用浅色False；
3. 色板反向：所有色板加_r实现色阶反转（rp.mpl_inferna_r），适合从深到浅热力图；
4. 批量出图：循环绘图场景仅需在循环外执行1次rp.mpl_setup，重复调用会造成样式重置；
5. 导出图片：rho+主题下推荐保存dpi=300，深色图导出开启facecolor=None透明背景；
6. 版本兼容：0.4.x旧版无setup_all_engines接口，跨Plotly/Bokeh优先升级0.6.0；
7. 科研论文规范：font_scale=1.2适配期刊字号，定量热力优先veridian/inferna色板。

五、拓展使用技巧

1. 自定义色板拼接：custom_color = rp.list_inferna + rp.list_frost组合两套色板；
2. 局部单图覆盖主题：单张图表不想用全局rho主题，在ax绘图前手动设置ax.set_style("default")。

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。