DataFrame.apply documentation needs upgrade

[tdpetrou]

Problem description

I believe the only place that apply is mentioned in detail in the documentation is in the essential basic functionality.

All the examples do not need apply, and can be done quicker with other methods. In fact, they actively teach how not to use pandas correctly. For instance, idxmax and interploate are both dataframe methods and from the documentation, they appear to be good use-cases for apply, which they are not.

Expected Output

I understand that it makes sense to use basic examples to motivate apply. But there should be some useful examples where apply is necessary.

Most of the examples should be replaced (or shown how to be duplicated with more idiomatic methods).

[jreback]

pls be more specific here.

[jreback]

further in master .apply has gained some examples (to the doc-string).

[tdpetrou]

I know you dislike apply like myself. I gave a tutorial on how to avoid apply by vectorizing it in my idiomatic pandas talk at pydata nyc. I used the poor examples from the documentation during the tutorial. This is one of early pandas users largest mistakes - using apply when it's not necessary.

I think it's probably OK to have a couple basic examples of using it when it's not necessary to teach the mechanics but after that, it should be followed with the idiomatic vectorized version.

You could have a simple set of rules when it is considered OK to use apply.

• for a Series - use it only when no pandas Series method exists (like the built-in type function)
• for a DataFrame - use it when a Series method exists but not a DataFrame method (like value_counts or the accessors (str, dt, and cat). Or other complex functions from other libraries like finding the edit distance.

[jreback]

sure all for a warning box
example of what folks do and what some better solns are

[tdpetrou]

Ok cool. I'll make some changes to the apply docs in the next few days.

[jreback]

some related .apply doc issues (depending on what is written, some of these may be closable)

#3928
#5299