From 4d689be556bacd58df8128f212869607ac5afaf7 Mon Sep 17 00:00:00 2001 From: Zhenghui Yin Date: Fri, 8 Aug 2025 23:18:04 -0700 Subject: [PATCH 1/4] DOC: clarify Series alignment when assigning to DataFrame column (GH#39845) --- doc/source/user_guide/indexing.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/doc/source/user_guide/indexing.rst b/doc/source/user_guide/indexing.rst index ebd1791c0f4ad..b8673dcdf3adc 100644 --- a/doc/source/user_guide/indexing.rst +++ b/doc/source/user_guide/indexing.rst @@ -766,6 +766,26 @@ This is like an ``append`` operation on the ``DataFrame``. dfi.loc[3] = 5 dfi +When assigning a :class:`Series` to a column, values are **aligned on index labels**. +The order of the ``Series`` does not matter. Labels not present in the +``DataFrame`` index result in ``NaN``. + +.. ipython:: python + + import pandas as pd + + df = pd.DataFrame({"a": [1, 2, 3]}) + df + + # assigning a partial Series aligns by index; other rows become NaN + df["b"] = pd.Series({1: "b"}) + df + + # order of the Series is irrelevant; labels drive the alignment + s = pd.Series({2: "zero", 1: "one", 0: "two"}) + df["c"] = s + df + .. _indexing.basics.get_value: Fast scalar value getting and setting From 8ebfaf3d2a6849c7cac04d839aea2aa4dc740b54 Mon Sep 17 00:00:00 2001 From: Zhenghui Yin Date: Sat, 9 Aug 2025 00:25:32 -0700 Subject: [PATCH 2/4] Fix doc check issue --- doc/source/user_guide/indexing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/user_guide/indexing.rst b/doc/source/user_guide/indexing.rst index b8673dcdf3adc..b5fdc9f697651 100644 --- a/doc/source/user_guide/indexing.rst +++ b/doc/source/user_guide/indexing.rst @@ -766,7 +766,7 @@ This is like an ``append`` operation on the ``DataFrame``. dfi.loc[3] = 5 dfi -When assigning a :class:`Series` to a column, values are **aligned on index labels**. +When assigning a :class:`pandas.Series` to a column, values are **aligned on index labels**. The order of the ``Series`` does not matter. Labels not present in the ``DataFrame`` index result in ``NaN``. From c5cff84dde099e46602a2fef0a1eb877fc072998 Mon Sep 17 00:00:00 2001 From: Zhenghui Yin Date: Sat, 9 Aug 2025 01:04:58 -0700 Subject: [PATCH 3/4] Update indexing.rst --- doc/source/user_guide/indexing.rst | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/doc/source/user_guide/indexing.rst b/doc/source/user_guide/indexing.rst index ebd1791c0f4ad..c7809248b8324 100644 --- a/doc/source/user_guide/indexing.rst +++ b/doc/source/user_guide/indexing.rst @@ -1751,30 +1751,40 @@ Key Points: * This behavior is consistent across df[col] = series and df.loc[:, col] = series Examples: -.. ipython:: python +~~~~~~~~~ - import pandas as pd +.. ipython:: python # Create a DataFrame df = pd.DataFrame({'values': [1, 2, 3]}, index=['x', 'y', 'z']) + df # Series with matching indices (different order) s1 = pd.Series([10, 20, 30], index=['z', 'x', 'y']) df['aligned'] = s1 # Aligns by index, not position - print(df) + df # Series with partial index match s2 = pd.Series([100, 200], index=['x', 'z']) df['partial'] = s2 # Missing 'y' gets NaN - print(df) + df # Series with non-matching indices s3 = pd.Series([1000, 2000], index=['a', 'b']) df['nomatch'] = s3 # All values become NaN - print(df) + df +Avoiding Confusion: +~~~~~~~~~~~~~~~~~~~ - #Avoiding Confusion: - #If you want positional assignment instead of index alignment: - # reset the Series index to match DataFrame index - df['s1_values'] = s1.reindex(df.index) +If you want positional assignment instead of index alignment: + +.. ipython:: python + + # Use .values or .to_numpy() to assign by position + df['position_based'] = s1.values[:len(df)] + df + + # Or align the Series to the DataFrame's index first + df['reindexed'] = s1.reindex(df.index) + df From 1f71fdeb0be6b0eabbfa5141693f7f8b22a071bc Mon Sep 17 00:00:00 2001 From: Zhenghui Yin Date: Sat, 9 Aug 2025 01:59:51 -0700 Subject: [PATCH 4/4] Delete old version --- doc/source/user_guide/indexing.rst | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/doc/source/user_guide/indexing.rst b/doc/source/user_guide/indexing.rst index 586c320104797..c7809248b8324 100644 --- a/doc/source/user_guide/indexing.rst +++ b/doc/source/user_guide/indexing.rst @@ -766,26 +766,6 @@ This is like an ``append`` operation on the ``DataFrame``. dfi.loc[3] = 5 dfi -When assigning a :class:`pandas.Series` to a column, values are **aligned on index labels**. -The order of the ``Series`` does not matter. Labels not present in the -``DataFrame`` index result in ``NaN``. - -.. ipython:: python - - import pandas as pd - - df = pd.DataFrame({"a": [1, 2, 3]}) - df - - # assigning a partial Series aligns by index; other rows become NaN - df["b"] = pd.Series({1: "b"}) - df - - # order of the Series is irrelevant; labels drive the alignment - s = pd.Series({2: "zero", 1: "one", 0: "two"}) - df["c"] = s - df - .. _indexing.basics.get_value: Fast scalar value getting and setting