DOC: elaborate on copies vs in place operations in comparison docs

Author: afeld

doc/source/getting_started/comparison/comparison_with_sas.rst

@@ -62,6 +62,12 @@ see the :ref:`indexing documentation<indexing>` for much more on how to use an
 ``Index`` effectively.
 
 
+Copies vs. in place operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: includes/copies.rst
+
+
 Data input / output
 -------------------
 

doc/source/getting_started/comparison/comparison_with_spreadsheets.rst

@@ -62,6 +62,13 @@ particular row don't change.
 See the :ref:`indexing documentation<indexing>` for much more on how to use an ``Index``
 effectively.
 
+
+Copies vs. in place operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: includes/copies.rst
+
+
 Commonly used spreadsheet functionalities
 -----------------------------------------
 

doc/source/getting_started/comparison/comparison_with_sql.rst

@@ -23,6 +23,13 @@ structure.
     tips = pd.read_csv(url)
     tips
 
+
+Copies vs. in place operations
+------------------------------
+
+.. include:: includes/copies.rst
+
+
 SELECT
 ------
 In SQL, selection is done using a comma-separated list of columns you'd like to select (or a ``*``

doc/source/getting_started/comparison/comparison_with_stata.rst

@@ -61,6 +61,12 @@ see the :ref:`indexing documentation<indexing>` for much more on how to use an
 ``Index`` effectively.
 
 
+Copies vs. in place operations
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: includes/copies.rst
+
+
 Data input / output
 -------------------
 

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

@@ -1,5 +1,4 @@
-The same operations are expressed in pandas below. Note that these operations do not happen in
-place. To make these changes persist, assign the operation back to a variable.
+The same operations are expressed in pandas below.
 
 Keep certain columns
 ''''''''''''''''''''

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

@@ -0,0 +1,20 @@
+Most pandas operations return copies of the ``Series``/``DataFrame``. To make the changes "stick",
+you'll need to either:
+
+* Assign back to the same variable
+
+   .. code-block:: python
+
+      df = df.sort_values("col1")
+
+* Assign to a new variable
+
+   .. code-block:: python
+
+      sorted_df = df.sort_values("col1")
+
+* Use the ``inplace=True`` keyword argument, where available
+
+   .. code-block:: python
+
+      df.sort_values("col1", inplace=True)