DOC: elaborate on copies vs in place operations in comparison docs (#38994)

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

@@ -65,6 +65,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
+
+
 Data input / output
 -------------------
 

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,23 @@
+Most pandas operations return copies of the ``Series``/``DataFrame``. To make the changes "stick",
+you'll need to either assign to a new variable:
+
+   .. code-block:: python
+
+      sorted_df = df.sort_values("col1")
+
+
+or overwrite the original one:
+
+   .. code-block:: python
+
+      df = df.sort_values("col1")
+
+.. note::
+
+   You will see an ``inplace=True`` keyword argument available for some methods:
+
+   .. code-block:: python
+
+      df.sort_values("col1", inplace=True)
+
+   Its use is discouraged. :ref:`More information. <indexing.view_versus_copy>`