pandas.array#

pandas.array(data,dtype=None,copy=True)[source]#

Create an array.

Parameters:

dataSequence of objects

The scalars insidedata should be instances of thescalar type fordtype. It’s expected thatdatarepresents a 1-dimensional array of data.

Whendata is an Index or Series, the underlying arraywill be extracted fromdata.

dtypestr, np.dtype, or ExtensionDtype, optional

The dtype to use for the array. This may be a NumPydtype or an extension type registered with pandas usingpandas.api.extensions.register_extension_dtype().

If not specified, there are two possibilities:

1. Whendata is aSeries,Index, orExtensionArray, thedtype will be takenfrom the data.

2. Otherwise, pandas will attempt to infer thedtypefrom the data.

Note that whendata is a NumPy array,data.dtype isnot used for inferring the array type. This is becauseNumPy cannot represent all the types of data that can beheld in extension arrays.

Currently, pandas will infer an extension dtype for sequences of

Scalar Type	Array Type
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 orpandas.arrays.ArrowStringArray
bool	pandas.arrays.BooleanArray

The ExtensionArray created when the scalar type isstr is determined bypd.options.mode.string_storage if the dtype is not explicitly given.

For all other cases, NumPy’s usual inference rules will be used.

copybool, default True

Whether to copy the data, even if not necessary. Dependingon the type ofdata, creating the new array may requirecopying data, even ifcopy=False.

Returns:

ExtensionArray

The newly created array.

Raises:

ValueError

Whendata is not 1-dimensional.

See also

numpy.array

Construct a NumPy array.

Series

Construct a pandas Series.

Index

Construct a pandas Index.

arrays.NumpyExtensionArray

ExtensionArray wrapping a NumPy array.

Series.array

Extract the array stored within a Series.

Notes

Omitting thedtype argument means pandas will attempt to infer thebest array type from the values in the data. As new array types areadded by pandas and 3rd party libraries, the “best” array type maychange. We recommend specifyingdtype to ensure that

1. the correct array type for the data is returned

2. the returned array type doesn’t change as new extension typesare added by pandas and third-party libraries

Additionally, if the underlying memory representation of the returnedarray matters, we recommend specifying thedtype as a concrete objectrather than a string alias or allowing it to be inferred. For example,a future version of pandas or a 3rd-party library may include adedicated ExtensionArray for string data. In this event, the followingwould no longer return aarrays.NumpyExtensionArray backed by aNumPy array.

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

This would instead return the new ExtensionArray dedicated for stringdata. 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"))<NumpyExtensionArray>['a', 'b']Length: 2, dtype: str32

Finally, Pandas has arrays that mostly overlap with NumPy

• arrays.DatetimeArray

• arrays.TimedeltaArray

When data with adatetime64[ns] ortimedelta64[ns] dtype ispassed, pandas will always return aDatetimeArray orTimedeltaArrayrather than aNumpyExtensionArray. This is for symmetry with the case oftimezone-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>['0 days 01:00:00', '0 days 02:00:00']Length: 2, dtype: timedelta64[ns]

Examples

If a dtype is not specified, pandas will infer the best dtype from the values.See the description ofdtype for the types pandas infers for.

>>>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

>>>withpd.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]

You can use the string alias fordtype

>>>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']

If pandas does not infer a dedicated extension type aarrays.NumpyExtensionArray is returned.

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

As mentioned in the “Notes” section, new extension types may be addedin the future (by pandas or 3rd party libraries), causing the returnvalue to no longer be aarrays.NumpyExtensionArray. Specify thedtype as a NumPy dtype if you need to ensure there’s no future change inbehavior.

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

data must be 1-dimensional. A ValueError is raised when the inputhas the wrong dimensionality.

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