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..c635d9157f557 100644 --- a/doc/source/user_guide/dsintro.rst +++ b/doc/source/user_guide/dsintro.rst @@ -650,6 +650,19 @@ 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 = pd.DataFrame(np.arange(6).reshape(2, 3), columns=["A", "B", "C"]) + + df + [1, 2, 3] # Returns a Series of arrays, not a DataFrame + + df + np.array([1, 2, 3]) # Correct broadcasting + + df + pd.Series([1, 2, 3], index=["A", "B", "C"]) # Also correct + For explicit control over the matching and broadcasting behavior, see the section on :ref:`flexible binary operations `.