Skip to content

DOC: Fixed the doctsring for _set_axis_name (GH 22895) #22969

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.

Sign up for GitHub

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

Merged
merged 15 commits into from
Nov 20, 2018
Merged

DOC: Fixed the doctsring for _set_axis_name (GH 22895) #22969

Changes from 4 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
a5fd1c3
DOC: Fixed the doctsring for _set_axis_name (GH 22895)
bkjchoi72 Oct 3, 2018
5dbbbd1
Added a new line after the first triple quotes
bkjchoi72 Oct 5, 2018
bc865d4
Removed the new line after the first triple quotes
bkjchoi72 Oct 5, 2018
457c58e
Merge branch 'master' into GH22895_fix_docstring_for_set_axis_name
bkjchoi72 Oct 5, 2018
e469e4e
Merge branch 'master' into GH22895_fix_docstring_for_set_axis_name
bkjchoi72 Oct 8, 2018
7fb8a52
Merge branch 'master' into GH22895_fix_docstring_for_set_axis_name
bkjchoi72 Oct 9, 2018
067fa8d
Modified the description of parameters. Changed the example to animals.
bkjchoi72 Oct 9, 2018
71f3909
Modified the example for DataFrame.rename_axis()
bkjchoi72 Oct 9, 2018
a7eb3d8
Changed the example so that it makes sense
bkjchoi72 Oct 9, 2018
96a5dd1
Fixed the indentation and changed the word "alter" to "set" where app…
bkjchoi72 Oct 10, 2018
22ef507
Merge branch 'master' into GH22895_fix_docstring_for_set_axis_name
bkjchoi72 Oct 10, 2018
b030a6b
Fixed failing docstring test
bkjchoi72 Oct 11, 2018
6d76d44
Merge branch 'master' into GH22895_fix_docstring_for_set_axis_name
bkjchoi72 Oct 11, 2018
adc2694
Adjusted indentation
bkjchoi72 Oct 11, 2018
9d944e8
Merging from master and fixing validation issues in the rename_axis d…
datapythonista Nov 19, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 14 additions & 10 deletions pandas/core/generic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1194,31 +1194,35 @@ def rename_axis(self, mapper, axis=0, copy=True, inplace=False):

def _set_axis_name(self, name, axis=0, inplace=False):
"""
Alter the name or names of the axis.
Alter the label(s) of the axis.
Copy link
Member

@datapythonista datapythonista Oct 9, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This doesn't seem correct. Altering the labels would be changing the names of the columns, not the name of the axis itself.

And small thing, but alter doesn't necessarily need to be correct. If the axis doesn't have a name, it's setting it, but not altering. Set would be better I think.


Parameters
----------
name : str or list of str
Name for the Index, or list of names for the MultiIndex
axis : int or str
0 or 'index' for the index; 1 or 'columns' for the columns
inplace : bool
whether to modify `self` directly or return a copy
Labels(s) to set.
Copy link
Member

@datapythonista datapythonista Oct 9, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as before, label is the names of each individual column, not the name of the axis

axis : int or str, default 0
The axis to set the label. The value 0 or 'index' specifies index,
and the value 1 or 'columns' specifies columns.
inplace : bool, default False
Whether to modify `self` directly or return a copy.
Copy link
Contributor

@jreback jreback Oct 7, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

see what we use elsewhere for this

Copy link
Contributor Author

@bkjchoi72 bkjchoi72 Oct 9, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There isn't great consistency for the description of inplace parameter. The most common and easy to understand I found is If True, do operation inplace and return None. I'll go with that one, and I'll change bool to boolean.


.. versionadded:: 0.21.0

Returns
-------
renamed : same type as caller or None if inplace=True
Series, DataFrame, Panel, or None
Copy link
Member

@datapythonista datapythonista Oct 9, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you remove Panel here. While it's correct, Panel it's already deprecated and will disappear in couple of months, so not worth having it.

The same type as the caller or `None` if `inplace` is `True`.

See Also
--------
pandas.DataFrame.rename
pandas.Series.rename
pandas.Index.rename
pandas.DataFrame.rename : Alter the labels of :class:`DataFrame`.
pandas.Series.rename : Alter the name or the labels :class:`Series`.
pandas.Index.rename : Alter the name of :class:`Index`
or :class:`MultiIndex`.

Examples
--------
>>> df = pd.DataFrame({"A": [1, 2, 3]})
Copy link
Member

@datapythonista datapythonista Oct 8, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for updating the docstring @bkjchoi72, looking much better now, and it fixes the doctest, which was the main goal. Just one comment that would make this docstring even better, besides the comments in the previous review.

Do you mind adding a more real-world example? I know it's the original example, not yours, but setting the axis name to foo doesn't give a good idea of that the axis name is.

We use examples in the code with names of animals, and some property like the number of legs. Could you do something like that, and set the axis to animals or the meaningful name for the example?

If you can also change that in DataFrame.rename_axis() too, which has a example with foo as well, that would be great.

Copy link
Contributor Author

@bkjchoi72 bkjchoi72 Oct 9, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion. I'll make those changes.

>>> df._set_axis_name("foo")
Copy link
Contributor

@jreback jreback Oct 7, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

can you show what the current axis name is prior to setting it.

A
foo
Expand Down