pandas.array(data: Sequence[object], dtype: Union[str, numpy.dtype, pandas.core.dtypes.base.ExtensionDtype, NoneType] = None, copy: bool = True) → pandas.core.dtypes.generic.ABCExtensionArray
[source]
Create an array.
New in version 0.24.0.
Parameters: |
|
---|---|
Returns: |
|
Raises: |
|
See also
numpy.array
Series
Index
arrays.PandasArray
Series.array
Omitting the dtype
argument means pandas will attempt to infer the best array type from the values in the data. As new array types are added by pandas and 3rd party libraries, the “best” array type may change. We recommend specifying dtype
to ensure that
Additionally, if the underlying memory representation of the returned array matters, we recommend specifying the dtype
as a concrete object rather than a string alias or allowing it to be inferred. For example, a future version of pandas or a 3rd-party library may include a dedicated ExtensionArray for string data. In this event, the following would no longer return a arrays.PandasArray
backed by a NumPy array.
>>> pd.array(['a', 'b'], dtype=str) <PandasArray> ['a', 'b'] Length: 2, dtype: str32
This would instead return the new ExtensionArray dedicated for string data. If you really need the new array to be backed by a NumPy array, specify that in the dtype.
>>> pd.array(['a', 'b'], dtype=np.dtype("<U1")) <PandasArray> ['a', 'b'] Length: 2, dtype: str32
Or use the dedicated constructor for the array you’re expecting, and wrap that in a PandasArray
>>> pd.array(np.array(['a', 'b'], dtype='<U1')) <PandasArray> ['a', 'b'] Length: 2, dtype: str32
Finally, Pandas has arrays that mostly overlap with NumPy
When data with a datetime64[ns]
or timedelta64[ns]
dtype is passed, pandas will always return a DatetimeArray
or TimedeltaArray
rather than a PandasArray
. This is for symmetry with the case of timezone-aware data, which NumPy does not natively support.
>>> 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> ['01:00:00', '02:00:00'] Length: 2, dtype: timedelta64[ns]
If a dtype is not specified, data
is passed through to numpy.array()
, and a arrays.PandasArray
is returned.
>>> pd.array([1, 2]) <PandasArray> [1, 2] Length: 2, dtype: int64
Or the NumPy dtype can be specified
>>> pd.array([1, 2], dtype=np.dtype("int32")) <PandasArray> [1, 2] Length: 2, dtype: int32
You can use the string alias for dtype
>>> pd.array(['a', 'b', 'a'], dtype='category') [a, b, a] Categories (2, object): [a, b]
Or specify the actual dtype
>>> pd.array(['a', 'b', 'a'], ... dtype=pd.CategoricalDtype(['a', 'b', 'c'], ordered=True)) [a, b, a] Categories (3, object): [a < b < c]
Because omitting the dtype
passes the data through to NumPy, a mixture of valid integers and NA will return a floating-point NumPy array.
>>> pd.array([1, 2, np.nan]) <PandasArray> [1.0, 2.0, nan] Length: 3, dtype: float64
To use pandas’ nullable pandas.arrays.IntegerArray
, specify the dtype:
>>> pd.array([1, 2, np.nan], dtype='Int64') <IntegerArray> [1, 2, NaN] Length: 3, dtype: Int64
Pandas will infer an ExtensionArray for some types of data:
>>> pd.array([pd.Period('2000', freq="D"), pd.Period("2000", freq="D")]) <PeriodArray> ['2000-01-01', '2000-01-01'] Length: 2, dtype: period[D]
data
must be 1-dimensional. A ValueError is raised when the input has the wrong dimensionality.
>>> pd.array(1) Traceback (most recent call last): ... ValueError: Cannot pass scalar '1' to 'pandas.array'.
© 2008–2012, AQR Capital Management, LLC, Lambda Foundry, Inc. and PyData Development Team
Licensed under the 3-clause BSD License.
https://pandas.pydata.org/pandas-docs/version/0.25.0/reference/api/pandas.array.html