ENH/API: Scalar values for Series.rename and NDFrame.rename_axis #11980

TomAugspurger · 2016-01-07T04:57:47Z

closes #9494
closes #11965

Okay refactored to overload NDFrame.rename and NDFrame.rename_axis

New rules:

Series.rename(scalar) or Series.rename(list-like) will alter Series.name
NDFrame.rename(mapping) and NDFrame.rename(function) operate as before (alter labels)
NDFrame.rename_axis(scaler) or NDFrame.rename_axis(list-like) will change the Index.name or MutliIndex.names
NDFrame.rename_axis(mapping) and NDFrame.rename_axis(function) operate as before.

I don't like overloading the method like this, but rename and rename_axis are the right method names. It's mostly backwards compatible, aside from people doing things like try: series.rename(x): except TypeError: ... and I don't know what our guarantees are around things like that.

jreback · 2016-01-07T12:39:46Z

doc/source/api.rst

@@ -367,6 +367,7 @@ Reindexing / Selection / Label manipulation
   Series.reindex
   Series.reindex_like
   Series.rename
+   Series.set_axis_name
   Series.reset_index


add .set_name

jreback · 2016-01-07T12:46:27Z

I would add an example (like this)

maybe in the data structures section.

shoyer · 2016-01-07T17:26:52Z

Do we need an inplace argument for these new methods at all? You can already just mutate the index directly if you want to do that.

TomAugspurger · 2016-01-07T17:37:29Z

OK, removing inplace.

Thoughts on pd.Series.rename(scalar) changing the Series name, and NDFrame.rename_axis(scalar/list-like) changing the axis name(s)? Those methods will keep their behavior for mappings / function inputs IIUC this is what xray does?

jreback · 2016-01-07T17:42:30Z

that would be quite an API change

TomAugspurger · 2016-01-07T17:44:47Z

I think it'd be backwards compatible right? Right now we raise a TypeError on scalars / array-likes. I'll writeup an example later.

TomAugspurger · 2016-01-09T16:10:09Z

pandas/core/generic.py

+        """
+        is_scalar_or_list = (
+            (not com.is_sequence(mapper) and not callable(mapper)) or
+            (com.is_list_like(mapper) and not isinstance(mapper,


Do we have a check for is_dict_like in core/common? I couldn't find one, and can move this or something similar into there if you want.

I would add a is_dict_like and just make it a check for https://docs.python.org/2/library/collections.html#collections.MutableMapping

Better to use duck typing -- for example, I'm pretty sure Series would fail that test :).

I wrote one of these for xarray: https://github.com/pydata/xarray/blob/v0.7.0/xarray/core/utils.py#L137

I find is_list_like & co ambiguous, because I don't know if list means to me what it means to the person who wrote it. the function name should describe the properties being tested for (e.g. is_immuatable_sequence rather than is_tuple_like). #12056 is properly the place to discuss that.

TomAugspurger · 2016-01-09T18:57:08Z

FYI, changed the API around, see the updated original post, which makes it more like xray

Basically we look at the type of the argument. For dict/functions we alter labels as before. For scalar/list-like we alter Series/index name(s).

jorisvandenbossche · 2016-01-09T19:14:42Z

Question: what would be the ideal name for the original functionality (i.e. changing the column names/index labels) if we could choose it know? Would that be something else as rename?

If we think of something really better, we could also opt to add that as a method, and at least use two different functions in the documentation for these two different operation that we can recommend to use (kind of soft deprecation)

jorisvandenbossche · 2016-01-09T19:18:05Z

Further, one drawback of the overloading of rename, is that you cannot rename a certain level of a MultiIndex using a mapping like {'original_level_name': 'new_level_name'} (instead of having to specify the level you want to rename with level=..)

TomAugspurger · 2016-01-09T19:27:49Z

what would be the ideal name for the original functionality

relabel I think.

And you're correct not being able to rename a single level of a MultiIndex; you'd have to specify all the levels, even the ones you aren't changing.. We could potentially add a level argument rename, but I think that's more confusion than it's worth and I didn't want to change the signature at all.

jreback · 2016-01-09T21:02:49Z

note #4160 for long time bug in renaming MultiIndex

jreback · 2016-02-09T22:28:56Z

pandas/core/common.py

+    Determin whether ``arg`` is dict-like.
+    '''
+    return hasattr(arg, '__getitem__') and hasattr(arg, 'keys')
+


does this work for py3 dictviews? (maybe add a confirming tests in test_common.py)

Not quite sure what you mean. IIUC the only dictviews are (python3) dict.keys(), .items() and .values(), none of which are dict like.

Overloading the APIs of Series.rename and NDFramed.rename_axis for method chaining.

TomAugspurger · 2016-02-11T01:55:06Z

@jreback could you expand a bit on what you mean by dictviews? I don't think that dict.keys() / dict.values() / dict.itms()

And on the docstrings, I don't think there's a way to only show certain examples for Series and others for DataFrames, is there? We have other docstrings showing both. I did have add an example with DataFrame.rename(scalar) raising a TypeError.

Other than those I think this is ready. The 2.7 build failed while building the docs because the xarray docstring you fixed in 4404d39

jreback · 2016-02-11T02:37:45Z

@TomAugspurger nvm, was thinking of handling the actual keys which are dict_keys IOW, views. but that is not what you are doing.

TomAugspurger · 2016-02-11T02:42:30Z

Ok, thanks!

jreback · 2016-02-11T02:43:43Z

side issue: we might want to revisit the signature of .rename & .reindex to be more like

.rename(values, axis) more in-line with other methods I think.

e.g.

.rename(lambda x: str(x), axis=1) rather than .rename(columns=lambda x: str(x))
.reindex(values, axis=1) rather than .reindex(columns=values)

TomAugspurger · 2016-02-11T02:51:20Z

Think that's worth breaking API for?

With rename we at least have rename_axis. Could point users to that if you want.

At the very least, it's nice that these two methods are at least similar to eachother. They're both for altering the axis labels, and they both take index=, columns-

jreback · 2016-02-11T03:03:32Z

actually we also have .reindex_axis so I guess .rename/.reindex are the axis-less ones....

closes pandas-dev#9494 closes pandas-dev#11965 Okay refactored to overload `NDFrame.rename` and `NDFrame.rename_axis` New rules: - Series.rename(scalar) or Series.rename(list-like) will alter `Series.name` - NDFrame.rename(mapping) and NDFrame.rename(function) operate as before (alter labels) - NDFrame.rename_axis(scaler) or NDFrame.rename_axis(list-like) will change the Index.name or MutliIndex.names - NDFrame.rename_axis(mapping) and NDFrame.rename_axis(function) operate as before. I don't like overloading the method like this, but `rename` and `rename_axis` are the right method names. It's *mostly* backwards compatible, aside from people doing things like `try: series.rename(x): except TypeError: ...` and I don't know what our guarantees are around things like that. Author: Tom Augspurger <tom.w.augspurger@gmail.com> Closes pandas-dev#11980 from TomAugspurger/chainable-rename and squashes the following commits: b36df76 [Tom Augspurger] ENH/API: Series.rename and NDFrame.rename_axis

Closes pandas-dev#12623 I added com.is_dict_like in pandas-dev#11980 and failed to use it for the `rename` method. Using that now and did some refactoring while I was in there. Added more tests for rename.

closes #12623 closes #12626 I added com.is_dict_like in #11980 and failed to use it for the `rename` method. Using that now and did some refactoring while I was in there. Added more tests for rename.

TomAugspurger added the API Design label Jan 7, 2016

TomAugspurger added this to the 0.18.0 milestone Jan 7, 2016

jreback reviewed Jan 7, 2016
View reviewed changes

jreback added Indexing Related to indexing on series/frames, not to indexes themselves MultiIndex labels Jan 7, 2016

TomAugspurger force-pushed the chainable-rename branch from 6bcd810 to 62bf793 Compare January 9, 2016 16:03

TomAugspurger reviewed Jan 9, 2016
View reviewed changes

TomAugspurger force-pushed the chainable-rename branch from 62bf793 to cee54ae Compare January 9, 2016 16:11

TomAugspurger force-pushed the chainable-rename branch from cee54ae to 94e4c86 Compare January 9, 2016 18:59

jreback reviewed Feb 9, 2016
View reviewed changes

TomAugspurger force-pushed the chainable-rename branch 2 times, most recently from 262aeb3 to 45b1484 Compare February 10, 2016 16:25

ENH/API: Series.rename and NDFrame.rename_axis

b36df76

Overloading the APIs of Series.rename and NDFramed.rename_axis for method chaining.

TomAugspurger force-pushed the chainable-rename branch from 45b1484 to b36df76 Compare February 10, 2016 16:26

jreback mentioned this pull request Feb 10, 2016

BUG: MultiIndex.set_names loses name #11979

Open

TomAugspurger closed this in 3073b47 Feb 11, 2016

jreback mentioned this pull request Feb 19, 2016

ENH: Harmonize drop and rename API #12392

Closed

TomAugspurger mentioned this pull request Mar 14, 2016

BUG: .rename* not treating Series as mapping #12626

Closed

TomAugspurger deleted the chainable-rename branch November 3, 2016 12:38

chris-b1 mentioned this pull request Dec 8, 2016

API: allow DataFrame.rename to take a list-like of colums #14829

Open

TomAugspurger mentioned this pull request Mar 16, 2017

rename_axis inplace=True #15704

Closed

TomAugspurger mentioned this pull request Oct 10, 2017

API: deprecate rename_axis / reindex_axis ? #17833

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENH/API: Scalar values for Series.rename and NDFrame.rename_axis #11980

ENH/API: Scalar values for Series.rename and NDFrame.rename_axis #11980

TomAugspurger commented Jan 7, 2016

jreback Jan 7, 2016

jreback commented Jan 7, 2016

shoyer commented Jan 7, 2016

TomAugspurger commented Jan 7, 2016

jreback commented Jan 7, 2016

TomAugspurger commented Jan 7, 2016

TomAugspurger Jan 9, 2016

jreback Feb 1, 2016

shoyer Feb 1, 2016

kawochen Feb 1, 2016

TomAugspurger commented Jan 9, 2016

jorisvandenbossche commented Jan 9, 2016

jorisvandenbossche commented Jan 9, 2016

TomAugspurger commented Jan 9, 2016

jreback commented Jan 9, 2016

jreback Feb 9, 2016

TomAugspurger Feb 10, 2016

TomAugspurger commented Feb 11, 2016

jreback commented Feb 11, 2016

TomAugspurger commented Feb 11, 2016

jreback commented Feb 11, 2016

TomAugspurger commented Feb 11, 2016

jreback commented Feb 11, 2016

ENH/API: Scalar values for Series.rename and NDFrame.rename_axis #11980

ENH/API: Scalar values for Series.rename and NDFrame.rename_axis #11980

Conversation

TomAugspurger commented Jan 7, 2016

jreback Jan 7, 2016

Choose a reason for hiding this comment

jreback commented Jan 7, 2016

shoyer commented Jan 7, 2016

TomAugspurger commented Jan 7, 2016

jreback commented Jan 7, 2016

TomAugspurger commented Jan 7, 2016

TomAugspurger Jan 9, 2016

Choose a reason for hiding this comment

jreback Feb 1, 2016

Choose a reason for hiding this comment

shoyer Feb 1, 2016

Choose a reason for hiding this comment

kawochen Feb 1, 2016

Choose a reason for hiding this comment

TomAugspurger commented Jan 9, 2016

jorisvandenbossche commented Jan 9, 2016

jorisvandenbossche commented Jan 9, 2016

TomAugspurger commented Jan 9, 2016

jreback commented Jan 9, 2016

jreback Feb 9, 2016

Choose a reason for hiding this comment

TomAugspurger Feb 10, 2016

Choose a reason for hiding this comment

TomAugspurger commented Feb 11, 2016

jreback commented Feb 11, 2016

TomAugspurger commented Feb 11, 2016

jreback commented Feb 11, 2016

TomAugspurger commented Feb 11, 2016

jreback commented Feb 11, 2016