pandas 陣列、純量和資料類型#

物件#

對於大多數資料類型,pandas 使用 NumPy 陣列作為具體物件,其中包含 IndexSeriesDataFrame

對於某些資料類型,pandas 會延伸 NumPy 的類型系統。這些類型的字串別名可以在 dtypes 中找到。

資料類型

pandas 資料類型

純量

陣列

有時區感知的日期時間

DatetimeTZDtype

時間戳記

日期時間

時間增量

(無)

Timedelta

時間增量

期間 (時間跨度)

PeriodDtype

期間

期間

區間

IntervalDtype

區間

區間

可為 Null 的整數

Int64Dtype, …

(無)

可為 Null 的整數

可為 Null 的浮點數

Float64Dtype, …

(無)

可為 Null 的浮點數

類別

CategoricalDtype

(無)

類別

稀疏

SparseDtype

(無)

稀疏

字串

StringDtype

str

字串

可為 Null 的布林值

BooleanDtype

bool

可為 Null 的布林值

PyArrow

ArrowDtype

Python 純量或 NA

PyArrow

pandas 和第三方函式庫可以延伸 NumPy 的類型系統 (請參閱 延伸類型)。頂層 array() 方法可用於建立新的陣列,該陣列可以儲存在 SeriesIndex 中,或作為 DataFrame 中的欄位。

陣列(資料[, 資料類型, 複製])

建立陣列。

PyArrow#

警告

此功能為實驗性質,且 API 可能在未來版本中不經警告而變更。

arrays.ArrowExtensionArraypyarrow.ChunkedArray 搭配 pyarrow.DataType 支援,而非 NumPy 陣列和資料類型。arrays.ArrowExtensionArray.dtypeArrowDtype

Pyarrow 提供與 NumPy 類似的陣列和 資料類型 支援,包括對所有資料類型的一流可空性支援、不可變性等。

下表顯示 pandas 識別的等效 pyarrow 支援 (pa)、pandas 延伸和 numpy (np) 類型。以下 pyarrow 支援的類型需要傳遞至 ArrowDtype 才能讓 pandas 識別,例如 pd.ArrowDtype(pa.bool_())

PyArrow 類型

pandas 延伸類型

NumPy 類型

pyarrow.bool_()

BooleanDtype

np.bool_

pyarrow.int8()

Int8Dtype

np.int8

pyarrow.int16()

Int16Dtype

np.int16

pyarrow.int32()

Int32Dtype

np.int32

pyarrow.int64()

Int64Dtype

np.int64

pyarrow.uint8()

UInt8Dtype

np.uint8

pyarrow.uint16()

UInt16Dtype

np.uint16

pyarrow.uint32()

UInt32Dtype

np.uint32

pyarrow.uint64()

UInt64Dtype

np.uint64

pyarrow.float32()

Float32Dtype

np.float32

pyarrow.float64()

Float64Dtype

np.float64

pyarrow.time32()

(無)

(無)

pyarrow.time64()

(無)

(無)

pyarrow.timestamp()

DatetimeTZDtype

np.datetime64

pyarrow.date32()

(無)

(無)

pyarrow.date64()

(無)

(無)

pyarrow.duration()

(無)

np.timedelta64

pyarrow.binary()

(無)

(無)

pyarrow.string()

StringDtype

np.str_

pyarrow.decimal128()

(無)

(無)

pyarrow.list_()

(無)

(無)

pyarrow.map_()

(無)

(無)

pyarrow.dictionary()

CategoricalDtype

(無)

註解

pd.StringDtype("pyarrow")pd.ArrowDtype(pa.string()) 提供 Pyarrow 支持的字串支援。 pd.StringDtype("pyarrow")字串區段 中描述如下,如果指定字串別名 "string[pyarrow]",將會回傳它。 pd.ArrowDtype(pa.string()) 通常與不同類型的 ArrowDtype 有更好的互通性。

雖然 arrays.ArrowExtensionArray 中的個別值儲存為 PyArrow 物件,但純量會回傳為對應於資料類型的 Python 純量,例如 PyArrow int64 會回傳為 Python int,或 NA 表示遺失值。

arrays.ArrowExtensionArray(values)

由 PyArrow ChunkedArray 支援的 Pandas ExtensionArray。

ArrowDtype(pyarrow_dtype)

PyArrow 資料類型的 ExtensionDtype。

如需更多資訊,請參閱 PyArrow 使用者指南

日期時間#

NumPy 無法原生表示具時區感知的日期時間。pandas 使用 arrays.DatetimeArray 擴充陣列來支援此功能,它可以儲存無時區或具時區感知的值。

Timestampdatetime.datetime 的子類別,是 pandas 的純量類型,用於無時區或具時區感知的日期時間資料。NaT 是日期時間資料的遺失值。

Timestamp([ts_input, year, month, day, ...])

python datetime.datetime 物件的 Pandas 替換。

屬性#

Timestamp.asm8

以奈秒為單位傳回 numpy datetime64 格式。

Timestamp.day

Timestamp.dayofweek

傳回星期幾。

Timestamp.day_of_week

傳回星期幾。

Timestamp.dayofyear

傳回一年中的第幾天。

Timestamp.day_of_year

傳回一年中的第幾天。

Timestamp.days_in_month

傳回一個月中的天數。

Timestamp.daysinmonth

傳回一個月中的天數。

Timestamp.fold

Timestamp.hour

Timestamp.is_leap_year

如果年份是閏年,傳回 True。

Timestamp.is_month_end

檢查日期是否為該月的最後一天。

Timestamp.is_month_start

檢查日期是否為該月的第一天。

Timestamp.is_quarter_end

檢查日期是否為該季度的最後一天。

Timestamp.is_quarter_start

檢查日期是否為季度的第一天。

Timestamp.is_year_end

如果日期是該年的最後一天,則傳回 True。

Timestamp.is_year_start

如果日期是該年的第一天,則傳回 True。

Timestamp.max

Timestamp.microsecond

Timestamp.min

Timestamp.minute

Timestamp.month

Timestamp.nanosecond

Timestamp.quarter

傳回該年的季度。

Timestamp.resolution

Timestamp.second

Timestamp.tz

tzinfo 的別名。

Timestamp.tzinfo

Timestamp.unit

與 self._creso 相關聯的縮寫。

Timestamp.value

Timestamp.week

傳回該年的週數。

Timestamp.weekofyear

傳回該年的週數。

Timestamp.year

方法#

Timestamp.as_unit(unit[, round_ok])

將底層 int64 表示轉換為指定的單位。

Timestamp.astimezone(tz)

將具時區感知的 Timestamp 轉換為另一個時區。

Timestamp.ceil(freq[, ambiguous, nonexistent])

傳回一個向上取整到此解析度的 Timestamp。

Timestamp.combine(date, time)

將日期、時間合併為具有相同日期和時間欄位的日期時間。

時間戳記.ctime()

傳回 ctime() 樣式的字串。

時間戳記.date()

傳回具有相同年、月和日的日期物件。

時間戳記.day_name([locale])

傳回具有指定 locale 的時間戳記星期名稱。

時間戳記.dst()

傳回夏令時間 (DST) 調整。

時間戳記.floor(freq[, ambiguous, nonexistent])

傳回一個向下取整到此解析度的時間戳記。

時間戳記.fromordinal(ordinal[, tz])

從一個前儒略曆序數建立一個時間戳記。

時間戳記.fromtimestamp(ts)

將時間戳記[, tz] 從 POSIX 時間戳記轉換為 tz 的當地時間。

時間戳記.isocalendar()

傳回一個包含 ISO 年、週數和星期幾的名稱元組。

時間戳記.isoformat([sep, timespec])

傳回根據 ISO 8601 格式化時間。

時間戳記.isoweekday()

傳回日期所表示的星期幾。

時間戳記.month_name([locale])

傳回具有指定 locale 的時間戳記月份名稱。

時間戳記.normalize()

將時間戳記標準化至午夜,保留 tz 資訊。

Timestamp.now([tz])

傳回新的 Timestamp 物件,代表當地時間為 tz。

Timestamp.replace([year, month, day, hour, ...])

實作 datetime.replace,處理奈秒。

Timestamp.round(freq[, ambiguous, nonexistent])

將 Timestamp 四捨五入到指定的解析度。

Timestamp.strftime(format)

傳回 Timestamp 的格式化字串。

Timestamp.strptime(string, format)

函式尚未實作。

Timestamp.time()

傳回時間物件,時間相同,但 tzinfo=None。

Timestamp.timestamp()

傳回浮點數的 POSIX 時間戳記。

Timestamp.timetuple()

傳回時間元組,與 time.localtime() 相容。

Timestamp.timetz()

傳回時間物件,時間和 tzinfo 相同。

Timestamp.to_datetime64()

傳回具有相同精度的 numpy.datetime64 物件。

Timestamp.to_numpy([dtype, copy])

將 Timestamp 轉換為 NumPy datetime64。

Timestamp.to_julian_date()

將 TimeStamp 轉換為儒略曆。

Timestamp.to_period([freq])

傳回此時間戳記為觀測值的期間。

Timestamp.to_pydatetime([警告])

將 Timestamp 物件轉換為原生 Python datetime 物件。

Timestamp.today([時區])

傳回當地時區的目前時間。

Timestamp.toordinal()

傳回前儒略日序數。

Timestamp.tz_convert(時區)

將具時區感知的 Timestamp 轉換為另一個時區。

Timestamp.tz_localize(時區[, 模稜兩可, ...])

將 Timestamp 定位到時區。

Timestamp.tzname()

傳回時區名稱。

Timestamp.utcfromtimestamp(時間戳記)

從 POSIX 時間戳記建構一個時區感知的 UTC datetime。

Timestamp.utcnow()

傳回一個新的 Timestamp 代表 UTC 日期和時間。

Timestamp.utcoffset()

傳回 UTC 偏移量。

Timestamp.utctimetuple()

傳回 UTC 時間元組,與 time.localtime() 相容。

Timestamp.weekday()

傳回日期所表示的星期幾。

一組時間戳記可以儲存在 arrays.DatetimeArray 中。對於時區感知資料,arrays.DatetimeArray.dtypeDatetimeTZDtype。對於時區非感知資料,會使用 np.dtype("datetime64[ns]")

如果資料有時區感知,則陣列中的每個值都必須有相同的時區。

arrays.DatetimeArray(values[, dtype, freq, copy])

Pandas 擴充陣列,用於時區無感知或時區感知的日期時間資料。

DatetimeTZDtype([unit, tz])

時區感知日期時間資料的擴充資料類型。

時間增量#

NumPy 可以原生表示時間增量。pandas 提供 Timedelta,以與 Timestamp 對稱。 NaT 是時間增量資料的遺失值。

Timedelta([value, unit])

表示持續時間,即兩個日期或時間之間的差異。

屬性#

Timedelta.asm8

傳回 numpy timedelta64 陣列標量檢視。

Timedelta.components

傳回元組命名類似的組件。

Timedelta.days

傳回時間增量的日期。

Timedelta.max

Timedelta.microseconds

Timedelta.min

Timedelta.nanoseconds

傳回奈秒數 (n),其中 0 <= n < 1 微秒。

Timedelta.resolution

Timedelta.seconds

傳回時間增量的總小時、分鐘和秒數,以秒為單位。

Timedelta.unit

Timedelta.value

Timedelta.view(dtype)

陣列檢視相容性。

方法#

Timedelta.as_unit(unit[, round_ok])

將基礎 int64 表示轉換為指定的單位。

Timedelta.ceil(freq)

傳回一個進位到此解析度的 Timedelta。

Timedelta.floor(freq)

傳回一個捨去到此解析度的 Timedelta。

Timedelta.isoformat()

將 Timedelta 格式化為 ISO 8601 Duration。

Timedelta.round(freq)

將 Timedelta 四捨五入到指定的解析度。

Timedelta.to_pytimedelta()

將 pandas Timedelta 物件轉換為 python datetime.timedelta 物件。

Timedelta.to_timedelta64()

傳回一個具有「ns」精度的 numpy.timedelta64 物件。

Timedelta.to_numpy([dtype, copy])

將 Timedelta 轉換為 NumPy timedelta64。

Timedelta.total_seconds()

持續時間中的總秒數。

可將 Timedelta 集合儲存在 TimedeltaArray 中。

arrays.TimedeltaArray(values[, dtype, freq, ...])

Pandas 擴充陣列,用於時間間隔資料。

週期#

pandas 將時間範圍表示為 Period 物件。

週期#

Period([value, freq, ordinal, year, month, ...])

表示一段時間。

屬性#

Period.day

取得週期所在的月份中的日期。

Period.dayofweek

週期所在的星期中的日期,星期一為 0,星期日為 6。

Period.day_of_week

週期所在的星期中的日期,星期一為 0,星期日為 6。

Period.dayofyear

傳回一年中的第幾天。

Period.day_of_year

傳回一年中的第幾天。

Period.days_in_month

取得此週期所在的月份中的總天數。

Period.daysinmonth

取得此週期所在的月份中的總天數。

Period.end_time

取得此週期的結束時間時間戳記。

Period.freq

Period.freqstr

傳回頻率的字串表示形式。

Period.hour

取得週期的日時間元件。

Period.is_leap_year

如果週期的年份為閏年,傳回 True。

Period.minute

取得 Period 中小時段的分鐘。

Period.month

傳回 Period 所屬的月份。

Period.ordinal

Period.quarter

傳回 Period 所屬的季度。

Period.qyear

根據起始季度,取得 Period 所屬的會計年度。

Period.second

取得 Period 的秒數部分。

Period.start_time

取得此期間開始時間的 Timestamp。

Period.week

取得給定 Period 中的一年中的第幾週。

Period.weekday

週期所在的星期中的日期,星期一為 0,星期日為 6。

Period.weekofyear

取得給定 Period 中的一年中的第幾週。

Period.year

傳回 Period 所屬的年份。

方法#

Period.asfreq(freq[, how])

將 Period 轉換為所需的頻率,在區間的開始或結束。

Period.now(freq)

傳回現在日期的期間。

Period.strftime(fmt)

傳回 Period 的格式化字串表示。

Period.to_timestamp([freq, how])

傳回 Period 的 Timestamp 表示。

可將 Period 集合儲存在 arrays.PeriodArray 中。在 arrays.PeriodArray 中的每個週期都必須具有相同的 freq

arrays.PeriodArray(values[, dtype, freq, copy])

Pandas ExtensionArray,用於儲存週期資料。

PeriodDtype(freq)

週期資料的 ExtensionDtype。

區間#

任意區間可表示為 Interval 物件。

區間

實作區間的不可變物件,一個有界的類似切片的區間。

屬性#

Interval.closed

描述區間包含側的字串。

Interval.closed_left

檢查區間是否在左側包含。

Interval.closed_right

檢查區間是否在右側包含。

Interval.is_empty

表示區間是否為空,表示不包含任何點。

Interval.left

區間的左邊界。

Interval.length

傳回區間的長度。

Interval.mid

傳回區間的中點。

Interval.open_left

檢查區間是否在左側開啟。

Interval.open_right

檢查區間是否在右側開啟。

Interval.overlaps(other)

檢查兩個 Interval 物件是否重疊。

Interval.right

區間的右邊界。

區間集合可以儲存在 arrays.IntervalArray 中。

arrays.IntervalArray(data[, closed, dtype, ...])

封閉於同一側的區間資料的 Pandas 陣列。

IntervalDtype([subtype, closed])

區間資料的 ExtensionDtype。

可為 Null 的整數#

numpy.ndarray 無法原生表示具有遺失值的整數資料。pandas 透過 arrays.IntegerArray 提供此功能。

arrays.IntegerArray(值, 遮罩[, 複製])

整數陣列(可選遺失)值。

Int8Dtype()

int8 整數資料的 ExtensionDtype。

Int16Dtype()

int16 整數資料的 ExtensionDtype。

Int32Dtype()

int32 整數資料的 ExtensionDtype。

Int64Dtype()

int64 整數資料的 ExtensionDtype。

UInt8Dtype()

uint8 整數資料的 ExtensionDtype。

UInt16Dtype()

uint16 整數資料的 ExtensionDtype。

UInt32Dtype()

uint32 整數資料的 ExtensionDtype。

UInt64Dtype()

uint64 整數資料的 ExtensionDtype。

可為 Null 的浮點數#

arrays.FloatingArray(值, 遮罩[, 複製])

浮點數陣列(可選遺失)值。

Float32Dtype()

float32 資料的 ExtensionDtype。

Float64Dtype()

float64 資料的 ExtensionDtype。

分類#

pandas 定義一種自訂資料類型,用於表示只能取有限、固定值集的資料。Categorical 的資料類型可以用 CategoricalDtype 來描述。

CategoricalDtype([categories, ordered])

具有類別和順序性的類別資料類型。

CategoricalDtype.categories

包含允許的唯一類別的Index

CategoricalDtype.ordered

類別是否具有順序關係。

類別資料可以儲存在pandas.Categorical

Categorical(values[, categories, ordered, ...])

以經典 R / S-plus 方式表示類別變數。

當您已具有類別和整數代碼時,可以使用替代建構函數Categorical.from_codes()

Categorical.from_codes(codes[, categories, ...])

從代碼和類別或資料類型建立類別類型。

資料類型資訊可在Categorical上取得

Categorical.dtype

此實例的CategoricalDtype

Categorical.categories

此類別的類別。

Categorical.ordered

類別是否具有順序關係。

Categorical.codes

此類別索引的類別代碼。

np.asarray(categorical)透過實作陣列介面來運作。請注意,這會將Categorical轉回 NumPy 陣列,因此類別和順序資訊不會保留!

Categorical.__array__([dtype])

numpy 陣列介面。

Categorical 可以儲存在 SeriesDataFrame 中。若要建立 dtype 為 category 的 Series,請使用 cat = s.astype(dtype)Series(..., dtype=dtype),其中 dtype 為下列任一項:

如果 Series 的 dtype 為 CategoricalDtype,則可以使用 Series.cat 來變更類別資料。請參閱 類別存取器 以取得更多資訊。

稀疏#

資料中單一值重複多次(例如 0NaN)可以用 arrays.SparseArray 有效儲存。

arrays.SparseArray(data[, sparse_index, ...])

用於儲存稀疏資料的擴充陣列。

SparseDtype([dtype, fill_value])

儲存在 SparseArray 中資料的資料類型。

如果 Series 包含稀疏值,可以使用 Series.sparse 存取器來存取稀疏特定屬性和方法。請參閱 稀疏存取器使用者指南 以了解更多資訊。

字串#

在處理文字資料時,其中每個有效元素都是字串或遺失值,我們建議使用 StringDtype(別名為 "string")。

arrays.StringArray(values[, copy])

字串資料的擴充陣列。

arrays.ArrowStringArray(values)

pyarrow.ChunkedArray 中字串資料的延伸陣列。

StringDtype([storage])

字串資料的延伸資料類型。

Series.str 存取器可供 Series 使用,而 arrays.StringArray 則支援 字串處理。詳情請參閱。

可為 Null 的布林#

布林資料類型(別名為 "boolean")支援儲存布林資料(TrueFalse),以及遺失值,而 numpy.ndarray 的布林值無法做到這一點。

arrays.BooleanArray(values, mask[, copy])

包含遺失值的布林(True/False)資料陣列。

BooleanDtype()

布林資料的延伸資料類型。

公用程式#

建構函式#

api.types.union_categoricals(to_union[, ...])

結合類別型清單,合併類別。

api.types.infer_dtype(value[, skipna])

傳回一個純量或清單值類型的字串標籤。

api.types.pandas_dtype(dtype)

將輸入轉換為僅限 pandas 的 dtype 物件或 numpy dtype 物件。

資料類型內省#

api.types.is_any_real_numeric_dtype(arr_or_dtype)

檢查提供的陣列或 dtype 是否為實數 dtype。

api.types.is_bool_dtype(arr_or_dtype)

檢查提供的陣列或 dtype 是否為布林 dtype。

api.types.is_categorical_dtype(arr_or_dtype)

(已棄用) 檢查陣列類似或 dtype 是否為類別 dtype。

api.types.is_complex_dtype(arr_or_dtype)

檢查提供的陣列或 dtype 是否為複數 dtype。

api.types.is_datetime64_any_dtype(arr_or_dtype)

檢查提供的陣列或 dtype 是否為 datetime64 dtype。

api.types.is_datetime64_dtype(arr_or_dtype)

檢查陣列或資料類型是否為 datetime64 資料類型。

api.types.is_datetime64_ns_dtype(arr_or_dtype)

檢查提供的陣列或資料類型是否為 datetime64[ns] 資料類型。

api.types.is_datetime64tz_dtype(arr_or_dtype)

(已棄用) 檢查陣列或資料類型是否為 DatetimeTZDtype 資料類型。

api.types.is_extension_array_dtype(arr_or_dtype)

檢查物件是否為 pandas 延伸陣列類型。

api.types.is_float_dtype(arr_or_dtype)

檢查提供的陣列或資料類型是否為浮點數資料類型。

api.types.is_int64_dtype(arr_or_dtype)

(已棄用) 檢查提供的陣列或資料類型是否為 int64 資料類型。

api.types.is_integer_dtype(arr_or_dtype)

檢查提供的陣列或資料型態是否為整數資料型態。

api.types.is_interval_dtype(arr_or_dtype)

(已棄用) 檢查陣列或資料型態是否為區間資料型態。

api.types.is_numeric_dtype(arr_or_dtype)

檢查提供的陣列或資料型態是否為數值資料型態。

api.types.is_object_dtype(arr_or_dtype)

檢查陣列或資料型態是否為物件資料型態。

api.types.is_period_dtype(arr_or_dtype)

(已棄用) 檢查陣列或資料型態是否為時間資料型態。

api.types.is_signed_integer_dtype(arr_or_dtype)

檢查提供的陣列或資料型態是否為有符號整數資料型態。

api.types.is_string_dtype(arr_or_dtype)

檢查提供的陣列或資料類型是否為字串資料類型。

api.types.is_timedelta64_dtype(arr_or_dtype)

檢查陣列類似或資料類型是否為 timedelta64 資料類型。

api.types.is_timedelta64_ns_dtype(arr_or_dtype)

檢查提供的陣列或資料類型是否為 timedelta64[ns] 資料類型。

api.types.is_unsigned_integer_dtype(arr_or_dtype)

檢查提供的陣列或資料類型是否為無符號整數資料類型。

api.types.is_sparse(arr)

(已棄用) 檢查陣列類似是否為 1-D pandas 稀疏陣列。

可迭代內省#

api.types.is_dict_like(obj)

檢查物件是否類似字典。

api.types.is_file_like(obj)

檢查物件是否為類似檔案的物件。

api.types.is_list_like(obj[, allow_sets])

檢查物件是否類似清單。

api.types.is_named_tuple(obj)

檢查物件是否為命名元組。

api.types.is_iterator(obj)

檢查物件是否為迭代器。

標量內省#

api.types.is_bool(obj)

如果給定的物件為布林值,傳回 True。

api.types.is_complex(obj)

如果給定的物件為複數,傳回 True。

api.types.is_float(obj)

如果給定的物件為浮點數,傳回 True。

api.types.is_hashable(obj)

如果 hash(obj) 會成功,傳回 True,否則傳回 False。

api.types.is_integer(obj)

如果給定的物件為整數,傳回 True。

api.types.is_interval(obj)

api.types.is_number(obj)

檢查物件是否為數字。

api.types.is_re(obj)

檢查物件是否為正則表達式模式實例。

api.types.is_re_compilable(obj)

檢查物件是否可以編譯成正規表示式模式實例。

api.types.is_scalar(val)

如果給定的物件是純量,則傳回 True。