选项与自定义

Pandas - 选项和自定义

Pandas 提供了一个灵活的系统来自定义其行为，特别是数据的显示方式（例如，显示的行数/列数，小数精度）。这对于在不同环境（如脚本、Jupyter notebook 或终端）中调整输出非常有用。

选项系统 API 包括几个关键函数：

• pd.get_option(param): 检索特定选项的当前值。
• pd.set_option(param, value): 全局设置特定选项的新值。
• pd.reset_option(param): 将特定选项重置为其默认值。
• pd.describe_option(param): 打印选项的详细描述，包括其默认值和当前值。
• pd.option_context(param, value, ...): 一个上下文管理器（context manager），用于在 with 块内临时设置一个或多个选项。

让我们探讨这些函数如何与常见的显示选项一起使用。

获取选项值 (get_option)

get_option 接受选项名称（作为字符串）并返回其当前设置。

示例：display.max_rows

此选项控制 Pandas 在打印 DataFrame 时显示的最大行数。如果 DataFrame 超过此限制，通常会被截断。

import pandas as pd

# 获取默认的最大显示行数
default_max_rows = pd.get_option("display.max_rows")
print(f"display.max_rows 的默认值：{default_max_rows}")

输出（默认值可能因 Pandas 版本/环境略有不同）：

Default value for display.max_rows: 60

示例：display.max_columns

此选项控制 Pandas 显示的最大列数。超出此限制后，列可能会被截断（由 ... 表示）。将其设置为 None 通常会显示所有列。

import pandas as pd

# 获取默认的最大显示列数
default_max_cols = pd.get_option("display.max_columns")
print(f"display.max_columns 的默认值：{default_max_cols}")

输出（默认值可能不同）：

Default value for display.max_columns: 20

设置选项值 (set_option)

set_option 接受选项名称和期望的新值。此更改会影响当前会话中后续的 Pandas 操作全局生效。

示例：增加 display.max_rows

import pandas as pd

print(f"原始 max_rows：{pd.get_option('display.max_rows')}")

# 设置 max_rows 以显示最多 100 行
pd.set_option("display.max_rows", 100)

print(f"新的 max_rows：{pd.get_option('display.max_rows')}")

输出：

原始 max_rows: 60
新的 max_rows: 100

示例：显示所有列 (display.max_columns)

import pandas as pd

print(f"原始 max_columns：{pd.get_option('display.max_columns')}")

# 将 max_columns 设置为 None 以显示所有列
pd.set_option("display.max_columns", None)

print(f"新的 max_columns：{pd.get_option('display.max_columns')}")

输出：

Original max_columns: 20
新的 max_columns: None

重置选项值 (reset_option)

reset_option 将指定的选项恢复到其原始默认值。

示例：重置 display.max_rows

import pandas as pd

# 假设我们之前修改了 max_rows
pd.set_option("display.max_rows", 999);
print(f"当前 max_rows：{pd.get_option('display.max_rows')}")

# 将 max_rows 重置为其默认值
pd.reset_option("display.max_rows")

print(f"重置后的 max_rows：{pd.get_option('display.max_rows')}")

输出（假设默认值为 60）：

Current max_rows: 999
重置后的 max_rows: 60

描述选项 (describe_option)

describe_option 提供了关于选项的有用文档，包括其目的、类型、默认值和当前设置。这不会更改选项。

示例：描述 display.precision

display.precision 选项控制浮点数显示的小数位数。

import pandas as pd

pd.describe_option("display.precision")

输出（确切文本可能因 Pandas 版本略有变化）：

display.precision : int
    浮点数输出精度，指小数点后的位数，用于常规格式和科学计数法。
    类似于 ``numpy.set_printoptions`` 的 precision 参数。
    [默认值: 6] [当前值: 6]

使用 option_context 进行临时设置

option_context 上下文管理器（context manager）非常有用，它允许你仅在 with 块内应用特定设置。一旦退出该块，选项将自动恢复到之前的值。

示例：临时更改 display.max_rows 和 display.precision

import pandas as pd
import numpy as np

# 创建一个示例 DataFrame
df = pd.DataFrame(np.random.rand(15, 5) * 100)

print(f"外部上下文：max_rows = {pd.get_option('display.max_rows')}，precision = {pd.get_option('display.precision')}")
print("带有默认设置的 DataFrame（可能已截断）：\n", df.head()) # 显示头部以避免输出过大

print("\n正在进入 option_context...")
with pd.option_context("display.max_rows", 10, "display.precision", 2):
    print(f"内部上下文：max_rows = {pd.get_option('display.max_rows')}，precision = {pd.get_option('display.precision')}")
    print("内部上下文中的 DataFrame（行数=10，精度=2）：\n", df)

print("\n已退出 option_context。")
print(f"再次回到外部上下文：max_rows = {pd.get_option('display.max_rows')}，precision = {pd.get_option('display.precision')}")
print("已恢复原始设置的 DataFrame：\n", df.head()) # 再次显示头部

输出（随机值和默认设置可能不同）：

外部上下文：max_rows = 60, precision = 6
带有默认设置的 DataFrame（可能已截断）：
           0          1          2          3          4
0  50.123456  10.987654  80.456789  30.123456  70.987654
1  20.654321  90.876543  40.345678  60.789012  10.456789
2  70.234567   5.567890  95.876543  25.123456  85.678901
3  40.789012  65.432109  15.987654  55.345678   5.876543
4  90.345678  20.876543  75.234567  80.789012  35.123456

正在进入 option_context...
内部上下文：max_rows = 10, precision = 2
内部上下文中的 DataFrame（行数=10，精度=2）：
        0      1      2      3      4
0   50.12  10.99  80.46  30.12  70.99
1   20.65  90.88  40.35  60.79  10.46
2   70.23   5.57  95.88  25.12  85.68
3   40.79  65.43  15.99  55.35   5.88
4   90.35  20.88  75.23  80.79  35.12
..    ...    ...    ...    ...    ...
10  11.22  33.44  55.66  77.88  99.00
11  98.76  87.65  76.54  65.43  54.32
12  12.34  23.45  34.56  45.67  56.78
13  67.89  78.90  89.01  90.12  11.23
14  22.34  33.45  44.56  55.67  66.78

[15 rows x 5 columns]

已退出 option_context。
再次回到外部上下文：max_rows = 60, precision = 6
已恢复原始设置的 DataFrame：
           0          1          2          3          4
0  50.123456  10.987654  80.456789  30.123456  70.987654
1  20.654321  90.876543  40.345678  60.789012  10.456789
2  70.234567   5.567890  95.876543  25.123456  85.678901
3  40.789012  65.432109  15.987654  55.345678   5.876543
4  90.345678  20.876543  75.234567  80.789012  35.123456

注意 with 块内的 DataFrame 显示方式发生了变化（截断为 10 行，2 位小数），并在退出块后恢复了原样。

常用参数

选项名称	描述
display.max_rows	显示的最大行数。None 表示无限制。
display.max_columns	显示的最大列数。None 表示无限制。
display.expand_frame_repr	打印 DataFrame 时是否扩展（‘expand’）以显示完整宽度，还是截断列以适应终端宽度（‘truncate’）。
display.max_colwidth	列中元素的最大宽度（以字符为单位）。较长的字符串将被截断。None 表示无限制。
display.precision	浮点数的小数位数。
mode.chained_assignment	控制链式赋值（chained assignment）的行为（'warn'、'raise'、None）。参阅 SettingWithCopyWarning。

请参阅 Pandas 官方文档以获取所有可用选项的完整列表。在此查找：Pandas 选项和设置