diff --git a/doc/source/user_guide/basics.rst b/doc/source/user_guide/basics.rst index 8155aa0ae03fa..d35cc06db9f06 100644 --- a/doc/source/user_guide/basics.rst +++ b/doc/source/user_guide/basics.rst @@ -209,6 +209,10 @@ either match on the *index* or *columns* via the **axis** keyword: df.sub(column, axis="index") df.sub(column, axis=0) +Be careful when using raw Python lists in binary operations with DataFrames. +Unlike NumPy arrays or Series, lists are not broadcast across rows or columns. +Instead, pandas attempts to match the entire list against a single axis, which may lead to confusing results such as Series of arrays. +To ensure proper broadcasting behavior, use a NumPy array or Series with explicit index or shape. Furthermore you can align a level of a MultiIndexed DataFrame with a Series. .. ipython:: python diff --git a/doc/source/user_guide/dsintro.rst b/doc/source/user_guide/dsintro.rst index 89981786d60b5..59938a66bb507 100644 --- a/doc/source/user_guide/dsintro.rst +++ b/doc/source/user_guide/dsintro.rst @@ -650,6 +650,13 @@ row-wise. For example: df - df.iloc[0] +When using a Python list in arithmetic operations with a DataFrame, the behavior is not element-wise broadcasting. +Instead, the list is treated as a single object and the operation is performed column-wise, resulting in unexpected output (e.g. arrays inside each cell). + +.. ipython:: python + + df + np.array([1, 2, 3]) + For explicit control over the matching and broadcasting behavior, see the section on :ref:`flexible binary operations `.