更新（2023年11月）- 版本2.3.0：添加详细程度参数，修复长期存在的问题

---

只需两行代码即可进行深入的探索性数据分析（EDA）（目标分析、比较、特征分析、相关性）！

Sweetviz是一个开源Python库，只需两行代码即可生成美观、高密度的可视化，快速启动探索性数据分析（EDA）。输出是一个完全独立的HTML应用程序。

该系统主要围绕快速可视化目标值和比较数据集而构建。其目标是帮助快速分析目标特征、训练与测试数据以及其他此类数据特征分析任务。

使用方法和参数描述如下，您还可以在这里找到一篇深入描述其特性的文章，并看到实际示例。

**Sweetviz的开发仍在进行中！**如果您遇到任何数据、兼容性或安装问题，请告诉我！感谢您在这里的问题跟踪系统中报告任何错误，我欢迎您对使用/功能的反馈和问题在这里全新的GitHub"讨论"标签中提出。

示例与提及

使用泰坦尼克号数据集的示例HTML报告

Colab上带文档的示例笔记本（Jupyter/其他笔记本应该也可以使用）

Medium文章深入描述其特性

KD Nugget文章：

特性

• 目标分析
  • 展示目标值（如泰坦尼克号数据集中的"生存"）与其他特征的关系
• 可视化和比较
  • 不同数据集（如训练数据与测试数据）
  • 集内特征（如男性与女性）
• 混合类型关联
  • Sweetviz无缝集成了数值型（皮尔逊相关系数）、分类型（不确定性系数）和分类-数值型（相关比）数据类型的关联，为所有数据类型提供最大信息。
• 类型推断
  • 自动检测数值、分类和文本特征，可选手动覆盖
• 摘要信息
  • 类型、唯一值、缺失值、重复行、最频繁值
  • 数值分析：
    • 最小/最大/范围、四分位数、均值、众数、标准差、总和、中位数绝对偏差、变异系数、峰度、偏度

新增与重要更新

• 2.2版本：针对Python 3.7+和numpy版本的大型兼容性更新
• 2.1版本：支持Comet.ml
• 2.0版本：支持Jupyter、Colab和其他笔记本，报告缩放和垂直布局

（有关这些功能的文档，请参见下文）

升级

一些人在通过pip升级时遇到了混合结果的情况。要从现有安装更新到最新版本，建议先pip uninstall sweetviz，然后再简单安装。

安装

Sweetviz 目前支持 Python 3.6+ 和 Pandas 0.25.3+。报告使用基本的 "os" 模块输出，因此尚不支持需要自定义文件操作的特殊环境（如 Google Colab），不过我正在寻找解决方案。

使用 pip

安装 sweetviz 的最佳方式（除了从源代码安装外）是使用 pip：

pip install sweetviz

安装问题及解决方法

在少数情况下，用户报告了诸如 ModuleNotFoundError: No module named 'sweetviz' 和 AttributeError: module 'sweetviz' has no attribute 'analyze' 等错误。 对于这些情况，我们建议采取以下措施：

• 确保您的脚本中没有名为 sweetviz.py 的文件，因为这会干扰库本身。删除或重命名该脚本（以及任何相关的 .pyc 文件），然后重试。
• 尝试使用 pip uninstall sweetviz 卸载库，然后重新安装。
• 问题可能源于使用多个 Python 版本，或操作系统权限。以下 Stack Overflow 文章解决了许多报告的此类问题：文章 1，文章 2，文章 3
• 如果以上方法都无效，请在 GitHub 上提交 bug 报告。感谢您花时间反馈，这可能有助于解决您和其他人的问题！

基本用法

创建报告是一个简单的两步过程：

1. 使用 analyze()、compare() 或 compare_intra() 之一创建 DataframeReport 对象
2. 使用 show_xxx() 函数渲染报告。现在您可以选择使用 html 或 notebook 报告选项，还可以进行缩放：（有关这些选项的更多信息，请参见下文）

步骤 1：创建报告

创建报告有 3 个主要函数：

• analyze(...)
• compare(...)
• compare_intra(...)

分析单个数据框（及其可选目标特征）

要分析单个数据框，只需使用 analyze(...) 函数，然后使用 show_html(...) 函数：

import sweetviz as sv

my_report = sv.analyze(my_dataframe)
my_report.show_html() # 默认参数将生成 "SWEETVIZ_REPORT.html"

运行时，这将在您的默认浏览器中输出一个 1080p 宽屏 html 应用程序：

可选参数

analyze() 函数可以接受多个其他参数：

analyze(source: Union[pd.DataFrame, Tuple[pd.DataFrame, str]],
            target_feat: str = None,
            feat_cfg: FeatureConfig = None,
            pairwise_analysis: str = 'auto',
            verbosity: str = 'default'):

• source: 数据框（如示例所示）或包含数据框和要在报告中显示的名称的元组。 例如：my_df 或 [my_df, "Training"]
• target_feat: 表示要标记为"目标"的特征名称的字符串。目前只有布尔型和数值型特征可以作为目标。
• feat_cfg: 一个 FeatureConfig 对象，表示要跳过的特征，或在分析中强制指定某种类型的特征。参数可以是单个字符串或字符串列表。参数包括 skip、force_cat、force_num 和 force_text。"force_" 参数会覆盖内置的类型检测。可以如下构造：

feature_config = sv.FeatureConfig(skip="PassengerId", force_text=["Age"])

• verbosity: [新增] 可以设置为 full、progress_only（仅显示进度条而不显示报告生成消息）和 off（完全静默，除错误或警告外）。默认详细程度也可以在 INI 覆盖中的 "General" 标题下设置（详见下文 "配置文件" 部分）。
• pairwise_analysis: 相关性和其他关联可能需要二次时间（n^2）来完成。默认设置（"auto"）将在不发出警告的情况下运行，直到数据集包含 "association_auto_threshold" 个特征。超过该阈值后，您需要明确传递参数 pairwise_analysis="on"（或 ="off"），因为处理如此多的特征需要很长时间。该参数还包括生成关联图（基于 Drazen Zaric 的概念）：

比较两个数据框（例如测试集与训练集）

要比较两个数据集，只需使用 compare() 函数。它的参数与 analyze() 相同，只是插入了第二个参数来覆盖比较数据框。建议使用 [dataframe, "name"] 格式的参数，以便更好地区分基础数据框和比较数据框。（例如 [my_df, "Train"] 与 my_df）

my_report = sv.compare([my_dataframe, "Training Data"], [test_df, "Test Data"], "Survived", feature_config)

比较同一数据框的两个子集（例如男性与女性）

获得深入洞察的另一种方法是使用比较功能将数据集分成两个子群体。 通过compare_intra()函数内置了对此的支持。该函数将布尔序列作为参数之一，并使用显式的"name"元组来命名生成的(true, false)数据集。请注意，在内部，这会创建2个单独的数据框来表示每个结果组。因此，它更像是手动执行此类处理的简便函数。

my_report = sv.compare_intra(my_dataframe, my_dataframe["Sex"] == "male", ["Male", "Female"], "Survived", feature_config)

第2步：显示报告

创建报告对象后（例如上面示例中的my_report），只需将其传递给两个show函数之一：

show_html()

show_html(  filepath='SWEETVIZ_REPORT.html', 
            open_browser=True, 
            layout='widescreen', 
            scale=None)

show_html(...) 将在给定的文件路径创建并保存HTML报告。有以下选项：

• layout：可选'widescreen'或'vertical'。宽屏布局在鼠标悬停在每个特征上时在屏幕右侧显示详细信息。新的（2.0版本）垂直布局在水平方向上更紧凑，并允许点击展开每个详细区域。
• scale：使用浮点数（例如scale = 0.8或None）来缩放整个报告。这对于使报告适应任何输出非常有用。
• open_browser：启用自动打开Web浏览器以显示报告。由于在某些情况下这是不需要的（或可能导致某些IDE出现问题），您可以在此禁用它。

show_notebook()

show_notebook(  w=None, 
                h=None, 
                scale=None,
                layout='widescreen',
                filepath=None,
                file_layout=None,
                file_scale=None)

show_notebook(...) 是2.0版本的新功能，它将在笔记本（例如Jupyter、Google Colab等）中嵌入一个显示报告的IFRAME元素。

请注意，由于笔记本通常是一个更受限制的视觉环境，因此最好使用自定义的宽度/高度/缩放值（w、h、scale），甚至在INI覆盖中设置自定义默认值（见下文）。选项包括：

• w（宽度）：设置报告输出_窗口_的宽度（完整报告可能不适合；使用layout和/或scale调整报告本身）。可以是百分比字符串（w="100%"）或像素数（w=900）。
• h（高度）：设置报告输出_窗口_的高度。可以是像素数（h=700）或"Full"以使窗口高度与所有特征一样高（h="Full"）。
• scale：与上面的show_html()相同。
• layout：与上面的show_html()相同。
• filepath：可选的输出HTML报告。
• file_layout：仅用于可选文件输出的布局（与上面show_html()的layout相同）
• file_scale：仅用于可选文件输出的缩放（与上面show_html()的scale相同）

自定义默认值：配置文件

该包包含一个用于配置的INI文件。您可以通过提供自己的文件并在创建报告之前调用以下命令来覆盖任何设置：

sv.config_parser.read("Override.ini")

重要提示#1： 最好在任何其他命令之前加载覆盖，因为许多INI选项在报告生成中使用。

重要提示#2： 在覆盖INI文件中的一组值之前，始终添加标题行（例如[General]），否则您的设置将被忽略。请参见下面的示例。如果设置多个值，只需包含一次[General]行。

最有用的配置覆盖

您可以查看sweetviz_defaults.ini文件以了解可以覆盖的内容（警告：其中很多内容仍在进行中，文档不完善），但最有用的覆盖如下。

默认报告布局、大小

覆盖以下任何一项（通过将它们放在您自己的INI中，再次不要忘记标题），以避免每次执行"show"命令时都必须设置它们：

重要提示：指定百分比时注意使用双'%'

[Output_Defaults]
html_layout = widescreen
html_scale = 1.0
notebook_layout = vertical
notebook_scale = 0.9
notebook_width = 100%%
notebook_height = 700

中文、日语、韩语（CJK）字符支持

[General]
use_cjk_font = 1 

*如果为[General]设置多个值，只包含一次[General]行。

这将切换图表中的字体以使用兼容CJK的字体。虽然这种字体不太紧凑，但它将消除这些语言的任何警告和"未知字符"符号。

移除Sweetviz标志

[Layout]
show_logo = 0

这将从页面顶部移除Sweetviz标志。

设置默认详细程度

[General]
default_verbosity = off 

*如果为[General]设置多个值，只包含一次[General]行。

可以设置为full、progress_only（仅显示进度条但不显示报告生成消息）和off（完全安静，除非出现错误或警告）。

相关性/关联分析

Sweetviz 关联图和分析的一个主要洞察来源和独特特性是它在一个单一图表中统一了:

• 数值相关性(数值特征之间)
• 不确定性系数(分类-分类之间)
• 相关比(分类-数值之间)

方块代表与分类特征相关的变量,圆圈代表数值-数值相关性。注意为了清晰起见,对角线上的平凡关系被留空。

重要提示:分类-分类关联(由显示不确定性系数的方块提供)是不对称的,这意味着每一行代表左侧行标题对每一列提供了多少信息。例如,"性别"、"客舱等级"和"票价"是对"生存"提供最多信息的元素。

对于泰坦尼克号数据集,这些信息相当对称,但并非总是如此!

相关性也会在每个特征的详细部分显示,适用时目标值会被突出显示。例如:

最后,值得注意的是,这些相关性/关联方法不应被视为绝对真理,因为它们对数据分布和关系的基本假设做出了一些假设。但它们可以作为一个非常有用的起点。

Comet.ml 集成

从2.1版本开始,Sweetviz 现在完全集成了 Comet.ml。这意味着只要您的 API 密钥在环境中正确设置,Sweetviz 将自动记录使用 show_html() 和 show_notebook() 生成的任何报告到您的工作空间。

此外,您还可以使用新函数 report.log_comet(experiment_object) 显式地将报告上传到给定实验的工作空间。

您可以查看一个 Colab 笔记本 示例来生成报告,以及其对应的 Comet.ml 工作空间 中的报告。

Comet 报告参数

您可以通过覆盖配置文件的 [comet_ml_defaults] 部分来自定义 Sweetviz 报告在 Comet 工作空间中的外观。有关使用 INI 覆盖的更多信息,请参见上文。

您可以选择使用 widescreen(水平)或 vertical(垂直)布局,并设置您喜欢的缩放比例,只需在覆盖 INI 文件中添加以下内容:

[comet_ml_defaults]
html_layout = vertical
html_scale = 0.85

故障排除 / 常见问题

• 安装问题

请参阅本文档顶部的"安装问题和修复"部分

• 亚洲字符,"RuntimeWarning: Glyph ### missing from current font"

请参阅上文关于 CJK 字符支持的部分。如果您发现需要额外的字符类型,请务必在问题跟踪系统中提出请求。

• ...任何其他问题

开发工作正在进行中,因此欢迎您在此问题跟踪系统中或在我们的论坛中(您应该可以使用 Github 账户登录!)报告任何问题和/或建议

贡献

这是我的第一个开源项目!我构建它是为了使它成为最有用的工具,并帮助尽可能多的人进行数据科学工作。如果它对您有用,您的贡献非常受欢迎,可以采取多种形式:

1. 传播消息!

在 GitHub 上点个星,发个 Twitter 或 Instagram 帖子是最简单的贡献,可能会极大地帮助这个项目成长!如果您觉得这个项目有用,您的这些快速行动对我来说意义重大,可能会产生深远的影响。

Kaggle 笔记本/帖子、Medium 文章、YouTube 视频教程和其他内容需要更多时间,但会更有帮助!

2. 报告错误和问题

我预计随着越来越多的人使用各种新的(且"不干净的")数据,会出现许多怪异情况。如果您发现了错误,请在此处开启一个新问题。

3. 建议和讨论用法/功能

为了使 Sweetviz 尽可能有用,我们需要听到您希望它做什么,或者它可以做得更好

4. 为开发做出贡献

我绝对欢迎在这个项目上得到任何帮助,只需在问题追踪器和/或我们的 Discourse 论坛上联系即可。

请注意,在一段繁忙的开发期后,代码本身现在需要一些清理。:)

特别感谢 & 相关材料

贡献者

非常感谢所有通过报告、反馈和提交在 Github 上做出贡献的人! 我要特别感谢 Frank Male,他在修复问题和为 2.2.0 设置新的构建流程方面提供了巨大帮助。

使用 contrib.rocks 制作。

相关材料

我希望 Sweetviz 成为最优秀资源的枢纽,一种获取最有价值信息和可视化的方式,而无需重新发明轮子。 因此，我想指出一些对Sweetviz有启发并被整合进来的优秀资源：

• Pandas-Profiling是本项目最初的灵感来源。它的一些类型检测代码被包含在Sweetviz中。

• Shaked Zychlinski：寻找分类相关性是一篇关于不同类型变量交互的优秀文章，是Sweetviz中相关分析的基础。

• Drazen Zaric：Python中更好的热力图和相关矩阵图是我们关联图的基础。