pandas 数组、标量和数据类型

对象

对于大多数数据类型，pandas 使用 NumPy 数组作为包含在 Index、Series 或 DataFrame 中的具体对象。

对于某些数据类型，pandas 扩展了 NumPy 的类型系统。这些类型的字符串别名可以在 dtypes 中找到。

数据类型	pandas 数据类型	标量	数组
带时区的日期时间	DatetimeTZDtype	Timestamp	日期时间
时间差	(无)	Timedelta	时间差
周期（时间跨度）	PeriodDtype	Period	周期
区间	IntervalDtype	Interval	区间
可空整数	Int64Dtype, …	(无)	可空整数
可空浮点数	Float64Dtype, …	(无)	可空浮点数
分类	CategoricalDtype	(无)	分类
稀疏	SparseDtype	(无)	稀疏
字符串	StringDtype	str	字符串
可空布尔值	BooleanDtype	bool	可空布尔值
PyArrow	ArrowDtype	Python 标量或 NA	PyArrow

pandas 和第三方库可以扩展 NumPy 的类型系统（参见 扩展类型）。顶级 array() 方法可用于创建新数组，该数组可以存储在 Series、Index 中，或作为 DataFrame 中的一列。

array(data[, dtype, copy])

创建数组。

PyArrow

警告

此功能处于实验阶段，API 可能会在未来版本中更改，恕不另行通知。

该 arrays.ArrowExtensionArray 由一个 pyarrow.ChunkedArray 支持，该数组具有 pyarrow.DataType 而不是 NumPy 数组和数据类型。该 .dtype 的 arrays.ArrowExtensionArray 是一个 ArrowDtype.

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	(无)

注意

Pyarrow 支持的字符串类型可以通过 pd.StringDtype("pyarrow") 和 pd.ArrowDtype(pa.string()) 来实现。 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 扩展数组来支持这一点，该数组可以保存无时区或带时区的日期时间值。

Timestamp 是 datetime.datetime 的子类，是 pandas 用于无时区或带时区日期时间数据的标量类型。 NaT 是日期时间数据的缺失值。

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

Pandas 对 python datetime.datetime 对象的替代。

属性

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)	将日期、时间组合成具有相同日期和时间字段的日期时间。
Timestamp.ctime()	返回 ctime() 样式字符串。
Timestamp.date()	返回具有相同年份、月份和日期的日期对象。
Timestamp.day_name([locale])	返回 Timestamp 的星期名称，指定语言环境。
Timestamp.dst()	返回夏令时 (DST) 调整。
Timestamp.floor(freq[, ambiguous, nonexistent])	返回一个新的 Timestamp，向下取整到此分辨率。
Timestamp.fromordinal(ordinal[, tz])	从儒略日构建一个时间戳。
Timestamp.fromtimestamp(ts)	将时间戳[, tz] 转换为 tz 的本地时间，来自 POSIX 时间戳。
Timestamp.isocalendar()	返回一个命名元组，包含 ISO 年份、周数和星期几。
Timestamp.isoformat([sep, timespec])	以 ISO 8601 格式返回时间。
Timestamp.isoweekday()	返回日期所代表的星期几。
Timestamp.month_name([locale])	返回指定区域设置的 Timestamp 的月份名称。
Timestamp.normalize()	将 Timestamp 规范化为午夜，保留时区信息。
Timestamp.now([tz])	返回表示 tz 本地当前时间的新的 Timestamp 对象。
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([warn])	将 Timestamp 对象转换为原生 Python datetime 对象。
Timestamp.today([tz])	返回本地时区的当前时间。
Timestamp.toordinal()	返回儒略日。
Timestamp.tz_convert(tz)	将时区感知 Timestamp 转换为另一个时区。
Timestamp.tz_localize(tz[, ambiguous, ...])	将 Timestamp 本地化到时区。
Timestamp.tzname()	返回时区名称。
Timestamp.utcfromtimestamp(ts)	从 POSIX 时间戳构造一个时区感知的 UTC 日期时间。
Timestamp.utcnow()	返回一个表示 UTC 日期和时间的新的 Timestamp。
Timestamp.utcoffset()	返回 UTC 偏移量。
Timestamp.utctimetuple()	返回 UTC 时间元组，与 time.localtime() 兼容。
Timestamp.weekday()	返回日期所代表的星期几。

一组时间戳可以存储在 arrays.DatetimeArray 中。对于时区感知数据，arrays.DatetimeArray 的 .dtype 是 DatetimeTZDtype。对于时区无感知数据，使用 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 持续时间。
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, ...])

用于 timedelta 数据的 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.month	返回此周期所在的月份。
Period.ordinal
Period.quarter	返回此周期所在的季度。
Period.qyear	根据周期的起始季度，返回周期所在的财年。
Period.second	获取周期的秒分量。
Period.start_time	获取周期开始的时间戳。
Period.week	获取给定周期所在的年份的周数。
Period.weekday	周期所在的星期几，星期一=0，星期日=6。
Period.weekofyear	获取给定周期所在的年份的周数。
Period.year	返回此周期所在的年份。

方法

Period.asfreq(freq[, how])	将周期转换为所需的频率，位于时间段的开始或结束。
Period.now(freq)	返回当前日期的周期。
Period.strftime(fmt)	返回Period的格式化字符串表示。
Period.to_timestamp([freq, how])	返回周期的 Timestamp 表示。

一个 Period 的集合可以存储在 arrays.PeriodArray 中。 arrays.PeriodArray 中的每个周期必须具有相同的 freq。

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

用于存储 Period 数据的 Pandas 扩展数组。

PeriodDtype(freq)

用于 Period 数据的扩展数据类型。

区间

任意区间可以表示为 Interval 对象。

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。

可空整数

numpy.ndarray 本身无法表示具有缺失值的整数数据。pandas 通过 arrays.IntegerArray 提供此功能。

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

整数（可选缺失）值的数组。

Int8Dtype()	用于 int8 整数数据的 ExtensionDtype。
Int16Dtype()	用于 int16 整数数据的 ExtensionDtype。
Int32Dtype()	用于 int32 整数数据的 ExtensionDtype。
Int64Dtype()	用于 int64 整数数据的 ExtensionDtype。
UInt8Dtype()	用于 uint8 整数数据的 ExtensionDtype。
UInt16Dtype()	用于 uint16 整数数据的 ExtensionDtype。
UInt32Dtype()	用于 uint32 整数数据的 ExtensionDtype。
UInt64Dtype()	用于 uint64 整数数据的 ExtensionDtype。

可空浮点数

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

浮点数（可选缺失）值的数组。

Float32Dtype()	用于 float32 数据的 ExtensionDtype。
Float64Dtype()	用于 float64 数据的 ExtensionDtype。

分类数据

pandas 定义了一种自定义数据类型，用于表示只能取有限固定值集的数据。 Categorical 的 dtype 可以用 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 可以存储在 Series 或 DataFrame 中。要创建 dtype 为 category 的 Series，请使用 cat = s.astype(dtype) 或 Series(..., dtype=dtype)，其中 dtype 可以是：

• 字符串 'category'

• CategoricalDtype 的实例。

如果 Series 的 dtype 为 CategoricalDtype，则可以使用 Series.cat 来更改分类数据。有关更多信息，请参见 分类访问器。

稀疏

数据中单个值重复多次（例如 0 或 NaN）可以有效地存储为 arrays.SparseArray。

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

用于存储稀疏数据的扩展数组。

SparseDtype([dtype, fill_value])

存储在 SparseArray 中的数据的 Dtype。

如果 Series 包含稀疏值，则可以使用 Series.sparse 访问器访问稀疏特定属性和方法。有关更多信息，请参阅 稀疏访问器 和 用户指南。

字符串

在处理文本数据时，其中每个有效元素都是字符串或缺失，我们建议使用 StringDtype（别名为 "string"）。

arrays.StringArray(values[, copy])	用于字符串数据的扩展数组。
arrays.ArrowStringArray(values)	用于 pyarrow.ChunkedArray 中字符串数据的扩展数组。

StringDtype([storage])

用于字符串数据的扩展 dtype。

对于由 arrays.StringArray 支持的 Series，可以使用 Series.str 访问器。有关更多信息，请参阅 字符串处理。

可空布尔值

布尔 dtype（别名为 "boolean"）支持存储布尔数据（True、False）以及缺失值，而这在 bool numpy.ndarray 中是不可能的。

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

包含缺失值的布尔（True/False）数据的数组。

BooleanDtype()

布尔数据的扩展 dtype。

实用程序

构造函数

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)	(已弃用) 检查数组或数据类型是否为 Categorical 数据类型。
api.types.is_complex_dtype(arr_or_dtype)	检查提供的数组或数据类型是否为复数数据类型。
api.types.is_datetime64_any_dtype(arr_or_dtype)	检查提供的数组或数据类型是否为 datetime64 数据类型。
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)	(已弃用) 检查数组或数据类型是否为 Interval 数据类型。
api.types.is_numeric_dtype(arr_or_dtype)	检查提供的数组或数据类型是否为数值数据类型。
api.types.is_object_dtype(arr_or_dtype)	检查数组或数据类型是否为 object 数据类型。
api.types.is_period_dtype(arr_or_dtype)	(已弃用) 检查数组或数据类型是否为 Period 数据类型。
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)	(已弃用) 检查类数组对象是否为一维 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。