DOC: Distinguish between different types of boolean indexing

[jcjf]

It's not clear from the docs that indexing with a boolean ndarray isn't the same as indexing with a boolean Series. It took me a while to realise that:

import pandas as pd
df = pd.DataFrame([[1, 2], [3, 4], [5, 6]], list('abc'), ['one', 'two'])
sr = (df['one'] > 2)
df.loc[sr, 'two']      # This is ok
df.iloc[sr, 1]         # But this is not
df.iloc[sr.values, 1]  # The right way to use iloc

I've since read through #3631 and it makes sense to me. However, even though the docs emphasise that .iloc is purely integer-based, it didn't click at the time that indexability of Series was the problem I was facing.

[jreback]

the soln in this case would be to

df.ix[sr,1]

which would interpret the 1 as a positional indexer, of course the usual caveats of .ix apply
personally I would do

df.loc[sr, df.columns[1]] to be very explict. More of a matter of taste.

However, would appreciate basically this example in the docs section if you would.

[jreback]

@jcjf pull-request?

[junjunjunk]

If this issue is still open, i'm going to take.
I'll add the following example and prose to https://pandas.pydata.org/pandas-docs/stable/user_guide/indexing.html#boolean-indexing.
Anyone has more improvements or comments, please let me know.

df = pd.DataFrame([[1, 2], [3, 4], [5, 6]], list('abc'), ['column_1', 'column_2'])
sr = (df['column_1'] > 2)
sr

df.loc[sr, df.columns[1]] 

df.iloc[sr.values, 1]

prose:
iloc distinguishes between different types of boolean indexing. If the type of boolean indexing is Series , an error will be raised. For instance, in the above example, df.iloc[sr.values, 1] is ok. This type of boolean indexing is array. But df.iloc[sr, 1]would raise ValueError.

[junjunjunk]

take