DOC: Integer NA

Closes pandas-dev#22003

Author: TomAugspurger

doc/source/integer_na.rst

@@ -8,27 +8,33 @@
 
  .. _integer_na:
 
-********************************
-Integer Data with Missing Values
-********************************
+**************************
+Nullable Integer Data Type
+**************************
 
 .. versionadded:: 0.24.0
 
-In :ref:`missing_data`, we say that pandas primarily uses ``NaN`` to represent
+In :ref:`missing_data`, we saw that pandas primarily uses ``NaN`` to represent
 missing data. Because ``NaN`` is a float, this forces an array of integers with
 any missing values to become floating point. In some cases, this may not matter
 much. But if your integer column is, say, and identifier, casting to float can
-lead to bad outcomes.
+be problematic.
 
 Pandas can represent integer data with missing values with the
 :class:`arrays.IntegerArray` array. This is an :ref:`extension types <extending.extension-types>`
-implemented within pandas. It is not the default dtype and will not be inferred,
-you must explicitly create an :class:`api.extensions.IntegerArray` using :func:`integer_array`.
+implemented within pandas. It is not the default dtype for integers, and will not be inferred;
+you must explicitly pass the dtype into the :meth:`array` or :class:`Series` method:
 
 .. ipython:: python
 
-   arr = integer_array([1, 2, np.nan])
-   arr
+   pd.array([1, 2, np.nan], dtype=pd.Int64Dtype())
+
+Or the string alias "Int64" (note the capital ``"I"``, to differentiate from
+NumPy's ``'int64'`` dtype:
+
+.. ipython:: python
+
+   pd.array([1, 2, np.nan], dtype="Int64")
 
 This array can be stored in a :class:`DataFrame` or :class:`Series` like any
 NumPy array.
@@ -37,22 +43,21 @@ NumPy array.
 
    pd.Series(arr)
 
-Alternatively, you can instruct pandas to treat an array-like as an
-:class:`api.extensions.IntegerArray` by specifying a dtype with a capital "I".
+You can also pass the list-like object to the :class:`Series` constructor
+with the dtype.
 
 .. ipython:: python
 
    s = pd.Series([1, 2, np.nan], dtype="Int64")
    s
 
-Note that by default (if you don't specify `dtype`), NumPy is used, and you'll end
+By default (if you don't specify ``dtype``), NumPy is used, and you'll end
 up with a ``float64`` dtype Series:
 
 .. ipython:: python
 
    pd.Series([1, 2, np.nan])
 
-
 Operations involving an integer array will behave similar to NumPy arrays.
 Missing values will be propagated, and and the data will be coerced to another
 dtype if needed.

doc/source/missing_data.rst

@@ -760,3 +760,19 @@ However, these can be filled in using :meth:`~DataFrame.fillna` and it will work
 
    reindexed[crit.fillna(False)]
    reindexed[crit.fillna(True)]
+
+Pandas provides a nullable integer dtype, but you must explicitly request it
+when creating the series or column. Notice that we use a capital "I" in
+the ``dtype="Int64"``.
+
+.. ipython:: python
+
+   s = pd.Series(np.random.randn(5), index=[0, 2, 4, 6, 7],
+                 dtype="Int64")
+   s > 0
+   (s > 0).dtype
+   crit = (s > 0).reindex(list(range(8)))
+   crit
+   crit.dtype
+
+See :ref:`integer_na` for more.

doc/source/whatsnew/v0.24.0.txt

@@ -99,7 +99,9 @@ Reduction and groupby operations such as 'sum' work.
 
 .. warning::
 
-   The Integer NA support currently uses the captilized dtype version, e.g. ``Int8`` as compared to the traditional ``int8``. This may be changed at a future date.
+   The Integer NA support currently uses the capitalized dtype version, e.g. ``Int8`` as compared to the traditional ``int8``. This may be changed at a future date.
+
+See :ref:`integer_na` for more.
 
 .. _whatsnew_0240.enhancements.read_html: