Day 32 官方文档的阅读

原创已于 2025-11-03 16:42:51 修改 · 629 阅读

30 ·

CC 4.0 BY-SA版权

文章标签：

#python #机器学习

于 2025-11-03 14:13:59 首次发布

Python打卡训练营专栏收录该内容

52 篇文章

订阅专栏

@浙大疏锦行

今日任务：

官方文档的检索方式：github和官网
官方文档的阅读和使用：要求安装的包和文档为同一个版本
类的关注点：实例化所需要的参数；普通方法所需要的参数；普通方法的返回值
绘图的理解：对底层库的调用

在day 30 中提到，阅读库的文档说明是了解和学习该库的一个好方法。对于大多数的python库都有官方文档，获取的方式有以下几种：（1）GitHub仓库（2）PyPI（3）搜索引擎搜索库名

以pdpbox为例，在PyPI网站上搜索‘PDPbox’后，就会找到官方文档的链接：

点击链接，进入文档。一般来说，文档说明会提供以下信息：

库的基本信息与核心功能，安装方法与环境配置要求
模块划分，核心类/函数清单以及功能（概览）
详细说明每个函数的参数、返回值、注意事项等等，示例代码参考（具体查询）
使用教程与场景化案例

简单地说，库的官方文档是用来知道这个库有哪些方法，而Python文件中的悬停功能是用来查看这个如何用的。（what + how）

接下来使用sklearn中提供的鸢尾花数据集（iris），以PDPbox库中的一个类进行绘图解释，实践一下阅读文档操作的过程。

数据加载与训练

首先导入相关的库及方法

import pandas as pd
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.ensemble import RandomForestClassifier

要注意，使用load_iris得到的数据（类似字典的Bunch对象）需要简单处理才能达到之前直接读取数据的效果。由于直接导入的数据iris.data为一个数组形式并且没有特征名，因此为了便于后续的处理，将其转换为带列名的dataframe形式，并在此基础上加入‘target’列。

iris = load_iris()
print(iris.keys())
# dict_keys(['data', 'target', 'frame', 'target_names', 'DESCR', 'feature_names', 'filename', 'data_module'])

# 加载数据
iris = load_iris()
df = pd.DataFrame(iris.data,columns=iris.feature_names) # 将数组转换为带列名的dataframe
df['target'] = iris.target # 添加标签
# 确定特征和标签
features = iris.feature_names
target = 'target'

#训练
X_train,X_test,y_train,y_test = train_test_split(df[features],df[target],train_size=0.8,random_state=42)
rf_model = RandomForestClassifier(random_state=42)
rf_model.fit(X_train,y_train)

找到使用的类

在查看文档时，还需要注意库的版本问题。因为库会更新，内容会变化。查看自己库的版本可以使用“库名.__version__”，如pdpbox.__version__。

在API Reference中可以看到pdpbox中的一些方法，使用第一个来绘图

进入这个类后，可以看到它实例化需要的参数

当然这些参数，使用鼠标悬停在TargetPlot上也可以看到。按照参数说明，导入这个类后并实例化：

from pdpbox.info_plots import TargetPlot # 导入类
# 实例化
target_plot = TargetPlot(
    df=df,
    feature='sepal length (cm)', # 要分析的特征列名称
    feature_name='花萼长度(cm)', # 默认为feature的值，图表中显示的名称
    target=target, # 目标变量
    grid_type='percentile',  # 按特征的分位数生成网格
    num_grid_points=10, # 特征取值的网格点数量（控制图表的平滑度）
)

在后面还可以看到，这个类的属性和方法的说明：

调用方法

可以看到TargetPlot类有一个plot方法，以及参数说明：

先使用默认参数，调用这个方法，并查看结果：

target_plot.plot()

可以看到返回的是一个元组：

结合官方文档中的返回值说明，分别查看：

（1）target_plot.plot()[0]，返回了plotly的figure图像，后续可以继续修改

（2）print(target_plot.plot()[1])，返回“None”。这里对'None'作解释，取决于engine的值：

engine='matplotlib'：matplotlib 绘制图表时，会生成 “坐标轴对象（matplotlib.axes.Axes）”，这些对象是图表的 “可操作单元”（比如可以通过它们修改标题、坐标轴标签、颜色等）。因此 target_plot.plot() 会返回一个字典（dict），键是坐标轴名称，值是对应的 Axes 对象，可以对图表进行后续自定义调整。
engine='plotly'：plotly 是交互式绘图库，它的图表渲染逻辑与 matplotlib 不同 ——plotly 图表通常通过自身的机制直接显示（比如在 Jupyter 中自动渲染，或生成 HTML 文件），不需要返回类似 matplotlib 的 Axes 对象来操作。因此，当使用 plotly 引擎时，plot() 函数不需要返回任何可操作的坐标轴对象，直接返回 None。

（3）target_plot.plot()[2]，返回了目标变量（或预测值）在不同特征区间的统计摘要，而target_plot.plot()[0]就是根据此的可视化。

对fig进行修改后的版本，fig.update_layout() 是对 Plotly 图表进行二次修改的核心方法：

fig,axes,summary_df = target_plot.plot(
    which_classes=None, # 默认用所有类别
    show_percentile=True, # 展示百分位线，默认为False
    engine='plotly',
    template='simple_white' # 模板
) # 返回元组

# 调整fig，手动设置图表尺寸（单位：像素）
fig.update_layout(
    width=800,  # 宽度800像素
    height=500,  # 高度500像素
    title=dict(text=f'Target Plot: 花萼长度(cm)', x=0.5)  # 居中标题
)

fig.show()

作业

根据对TargetPlot的实例化可以发现，在阅读文档时要注意以下信息：

传入的参数和对应的格式
类对应的方法的返回值

作业：参考pdpbox官方文档中的其他类，绘制相应的图，任选即可

选择InteractPredictPlot类，是用于可视化两个特征之间的交互效应的高级工具。

# InteractPredictPlot类
from pdpbox.info_plots import InteractPredictPlot
#实例化
interact_predict_plot = InteractPredictPlot(
    df=df,
    features=features[:2], #选择花萼长度和花萼宽度
    feature_names=features[:2],
    model=rf_model,
    model_features=features # 数据集中特征列的名称列表
)

# 返回值类型与TargetPlot相同
fig,axes,summary_df = interact_predict_plot.plot(
    which_classes=None,
    show_percentile=False,
    engine='plotly',
    template='plotly_white',
)
#调整fig
fig.update_layout(
    width=1200,
    height=800,
    title=dict(text=f'InteractPredictPlot: {features[0]} and {features[1]}',x=0.5) # 居中标题
)

fig.show()

分别展示花萼长度和花萼宽度在三个类别（0，1，2）下的交互：