DOC: rewrite missing value includes to not require replacement

Author: afeld

doc/source/getting_started/comparison/comparison_with_sas.rst

@@ -422,6 +422,8 @@ input frames.
 Missing data
 ------------
 
+Both pandas and SAS have a representation for missing data.
+
 .. include:: includes/missing_intro.rst
 
 One difference is that missing data cannot be compared to its sentinel value.
@@ -441,8 +443,6 @@ For example, in SAS you could do this to filter missing values.
 
 .. include:: includes/missing.rst
 
-.. |program| replace:: SAS
-
 
 GroupBy
 -------

doc/source/getting_started/comparison/comparison_with_stata.rst

@@ -413,6 +413,8 @@ or the intersection of the two by using the values created in the
 Missing data
 ------------
 
+Both pandas and State have a representation for missing data.
+
 .. include:: includes/missing_intro.rst
 
 One difference is that missing data cannot be compared to its sentinel value.
@@ -427,8 +429,6 @@ For example, in Stata you could do this to filter missing values.
 
 .. include:: includes/missing.rst
 
-.. |program| replace:: Stata
-
 
 GroupBy
 -------

doc/source/getting_started/comparison/includes/missing.rst

@@ -1,23 +1,31 @@
-This doesn't work in pandas.  Instead, the :func:`pd.isna` or :func:`pd.notna` functions
-should be used for comparisons.
+In pandas, :meth:`Series.isna` and :meth:`Series.notna` can be used to filter the rows.
 
 .. ipython:: python
 
-   outer_join[pd.isna(outer_join["value_x"])]
-   outer_join[pd.notna(outer_join["value_x"])]
+   outer_join[outer_join["value_x"].isna()]
+   outer_join[outer_join["value_x"].notna()]
 
-pandas also provides a variety of methods to work with missing data -- some of which would be
-challenging to express in |program|. For example, there are methods to drop all rows with any
-missing values, replacing missing values with a specified value, like the mean, or forward filling
-from previous rows. See the :ref:`missing data documentation<missing_data>` for more.
+pandas provides :ref:`a variety of methods to work with missing data <missing_data>`. Here are some examples:
+
+Drop rows with missing values
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. ipython:: python
 
-   # Drop rows with any missing value
    outer_join.dropna()
 
-   # Fill forwards
+Forward fill from previous rows
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. ipython:: python
+
    outer_join.fillna(method="ffill")
 
-   # Impute missing values with the mean
+Replace missing values with a specified value
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Using the mean:
+
+.. ipython:: python
+
    outer_join["value_x"].fillna(outer_join["value_x"].mean())

doc/source/getting_started/comparison/includes/missing_intro.rst

@@ -1,6 +1,6 @@
-Both pandas and |program| have a representation for missing data — pandas' is the special float
-value ``NaN`` (not a number).  Many of the semantics are the same; for example missing data
-propagates through numeric operations, and is ignored by default for aggregations.
+pandas represents missing data with the special float value ``NaN`` (not a number).  Many of the
+semantics are the same; for example missing data propagates through numeric operations, and is
+ignored by default for aggregations.
 
 .. ipython:: python