DOC: Indexing and selecting data and the use of mask/where

[psteinb]

Location of the documentation

https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#evaluation-order-matters

Documentation problem

The documentation talks about how not to use dfb['c'][dfb['a'].str.startswith('o')] = 42 for assignment of multiple values to a pandas.Series or pandas.DataFrame column. it does however fail to make a concrete suggestion how to do it given the example.

Suggested fix for documentation

I suggest to mention the pandas.Series.where and pandas.Series.mask methods here in order to show how the assignment can be done, i.e. by adding an example like:

dfb['c'].mask(dfb['a'].str.startswith('o'), 42)

which performs the desired assigment of rows matching o to 42. I am happy to contribute this as a PR myself.

[TomAugspurger]

We do have suggestions starting with "This is the correct access method:" though. Does that suffice?

If you're looking to provide a recommendation for this specific example then I'd recommend

mask = dfb['a'].str.startswith('o')

df.loc[mask, 'c'] = 42

I think that using .loc is more common than .mask. We'd welcome a PR with that.

[psteinb]

Indeed, I see "This is the correct access method:", but the example that follows does a single-item assignment that the previous example doesn't exhibit. This leaves learners out in the open and wandering off to stackoverflow. My suggestion is to fix that.

I'm happy to contribute the df.loc[mask, 'c'] = 42 inspired example as you recommend. I don't endorse this API too much, but that is more a matter of taste and being a newbie with pandas. PR incoming.