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