Skip to main content
`Ctrl`+`K`

# pandas.api.extensions.ExtensionArray.take

ExtensionArray.take(indices, *, allow_fill=False, fill_value=None)

  Take elements from an array.

  Parameters:
    indices sequence of int or one-dimensional np.ndarray of int

      Indices to be taken.

    allow_fill bool, default False

      How to handle negative values in indices.

      - False: negative values in indices indicate positional indices from the right (the default). This is similar to `numpy.take()`.

      - True: negative values in indices indicate missing values. These values are set to fill_value. Any other other negative values raise a `ValueError`.

    fill_value any, optional

      Fill value to use for NA-indices when allow_fill is True. This may be `None`, in which case the default NA value for the type, `self.dtype.na_value`, is used.

      For many ExtensionArrays, there will be two representations of fill_value: a user-facing “boxed” scalar, and a low-level physical NA value. fill_value should be the user-facing version, and the implementation should handle translating that to the physical version for processing the take if necessary.

  Returns:
    ExtensionArray

      An array formed with selected indices.

  Raises:
    IndexError

      When the indices are out of bounds for the array.

    ValueError

      When indices contains negative values other than `-1` and allow_fill is True.

  See also

  `numpy.take`

    Take elements from an array along an axis.

  `api.extensions.take`

    Take elements from an array.

  Notes

  ExtensionArray.take is called by `Series.__getitem__`, `.loc`, `iloc`, when indices is a sequence of values. Additionally, it’s called by `Series.reindex()`, or any other method that causes realignment, with a fill_value.

  Examples

  Here’s an example implementation, which relies on casting the extension array to object dtype. This uses the helper method `pandas.api.extensions.take()`.

      def take(self, indices, allow_fill=False, fill_value=None):
          from pandas.api.extensions import take

          # If the ExtensionArray is backed by an ndarray, then
          # just pass that here instead of coercing to object.
          data = self.astype(object)

          if allow_fill and fill_value is None:
              fill_value = self.dtype.na_value

          # fill value should always be translated from the scalar
          # type for the array, to the physical storage type for
          # the data, before passing to take.

          result = take(
              data, indices, fill_value=fill_value, allow_fill=allow_fill
          )
          return self._from_sequence(result, dtype=self.dtype)