DOC: Integer NA

Closes pandas-dev#22003

Author: TomAugspurger

doc/source/basics.rst

@@ -84,7 +84,10 @@ unlike the axis labels, cannot be assigned to.
     When working with heterogeneous data, the dtype of the resulting ndarray
     will be chosen to accommodate all of the data involved. For example, if
     strings are involved, the result will be of object dtype. If there are only
-    floats and integers, the resulting array will be of float dtype.
+    floats and integers, the resulting array will be of float dtype. If you
+    need to store an integer column with missing data, use one of the "Int"
+    dtypes (``"Int8"``, ``"Int16"``, ``"Int32"``, ``"Int64"``). See
+    :ref:`integer_na` for more.
 
 .. _basics.accelerate:
 

doc/source/gotchas.rst

@@ -228,8 +228,17 @@ arrays. For example:
    s2.dtype
 
 This trade-off is made largely for memory and performance reasons, and also so
-that the resulting ``Series`` continues to be "numeric". One possibility is to 
-use ``dtype=object`` arrays instead.
+that the resulting ``Series`` continues to be "numeric".
+
+If you need to represent integers with possibly missing values, use one of
+the ``"Int"`` dtypes provided by pandas
+
+* :class:`Int8Dtype`
+* :class:`Int16Dtype`
+* :class:`Int32Dtype`
+* :class:`Int64Dtype`
+
+See :ref:`integer_na` for more.
 
 ``NA`` type promotions
 ~~~~~~~~~~~~~~~~~~~~~~

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: