DOC: Update Series.map to reflect usage like DataFrame.map

[WillAyd]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

https://pandas.pydata.org/docs/dev/reference/api/pandas.Series.map.html

Documentation problem

If you look at the DataFrame.map documentation it starts with Apply a function to a DataFrame elementwise

https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DataFrame.map.html

Suggested fix for documentation

I think the Series documentation should be more explicit about how it can apply elementwise. @rhshadrach would know best but I am under the impression Series.map(lambda x: return x + 1) should be used in place of the very common Series.apply(lambda x: return x + 1) pattern, so would be good to say something about that too

[rhshadrach]

This sounds good to me, but I'm having a little trouble discerning what you're thinking. In the Series.map API page, there is the example It also accepts a function:. Are you looking for more numeric examples here? They currently use strings. Or maybe just something with lambda or named function more explicitly. Another thought is in the description of arg - Mapping correspondence. could maybe be more fleshed out?

[rhshadrach]

I am under the impression Series.map(lambda x: return x + 1) should be used in place of the very common Series.apply(lambda x: return x + 1) pattern

This is where we were going because of issues like this:

size = 10_000
ser = pd.Series(np.arange(size))

%timeit ser.apply(lambda x: x + 1)
# 1.58 ms ± 7.55 µs per loop (mean ± std. dev. of 7 runs, 1,000 loops each)

%timeit ser.to_frame().apply(lambda x: x + 1)[0]
133 µs ± 203 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)

The idea was to make Series.apply act the same way as DataFrame.apply (always vectorized), and then have Series.map act the same as DataFrame.map (always elementwise). However I believe we've put a hold on proceeding further down this path - at least in the near term - because of objections to Series.apply not acting element-wise.

But at least you can do:

%timeit ser.apply(lambda x: x + 1, by_row=False)
31.5 µs ± 264 ns per loop (mean ± std. dev. of 7 runs, 10,000 loops each)