ENH: Harmonize drop and rename API

[nickeubank]

rename accepts a columns argument or an index argument, while drop looks for a labels and axis pair. I don't know about anyone else, but I have to check the help file every time I come back to pandas to remember which takes which.

How would people feel about adding columns and index arguments to drop? They could just be added in addition to labels/axis if we want to provide backwards compatibility and just raise an exception if the user tries to mix them.

[jreback]

actually this is a bigger API issue that @TomAugspurger and I briefly touched on here

.rename and .rename_axis
.reindex and .reindex_axis
are consistent with each other

.drop and .fillna are also consistent (just not with the others)

So thoughts on how to proceed here. I'd rather not make add hoc changes, rather try to construct an overall consistent way of doing things; we can certainly provide back-compat, but unifying things is probably a good thing.

[TomAugspurger]

I don't have a strong preference for one style over the other. The only upshot of the .rename(index=, columns=) approach is that you can do both at once instead of .rename_axis(index).rename_axis(columns, axis=1), very minor.

I would slightly favor just recommending and documenting the _axis methods (with labels, axis) rather than changing any method signatures.

[jreback]

do you think we should add corresponding .drop_axis and .fillna_axis? or too much clutter

[nickeubank]

Personally, I have a preference for columns and index as arguments -- they've always felt more intuitive and pythonic to me. But that's second to the value of harmonization.

Just documenting the _axis methods still leaves an uncomfortable inconsistency though, no? We offer a work around, I'd be in favor of fixing .drop and .fillna.

I'm agnostic on adding .drop_axis/.fillna_axis methods.

If we change the .drop and .fillna methods to take columns, index, do we still want to support the labels, axis arguments for backwards compatibility or break the api?

[jreback]

why don't you list all of the relevant methods (might be some more that I am forgetting), and make a proposal.

[nickeubank]

OK

[nickeubank]

drop and fillna:

• change primary arguments from labels, axis to columns, index
• Accept labels, axis arguments for backward compatibility, but move to back of argument list
  (note this will break code by people who passed labels as first positional argument, but ok since will throw and exception
  if no positional arguments allowed)

drop_axis and fillna_axis:

• New method that accepts labels, axis

Others:

• Could implement for apply if we really wanted? I'm dis-inclined, but possible.
• Could implement for add() , sub() , mul(), div(), radd(), rsum(), etc...

Open question:

• How should these work for panels? (I never use panels, so not sure of best practices)

[jreback]

see that's the problem. In reality we should leave everything alone and maybe just change reindex/rename. The labels/axis idiom is much more common (and to be honest quite a bit more useful). Rarely do you actually change 2 things at once (which violates many pythonic principles). I would rather chain things like:

.reindex(...., axis='index').reindex(...., axis='columns')

though we are actually flexible enough to accept both paradigms.

[nickeubank]

Oh, I don't really care about the "two things at once" -- I just liked the "columns" argument for being more meaningful.

So your preference is:

reindex/rename:
- change primary arguments to label / axis
- keep taking columns / index for backwards compatibility?

That's fine by me -- like I said, I'm mostly interested in harmonization!

[max-sixty]

The labels/axis idiom is much more common (and to be honest quite a bit more useful). Rarely do you actually change 2 things at once (which violates many pythonic principles).

+1

And, I know people have gone back & forth on this a bit - but I would also 'vote' for:

• .rename being like xarray: renaming axes names only or, where the object has a name (currently Series), renaming the object
• .relabel used for reindexing-like operations with a mapping from old to new labels

[shoyer]

The labels/axis idiom is much more common (and to be honest quite a bit more useful). Rarely do you actually change 2 things at once (which violates many pythonic principles).

I agree that changing 2 things at once is not a great API, but I agree with @nickeubank that explicit columns and index arguments make for more readable code: compare df.drop(columns='foo') vs df.drop('foo', axis='columns') (or worse, df.drop('foo', axis=1), which is assuredly more common because it's less typing).

[jorisvandenbossche]

I would like to avoid adding new methods as drop_axis (which is actually not a good name IMO, as it sounds you want to drop a full axis, while you want do drop certain items from an axis)

Further, I think we should make a clear distinction between methods that modify the axis (rename, drop, reindex), and methods that perform operation over a certain axis (apply, add, ..). Those last ones use the axis= idiom to specify the direction of operation, and that is indeed a common idiom. I think the discussion should only be about rename, reindex and drop

I personally also like the explicit column and index arguments in eg df.rename(columns=..) (this reads very natural). So I would not like to see these go (or deprecated).

It is not really good API design, but I think it is perfectly possible to combine both idioms in one method for all of the discussed functions as kind of a compromise?
For example, changes of the current signature could be:

• df.reindex(index=None, columns=None, ...) -> df.reindex(labels=None, index=None, columns=None, axis=0, ...)
• df.drop(labels, axis=0, ...) -> df.drop(labels=None, axis=0, index=None, columns=None, ...)

Which would be I think backwards compatible?
That would kind of harmonize the api for the different methods, but have the bad design of providing two ways to do something in one function.