pandas.Index.to_numpy

Index.to_numpy(dtype=None, copy=False, na_value=NoDefault.no_default, **kwargs)[source]

A NumPy ndarray representing the values in this Series or Index.

Parameters
dtype:str or numpy.dtype, optional

The dtype to pass to numpy.asarray().

copy:bool, default False

Whether to ensure that the returned value is not a view on another array. Note that copy=False does not ensure that to_numpy() is no-copy. Rather, copy=True ensure that a copy is made, even if not strictly necessary.

na_value:Any, optional

The value to use for missing values. The default value depends on dtype and the type of the array.

New in version 1.0.0.

**kwargs

Additional keywords passed through to the to_numpy method of the underlying array (for extension arrays).

New in version 1.0.0.

Returns
numpy.ndarray

See also

Series.array

Get the actual data stored within.

Index.array

Get the actual data stored within.

DataFrame.to_numpy

Similar method for DataFrame.

Notes

The returned array will be the same up to equality (values equal in self will be equal in the returned array; likewise for values that are not equal). When self contains an ExtensionArray, the dtype may be different. For example, for a category-dtype Series, to_numpy() will return a NumPy array and the categorical dtype will be lost.

For NumPy dtypes, this will be a reference to the actual data stored in this Series or Index (assuming copy=False). Modifying the result in place will modify the data stored in the Series or Index (not that we recommend doing that).

For extension types, to_numpy() may require copying data and coercing the result to a NumPy type (possibly object), which may be expensive. When you need a no-copy reference to the underlying data, Series.array should be used instead.

This table lays out the different dtypes and default return types of to_numpy() for various dtypes within pandas.

dtype

array type

category[T]

ndarray[T] (same dtype as input)

period

ndarray[object] (Periods)

interval

ndarray[object] (Intervals)

IntegerNA

ndarray[object]

datetime64[ns]

datetime64[ns]

datetime64[ns, tz]

ndarray[object] (Timestamps)

Examples

>>> ser = pd.Series(pd.Categorical(['a', 'b', 'a']))
>>> ser.to_numpy()
array(['a', 'b', 'a'], dtype=object)

Specify the dtype to control how datetime-aware data is represented. Use dtype=object to return an ndarray of pandas Timestamp objects, each with the correct tz.

>>> ser = pd.Series(pd.date_range('2000', periods=2, tz="CET"))
>>> ser.to_numpy(dtype=object)
array([Timestamp('2000-01-01 00:00:00+0100', tz='CET'),
       Timestamp('2000-01-02 00:00:00+0100', tz='CET')],
      dtype=object)

Or dtype='datetime64[ns]' to return an ndarray of native datetime64 values. The values are converted to UTC and the timezone info is dropped.

>>> ser.to_numpy(dtype="datetime64[ns]")
... 
array(['1999-12-31T23:00:00.000000000', '2000-01-01T23:00:00...'],
      dtype='datetime64[ns]')

© 2008–2021, 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/1.3.4/reference/api/pandas.Index.to_numpy.html