Python Pandas.unique 函数解析与实战教程

摘要

本文章旨在全面地解析 pandas 库中的 unique 函数。pandas.unique 是一个用于从一维数组型（array-like）对象中提取唯一值的高效工具。我们将从其核心功能、函数签名、参数详解、返回值类型，到关键行为特性（如顺序保留、缺失值处理）进行详细阐述。此外，还将包含丰富的实战代码示例，涵盖不同数据类型的应用场景，并对 pandas.unique 与 Series.unique、numpy.unique 及原生 set() 在性能上进行对比分析。最后，本文章将探讨一些常见的错误处理和使用注意事项，以帮助读者在数据分析实践中更准确、高效地使用此函数。

---

1. 核心功能与函数签名

pandas.unique 是 Pandas 库提供的一个顶层函数（top-level function），其主要目标是从一个一维数据结构中，按照值首次出现的顺序，提取出所有不重复的元素。

1.1 函数签名

pandas.unique 的函数签名非常简洁 。

pandas.unique(values)

1.2 参数详解 (values)

该函数仅接受一个参数：

• values:
  • 类型: 1d array-like (一维数组型对象) 。
  • 说明: 这是你希望从中提取唯一值的数据源。它可以是多种形式，包括但不限于：
    • pandas.Series
    • pandas.Index
    • numpy.ndarray
    • Python list
    • Python tuple

1.3 返回值详解

pandas.unique 的返回值类型并不是固定的，而是取决于输入 values 的数据类型，这一点对于后续操作至关重要 。

• numpy.ndarray: 这是最常见的返回类型。当输入是 pandas.Series、numpy.ndarray 或包含数值、字符串等基本类型的列表时，函数会返回一个 NumPy 数组 。
• pandas.Index: 如果输入本身就是一个 pandas.Index 对象，则返回的唯一值集合也将被封装在一个新的 Index 对象中 。
• pandas.Categorical: 如果输入的数据类型是 Categorical（分类型），则返回值也是一个 Categorical 对象，它包含了数据中实际出现的类别 。
• ExtensionArray: 对于 Pandas 中其他扩展数组类型（如带时区的时间序列数据），函数会返回相应类型的 ExtensionArray 。

---

2. 关键行为特性

理解 pandas.unique 的核心行为是正确使用它的基础。

2.1 顺序保留

这是 pandas.unique 最重要的特性之一。它返回的唯一值是按照它们在原始数据 values 中首次出现的顺序排列的。函数不会对结果进行排序 。这与 numpy.unique（默认排序）和 Python 的 set（无序）有显著区别。

import pandas as pddata = pd.Series(['apple', 'banana', 'apple', 'cherry', 'banana'])
# 顺序将是 'apple', 'banana', 'cherry'
print(pd.unique(data))
# 输出: ['apple' 'banana' 'cherry']

2.2 缺失值处理

pandas.unique 将缺失值（NA）视为一个有效的、唯一的元素，并会将其包含在返回结果中 。这包括：

• numpy.nan (用于浮点数)
• None (用于对象类型)
• pd.NA (通用缺失值标记)
• pd.NaT (用于日期时间类型)

import numpy as npdata_with_na = [2, 1, np.nan, 3, 1, np.nan, 2]
# np.nan 会被当做一个唯一值包含在内
print(pd.unique(data_with_na))
# 输出: [ 2.  1. nan  3.]

如果你希望得到不包含缺失值的结果，需要在调用 unique 之前手动过滤掉它们 。

series = pd.Series([2, 1, np.nan, 3