Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: default axis is unspecified for DataFrame (and even some Series) operations #48561

Open
1 task done
toobaz opened this issue Sep 15, 2022 · 1 comment
Open
1 task done
Labels
Docs Needs Triage Issue that has not been reviewed by a pandas team member

Comments

@toobaz
Copy link
Member

toobaz commented Sep 15, 2022

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/reference/api/pandas.DataFrame.max.html

Documentation problem

The docs for pd.DataFrame.max() state, about the axis argument:

axis{index (0), columns (1)}

    Axis for the function to be applied on.

The docs for pd.DataFrame.std() don't even include the explanatory sentence.

Instead, the docs for pd.DataFrame.cummin() have

axis{0 or ‘index’, 1 or ‘columns’}, default 0

    The index or the name of the axis. 0 is equivalent to None or ‘index’.

... which I think is good (also notice the more understandable explanation of the equivalence between numbers and descriptions), except that the default in the signature is None, not 0, and that I would replace the last sentence with None is equivalent to 0 or index.

Suggested fix for documentation

Simplest solution: specify, in all these signatures, that default: None and that None corresponds to 0 (see above for cummin()).

My preferred solution, set the default to 0 (rather than None), specify that default 0, start deprecating None (which is likely not used anywhere anyway). But given that the current max() signature states axis=NoDefault.no_default, which I don't know the meaning of, maybe there is something I am missing? Still, the signature for std() looks similar except that axis=None (the axis docs still provide no default), and conceptually the kind of requested data manipulation is similar...

@toobaz toobaz added Docs Needs Triage Issue that has not been reviewed by a pandas team member labels Sep 15, 2022
@toobaz
Copy link
Member Author

toobaz commented Sep 15, 2022

I'm happy to provide a PR once we pick the preferred solution.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Docs Needs Triage Issue that has not been reviewed by a pandas team member
Projects
None yet
Development

No branches or pull requests

1 participant