pandas 数组、标量和数据类型

Objects

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

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

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

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

数组(数据[, 数据类型, 复制])

创建一个数组。

PyArrow

警告

此功能是实验性的，API 可能在未来的版本中无预警地更改。

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

Pyarrow 提供了类似于 NumPy 的数组和 数据类型 支持，包括所有数据类型的第一类可空性支持、不可变性等。

下表显示了 pandas 识别的等效 pyarrow-backed (pa)、pandas 扩展和 numpy (np) 类型。下面的 Pyarrow-backed 类型需要传递给 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 是日期时间数据的缺失值。

时间戳([ts_input, year, month, day, ...])

Pandas 用于替代 python datetime.datetime 对象的替换方案。

属性

Timestamp.asm8	返回具有相同精度的 numpy datetime64 格式。
Timestamp.day	Return the day of the Timestamp.
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 的年份季度。
Timestamp.resolution
Timestamp.second
Timestamp.tz	tzinfo 的别名。
Timestamp.tzinfo
Timestamp.unit	与 self._creso 相关的缩写。
Timestamp.value
Timestamp.week	返回一年中的周数。
Timestamp.weekofyear	返回一年中的周数。
Timestamp.year

方法

Timestamp.as_unit(单位[, 四舍五入_允许])	将底层的 int64 表示转换为给定的单位。
Timestamp.astimezone(tz)	将时区感知的 Timestamp 转换为另一个时区。
Timestamp.ceil(freq[, ambiguous, nonexistent])	返回一个新的 Timestamp，向上舍入到此分辨率。
Timestamp.combine(日期, 时间)	将日期和时间合并成一个单一的时间戳对象。
Timestamp.ctime()	返回一个表示时间戳的 ctime() 样式字符串。
Timestamp.date()	返回具有相同年、月和日的 datetime.date。
Timestamp.day_name([locale])	返回带有指定区域设置的时间戳的日期名称。
Timestamp.dst()	返回夏令时（DST）调整。
Timestamp.floor(freq[, ambiguous, nonexistent])	返回一个新的 Timestamp，向下取整到此分辨率。
Timestamp.fromordinal(ordinal[, tz])	从一个预设的格列高利序数构建一个时间戳。
Timestamp.fromtimestamp(ts[, tz])	从 POSIX 时间戳创建一个 Timestamp 对象。
Timestamp.isocalendar()	返回一个包含 ISO 年份、周数和工作日的命名元组。
Timestamp.isoformat([sep, timespec])	返回根据 ISO 8601 格式化的时间。
Timestamp.isoweekday()	返回由日期表示的星期几。
Timestamp.month_name([locale])	返回具有指定区域设置的时间戳的月份名称。
Timestamp.normalize()	将时间戳标准化为午夜，保留时区信息。
Timestamp.now([tz])	返回一个新的 Timestamp 对象，表示当前时间，本地化为 tz。
Timestamp.replace([年, 月, 日, 时, ...])	实现 datetime.replace，处理纳秒。
Timestamp.round(freq[, ambiguous, nonexistent])	将时间戳四舍五入到指定的分辨率。
Timestamp.strftime(格式)	返回时间戳的格式化字符串。
Timestamp.strptime(date_string, format)	将字符串参数转换为日期时间。
Timestamp.time()	返回一个时间对象，时间相同但 tzinfo=None。
Timestamp.timestamp()	返回 POSIX 时间戳作为浮点数。
Timestamp.timetuple()	返回时间元组，兼容 time.localtime()。
Timestamp.timetz()	返回具有相同时间和时区信息的时间对象。
Timestamp.to_datetime64()	返回一个具有相同精度的 NumPy datetime64 对象。
Timestamp.to_numpy([dtype, copy])	将时间戳转换为 NumPy datetime64。
Timestamp.to_julian_date()	将时间戳转换为儒略日期。
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.tzname()	返回时区名称。
Timestamp.utcfromtimestamp(ts)	从 POSIX 时间戳构造一个时区感知的 UTC 日期时间。
Timestamp.utcnow()	返回一个新的 Timestamp 表示 UTC 日期和时间。
Timestamp.utcoffset()	返回 utc 偏移量。
Timestamp.utctimetuple()	返回UTC时间元组，兼容 time.localtime()。
Timestamp.weekday()	返回由日期表示的星期几。

时间戳集合可以存储在 arrays.DatetimeArray 中。对于时区感知的数据，arrays.DatetimeArray 的 .dtype 是 DatetimeTZDtype。对于时区不可知的数据，使用 np.dtype("datetime64[ns]")。

如果数据是时区感知的，那么数组中的每个值必须具有相同的时区。

arrays.DatetimeArray(数据[, 数据类型, 频率, 复制])

用于 tz-naive 或 tz-aware 日期时间数据的 Pandas ExtensionArray。

DatetimeTZDtype([单位, 时区])

一个用于时区感知日期时间数据的扩展数据类型。

Timedeltas

NumPy 可以原生表示时间增量。pandas 提供了 Timedelta 以与 Timestamp 对称。NaT 是时间增量数据的缺失值。

Timedelta([value, unit])

表示一个时间段，即两个日期或时间之间的差异。

属性

Timedelta.asm8	返回一个 numpy timedelta64 数组标量视图。
Timedelta.components	返回一个类似命名元组的组件。
Timedelta.days	返回 timedelta 的天数。
Timedelta.max
Timedelta.microseconds	返回微秒数（n），其中 0 <= n < 1 毫秒。
Timedelta.min
Timedelta.nanoseconds	返回纳秒数（n），其中 0 <= n < 1 微秒。
Timedelta.resolution
Timedelta.seconds	返回 timedelta 的总小时、分钟和秒数为秒。
Timedelta.unit	返回 Timedelta 对象的单位。
Timedelta.value	返回 Timedelta 对象的纳秒值。
Timedelta.view(dtype)	数组视图兼容性。

方法

Timedelta.as_unit(单位[, 允许四舍五入])	将底层的 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(data[, dtype, freq, copy])

用于 timedelta 数据的 Pandas ExtensionArray。

周期

pandas 将时间段表示为 Period 对象。

周期

周期([值, 频率, 序数, 年, 月, ...])

表示一段时间。

属性

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的第二个组件。
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])	返回 Period 的时间戳表示。

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

数组.PeriodArray(values[, dtype, copy])

用于存储Period数据的Pandas ExtensionArray。

PeriodDtype(freq)

用于周期数据的 ExtensionDtype。

区间

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

区间	实现间隔（Interval）的不可变对象，一个类似有界切片的间隔。

属性

Interval.closed	描述区间包含侧的字符串。
Interval.closed_left	检查区间是否在左侧闭合。
Interval.closed_right	检查区间是否在右侧闭合。
Interval.is_empty	指示一个区间是否为空，即它不包含任何点。
Interval.left	区间的左边界。
Interval.length	返回 Interval 的长度。
Interval.mid	返回区间的中间点。
Interval.open_left	检查区间是否在左侧开放。
Interval.open_right	检查区间是否在右侧开放。
Interval.overlaps(other)	检查两个 Interval 对象是否重叠。
Interval.right	区间的右边界。

一组区间可以存储在 arrays.IntervalArray 中。

arrays.IntervalArray(数据[, 闭合, 数据类型, ...])

用于闭合在同一边的区间数据的 Pandas 数组。

IntervalDtype([子类型, 闭合])

用于区间数据的 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([类别, 有序])

用于分类数据的类型，包含类别和有序性。

CategoricalDtype.categories	一个包含允许的唯一类别的 Index。
CategoricalDtype.ordered	类别是否具有有序关系。

分类数据可以存储在 pandas.Categorical 中

分类(values[, categories, ordered, ...])

以经典的 R / S-plus 风格表示一个分类变量。

当你已经有类别和整数码时，可以使用替代的 Categorical.from_codes() 构造函数：

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

从代码和类别或数据类型创建一个分类类型。

dtype 信息可以在 Categorical 上找到

Categorical.dtype	这个实例的 CategoricalDtype。
Categorical.categories	这个分类的类别。
Categorical.ordered	类别是否具有有序关系。
Categorical.codes	这个分类索引的类别代码。

np.asarray(categorical) 通过实现数组接口来工作。请注意，这将把 Categorical 转换回 NumPy 数组，因此类别和顺序信息不会被保留！

Categorical.__array__([dtype, copy])

numpy 数组接口。

一个 Categorical 可以存储在一个 Series 或 DataFrame 中。要创建一个 dtype 为 category 的 Series，使用 cat = s.astype(dtype) 或 Series(..., dtype=dtype)，其中 dtype 是

• 字符串 'category'

• 一个 CategoricalDtype 的实例。

如果 Series 是 CategoricalDtype 类型的，可以使用 Series.cat 来更改分类数据。更多信息请参见 Categorical 访问器。

在 Categorical 上有更多方法可用：

Categorical.as_ordered()	设置分类变量为有序。
Categorical.as_unordered()	将分类设置为无序。
Categorical.set_categories(new_categories[, ...])	将类别设置为指定的新类别。
Categorical.rename_categories(new_categories)	重命名类别。
Categorical.reorder_categories(new_categories)	按照 new_categories 中的指定重新排序类别。
Categorical.add_categories(new_categories)	添加新类别。
Categorical.remove_categories(移除项)	移除指定的类别。
Categorical.remove_unused_categories()	移除未使用的类别。
Categorical.map(mapper[, na_action])	使用输入映射或函数映射类别。

Sparse

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

arrays.SparseArray(数据[, 稀疏索引, ...])

用于存储稀疏数据的 ExtensionArray。

SparseDtype([dtype, fill_value])

存储在 SparseArray 中的数据的 Dtype。

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

字符串

在处理文本数据时，每个有效元素是一个字符串或缺失，我们推荐使用 StringDtype （使用别名 "string"）。

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

StringDtype([存储, na_值])

字符串数据的扩展 dtype。

Series.str 访问器适用于由 arrays.StringArray 支持的 Series。更多信息请参见 字符串处理。

可空布尔值

布尔数据类型（带有别名 "boolean"）提供了对存储布尔数据（True，False）以及缺失值的支持，这是使用布尔 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)	（已弃用）检查数组类或dtype是否为Categorical 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)	检查一个类数组或dtype是否为datetime64 dtype。
api.types.is_datetime64_ns_dtype(arr_or_dtype)	检查提供的数组或dtype是否为datetime64[ns] dtype。
api.types.is_datetime64tz_dtype(arr_or_dtype)	(已弃用) 检查一个类似数组或 dtype 是否为 DatetimeTZDtype dtype。
api.types.is_extension_array_dtype(arr_or_dtype)	检查对象是否为 pandas 扩展数组类型。
api.types.is_float_dtype(arr_or_dtype)	检查提供的数组或dtype是否为浮点型dtype。
api.types.is_int64_dtype(arr_or_dtype)	(已弃用) 检查提供的数组或 dtype 是否为 int64 dtype。
api.types.is_integer_dtype(arr_or_dtype)	检查提供的数组或dtype是否为整数dtype。
api.types.is_interval_dtype(arr_or_dtype)	（已弃用）检查数组类或数据类型是否为区间数据类型。
api.types.is_numeric_dtype(arr_or_dtype)	检查提供的数组或dtype是否为数值型dtype。
api.types.is_object_dtype(arr_or_dtype)	检查一个类似数组或dtype是否是对象dtype。
api.types.is_period_dtype(arr_or_dtype)	（已弃用）检查数组类或数据类型是否为 Period 数据类型。
api.types.is_signed_integer_dtype(arr_or_dtype)	检查提供的数组或dtype是否为有符号整数dtype。
api.types.is_string_dtype(arr_or_dtype)	检查提供的数组或dtype是否为字符串dtype。
api.types.is_timedelta64_dtype(arr_or_dtype)	检查一个类数组或dtype是否为timedelta64 dtype。
api.types.is_timedelta64_ns_dtype(arr_or_dtype)	检查提供的数组或dtype是否为timedelta64[ns] dtype。
api.types.is_unsigned_integer_dtype(arr_or_dtype)	检查提供的数组或dtype是否为无符号整数dtype。
api.types.is_sparse(arr)	(已弃用) 检查一个类数组对象是否是1维的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_number(obj)	检查对象是否为数字。
api.types.is_re(obj)	检查对象是否为正则表达式模式实例。
api.types.is_re_compilable(obj)	检查对象是否可以编译成正则表达式模式实例。
api.types.is_scalar(val)	如果给定的对象是标量，则返回 True。