From 2522866eeefe5a3a31d25c70a9455cf805c7d7bf Mon Sep 17 00:00:00 2001 From: Aidan Feldman Date: Wed, 6 Jan 2021 00:00:57 -0500 Subject: [PATCH 1/2] DOC: elaborate on copies vs in place operations in comparison docs --- .../comparison/comparison_with_sas.rst | 6 ++++++ .../comparison_with_spreadsheets.rst | 7 +++++++ .../comparison/comparison_with_sql.rst | 7 +++++++ .../comparison/comparison_with_stata.rst | 6 ++++++ .../comparison/includes/column_selection.rst | 3 +-- .../comparison/includes/copies.rst | 20 +++++++++++++++++++ 6 files changed, 47 insertions(+), 2 deletions(-) create mode 100644 doc/source/getting_started/comparison/includes/copies.rst diff --git a/doc/source/getting_started/comparison/comparison_with_sas.rst b/doc/source/getting_started/comparison/comparison_with_sas.rst index 2b316cccb7fc9..54b45dc20db20 100644 --- a/doc/source/getting_started/comparison/comparison_with_sas.rst +++ b/doc/source/getting_started/comparison/comparison_with_sas.rst @@ -62,6 +62,12 @@ see the :ref:`indexing documentation` for much more on how to use an ``Index`` effectively. +Copies vs. in place operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: includes/copies.rst + + Data input / output ------------------- diff --git a/doc/source/getting_started/comparison/comparison_with_spreadsheets.rst b/doc/source/getting_started/comparison/comparison_with_spreadsheets.rst index e9d687bc07999..c92d2a660d753 100644 --- a/doc/source/getting_started/comparison/comparison_with_spreadsheets.rst +++ b/doc/source/getting_started/comparison/comparison_with_spreadsheets.rst @@ -65,6 +65,13 @@ particular row don't change. See the :ref:`indexing documentation` for much more on how to use an ``Index`` effectively. + +Copies vs. in place operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: includes/copies.rst + + Data input / output ------------------- diff --git a/doc/source/getting_started/comparison/comparison_with_sql.rst b/doc/source/getting_started/comparison/comparison_with_sql.rst index 890f0cbe50424..fcfa03a8bce5f 100644 --- a/doc/source/getting_started/comparison/comparison_with_sql.rst +++ b/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 ``*`` diff --git a/doc/source/getting_started/comparison/comparison_with_stata.rst b/doc/source/getting_started/comparison/comparison_with_stata.rst index 43cb775b5461d..94c45adcccc82 100644 --- a/doc/source/getting_started/comparison/comparison_with_stata.rst +++ b/doc/source/getting_started/comparison/comparison_with_stata.rst @@ -61,6 +61,12 @@ see the :ref:`indexing documentation` for much more on how to use an ``Index`` effectively. +Copies vs. in place operations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. include:: includes/copies.rst + + Data input / output ------------------- diff --git a/doc/source/getting_started/comparison/includes/column_selection.rst b/doc/source/getting_started/comparison/includes/column_selection.rst index b925af1294f54..071645c9718cb 100644 --- a/doc/source/getting_started/comparison/includes/column_selection.rst +++ b/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 '''''''''''''''''''' diff --git a/doc/source/getting_started/comparison/includes/copies.rst b/doc/source/getting_started/comparison/includes/copies.rst new file mode 100644 index 0000000000000..1d6211209705f --- /dev/null +++ b/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) From 0ff288cf3dfea172d7d67c71d1efb99e3a7a60e6 Mon Sep 17 00:00:00 2001 From: Aidan Feldman Date: Fri, 8 Jan 2021 06:31:15 +0000 Subject: [PATCH 2/2] DOC: discourage use of inplace=True in comparion pages --- .../comparison/includes/copies.rst | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/doc/source/getting_started/comparison/includes/copies.rst b/doc/source/getting_started/comparison/includes/copies.rst index 1d6211209705f..08ccd47624932 100644 --- a/doc/source/getting_started/comparison/includes/copies.rst +++ b/doc/source/getting_started/comparison/includes/copies.rst @@ -1,20 +1,23 @@ 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 +you'll need to either assign to a new variable: .. code-block:: python - df = df.sort_values("col1") + sorted_df = df.sort_values("col1") + -* Assign to a new variable +or overwrite the original one: .. code-block:: python - sorted_df = df.sort_values("col1") + df = df.sort_values("col1") -* Use the ``inplace=True`` keyword argument, where available +.. 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. `