pandas.array

pandas.array(data, dtype=None, copy=True)

创建一个数组。

Parameters:

data对象序列

data 中的标量应为 dtype 的标量类型的实例。预期 data 代表数据的 1 维数组。

当 data 是 Index 或 Series 时，将从 data 中提取底层数组。

dtypestr、np.dtype 或 ExtensionDtype，可选

用于该数组的 dtype。这可以是 NumPy dtype 或使用 pandas.api.extensions.register_extension_dtype() 注册到 pandas 的扩展类型。

如果未指定，则有两种可能性：

1. 当 data 是 Series 、Index 或 ExtensionArray 时，dtype 将从数据中获取。

2. 否则，pandas 将尝试从数据中推断 dtype。

请注意，当 data 是 NumPy 数组时，不会使用 data.dtype 来推断数组类型。这是因为 NumPy 无法表示扩展数组中可以包含的所有数据类型。

目前，pandas 将为以下内容的序列推断扩展 dtype：

标量类型	数组类型
pandas.Interval	pandas.arrays.IntervalArray
pandas.Period	pandas.arrays.PeriodArray
datetime.datetime	pandas.arrays.DatetimeArray
datetime.timedelta	pandas.arrays.TimedeltaArray
int	pandas.arrays.IntegerArray
float	pandas.arrays.FloatingArray
str	pandas.arrays.StringArray 或 pandas.arrays.ArrowStringArray
bool	pandas.arrays.BooleanArray

当标量类型为 str 时创建的 ExtensionArray 取决于 pd.options.mode.string_storage，前提是未显式给出 dtype。

对于所有其他情况，将使用 NumPy 的常规推断规则。

copybool, default True

是否复制数据，即使没有必要。根据 data 的类型，即使 copy=False，创建新数组也可能需要复制数据。

Returns:

ExtensionArray

新创建的数组。

Raises:

ValueError

当 data 不是 1 维时。

参见

numpy.array

构造一个 NumPy 数组。

Series

构造一个 pandas Series。

Index

构造一个 pandas Index。

arrays.NumpyExtensionArray

包装 NumPy 数组的 ExtensionArray。

Series.array

提取 Series 中存储的数组。

Notes

省略 dtype 参数意味着 pandas 将尝试从数据中的值推断最佳数组类型。随着 pandas 和第三方库添加新的数组类型，“最佳”数组类型可能会发生变化。我们建议指定 dtype 以确保：

1. 返回数据的正确数组类型

2. 返回的数组类型不会随着 pandas 和第三方库添加新的扩展类型而改变

此外，如果返回数组的底层内存表示很重要，我们建议将 dtype 指定为具体对象，而不是字符串别名，或者允许自动推断。例如，pandas 的未来版本或第三方库可能会包含专用的字符串扩展数组。在这种情况下，以下代码将不再返回由 NumPy 数组支持的 arrays.NumpyExtensionArray 。

>>> pd.array(['a', 'b'], dtype=str)
<NumpyExtensionArray>
['a', 'b']
Length: 2, dtype: str32

这将改返回支持字符串数据的新的 ExtensionArray。如果您确实需要新数组由 NumPy 数组支持，请在 dtype 中指定。

>>> pd.array(['a', 'b'], dtype=np.dtype("<U1"))
<NumpyExtensionArray>
['a', 'b']
Length: 2, dtype: str32

最后，Pandas 提供的数组与 NumPy 大致重叠

• arrays.DatetimeArray

• arrays.TimedeltaArray

当传递具有 datetime64[ns] 或 timedelta64[ns] dtype 的数据时，pandas 将始终返回 DatetimeArray 或 TimedeltaArray，而不是 NumpyExtensionArray。这是为了与 NumPy 原生不支持的时区感知数据情况保持对称。

>>> pd.array(['2015', '2016'], dtype='datetime64[ns]')
<DatetimeArray>
['2015-01-01 00:00:00', '2016-01-01 00:00:00']
Length: 2, dtype: datetime64[ns]

>>> pd.array(["1h", "2h"], dtype='timedelta64[ns]')
<TimedeltaArray>
['0 days 01:00:00', '0 days 02:00:00']
Length: 2, dtype: timedelta64[ns]

Examples

如果未指定 dtype，pandas 将从值中推断最佳 dtype。有关 pandas 推断类型的说明，请参阅 dtype 的说明。

>>> pd.array([1, 2])
<IntegerArray>
[1, 2]
Length: 2, dtype: Int64

>>> pd.array([1, 2, np.nan])
<IntegerArray>
[1, 2, <NA>]
Length: 3, dtype: Int64

>>> pd.array([1.1, 2.2])
<FloatingArray>
[1.1, 2.2]
Length: 2, dtype: Float64

>>> pd.array(["a", None, "c"])
<StringArray>
['a', <NA>, 'c']
Length: 3, dtype: string

>>> with pd.option_context("string_storage", "pyarrow"):
...     arr = pd.array(["a", None, "c"])
...
>>> arr
<ArrowStringArray>
['a', <NA>, 'c']
Length: 3, dtype: string

>>> pd.array([pd.Period('2000', freq="D"), pd.Period("2000", freq="D")])
<PeriodArray>
['2000-01-01', '2000-01-01']
Length: 2, dtype: period[D]

您可以使用 dtype 的字符串别名

>>> pd.array(['a', 'b', 'a'], dtype='category')
['a', 'b', 'a']
Categories (2, object): ['a', 'b']

或者指定实际的 dtype

>>> pd.array(['a', 'b', 'a'],
...          dtype=pd.CategoricalDtype(['a', 'b', 'c'], ordered=True))
['a', 'b', 'a']
Categories (3, object): ['a' < 'b' < 'c']

如果 pandas 未推断出专用扩展类型，则会返回 arrays.NumpyExtensionArray 。

>>> pd.array([1 + 1j, 3 + 2j])
<NumpyExtensionArray>
[(1+1j), (3+2j)]
Length: 2, dtype: complex128

如“备注”部分所述，未来可能会添加新的扩展类型（由 pandas 或第三方库添加），导致返回值不再是 arrays.NumpyExtensionArray 。如果需要确保行为不会发生将来变化，请将 dtype 指定为 NumPy dtype。

>>> pd.array([1, 2], dtype=np.dtype("int32"))
<NumpyExtensionArray>
[1, 2]
Length: 2, dtype: int32

data 必须是 1 维的。当输入维度不正确时，会引发 ValueError。

>>> pd.array(1)
Traceback (most recent call last):
  ...
ValueError: Cannot pass scalar '1' to 'pandas.array'.