From dddb85e85351ccb21c3d737eeb3e078ed032d4f4 Mon Sep 17 00:00:00 2001 From: Sietse Brouwer Date: Tue, 5 Dec 2017 21:59:14 +0100 Subject: [PATCH] DOC: explain the `mode.chained_assignment` option --- doc/source/indexing.rst | 22 +++++++++++++++++----- doc/source/options.rst | 6 +++--- 2 files changed, 20 insertions(+), 8 deletions(-) diff --git a/doc/source/indexing.rst b/doc/source/indexing.rst index 2f9f7a04def19..2f3dbb9746066 100644 --- a/doc/source/indexing.rst +++ b/doc/source/indexing.rst @@ -1833,15 +1833,27 @@ that you've done this: Yikes! +.. _indexing.evaluation_order: + Evaluation order matters ~~~~~~~~~~~~~~~~~~~~~~~~ -Furthermore, in chained expressions, the order may determine whether a copy is returned or not. -If an expression will set values on a copy of a slice, then a ``SettingWithCopy`` -warning will be issued. +When you use chained indexing, the order and type of the indexing operation +partially determine whether the result is a slice into the original object, or +a copy of the slice. + +Pandas has the ``SettingWithCopyWarning`` because assigning to a copy of a +slice is frequently not intentional, but a mistake caused by chained indexing +returning a copy where a slice was expected. + +If you would like pandas to be more or less trusting about assignment to a +chained indexing expression, you can set the :ref:`option ` +``mode.chained_assignment`` to one of these values: -You can control the action of a chained assignment via the option ``mode.chained_assignment``, -which can take the values ``['raise','warn',None]``, where showing a warning is the default. +* ``'warn'``, the default, means a ``SettingWithCopyWarning`` is printed. +* ``'raise'`` means pandas will raise a ``SettingWithCopyException`` + you have to deal with. +* ``None`` will suppress the warnings entirely. .. ipython:: python :okwarning: diff --git a/doc/source/options.rst b/doc/source/options.rst index 2da55a5a658a4..bb9663631f4c0 100644 --- a/doc/source/options.rst +++ b/doc/source/options.rst @@ -417,9 +417,9 @@ io.hdf.dropna_table True drop ALL nan rows when appendin io.parquet.engine None The engine to use as a default for parquet reading and writing. If None then try 'pyarrow' and 'fastparquet' -mode.chained_assignment warn Raise an exception, warn, or no - action if trying to use chained - assignment, The default is warn +mode.chained_assignment warn 'raise', 'warn', or None. Raise an + exception, warn, or no action if + trying to use :ref:`chained assignment `. mode.sim_interactive False Whether to simulate interactive mode for purposes of testing. mode.use_inf_as_na False True means treat None, NaN, -INF,