diff --git a/pandas/core/indexing.py b/pandas/core/indexing.py index 3707e141bc447..cf7f337799be7 100644 --- a/pandas/core/indexing.py +++ b/pandas/core/indexing.py @@ -287,6 +287,10 @@ def loc(self) -> _LocIndexer: - An alignable boolean Series. The index of the key will be aligned before masking. - An alignable Index. The Index of the returned selection will be the input. + + .. warning:: Preferred syntax to assign a column: `df[]` instead of + allocation through `df.loc[]` + - A ``callable`` function with one argument (the calling Series or DataFrame) and that returns valid output for indexing (one of the above) @@ -388,6 +392,9 @@ def loc(self) -> _LocIndexer: **Setting values** + .. warning:: Preferred syntax to assign a column: `df['shield']` + instead of allocation through `df.loc[]` such as `df.loc['shield']` + Set value for all items matching the list of labels >>> df.loc[['viper', 'sidewinder'], ['shield']] = 50 @@ -445,6 +452,36 @@ def loc(self) -> _LocIndexer: 8 4 5 9 7 8 + **Setting values using Series** + + Assign column using Series + + >>> df.loc[:, 'shield'] = pd.Series({7: 8, 8: 10, 9: 13}) + >>> df + max_speed shield + 7 1 8 + 8 4 10 + 9 7 13 + + Assigning column to a Series with non matching indexes aligns the + right hand side to the index of the left + + >>> df.loc[:, 'shield'] = pd.Series({8: 10}) + >>> df + max_speed shield + 7 1 NaN + 8 4 10.0 + 9 7 NaN + + Assign column containing value with missing index + + >>> df.loc[:, 'shield'] = pd.Series({11: 14}) + >>> df + max_speed shield + 7 1 NaN + 8 4 NaN + 9 7 NaN + **Getting values with a MultiIndex** A number of examples using a DataFrame with a MultiIndex