axis='index' or axis='columns' not widely known as alternative to axis=1 or 0

[pybokeh]

Hello, just wanted to create this issue to hopefully inspire someone to include the use of axis='index' or axis='columns' as an alternative to using axis=0 or 1 in the documentation/docstrings, since the latter form is less intuittive.

[dhirsch]

This would be great! I had no idea until just now

[TomAugspurger]

Thanks, I saw your post on r/pystats.

It'd be great if someone could go through and make sure that 'index'/'columns' works in place of 0/1 for all the methods. It should use self._get_axis_number Right now e.g. .interpolate fails.

Or we could publicize it first and fix bugs as they're reported.

[jreback]

Most of this is already done (and has been for quite a while), as the doc strings are auto-generated. That said is would be nice to audit to make sure they are in there. And as @TomAugspurger their are some functions that are not fully compliant.

Further I don't recall any section which explicity mentions this, maybe should go in Intro to Data Structures

In [3]: DataFrame.sum?    
Docstring:
Return the sum of the values for the requested axis

Parameters
----------
axis : {index (0), columns (1)}
skipna : boolean, default True
    Exclude NA/null values. If an entire row/column is NA, the result
    will be NA
level : int or level name, default None
        If the axis is a MultiIndex (hierarchical), count along a
        particular level, collapsing into a Series
numeric_only : boolean, default None
    Include only float, int, boolean data. If None, will attempt to use
    everything, then use only numeric data

Returns
-------
sum : Series or DataFrame (if level specified)

[pybokeh]

@TomAugspurger You're welcome! I'm glad it appears I wasn't the only one that thought the use of 0 or 1 for the axis parameter was a bit esoteric.

@jreback To be more explicit in the docs, how about from:

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

to

axis : 0 or 'index', 1 or 'columns'

or

axis: {0|'index'} or {1|'columns'}

I think your example may not be as clear as my 2 suggestions.

[jreback]

@pybokeh sure, pull-requests are welcome. This is just a 1-line change as these are all auto-generated.

[pybokeh]

@jreback I'm ashamed to admit that I don't yet know how to contribute to github projects, I just know how to create my own repositories, push changes to them, and create issues. Most of it is due to my Python knowledge isn't that great since I'm a data analyst and not a software developer. But for changes to documentation, I think I can handle those. I feel bad just raising issues when I want to also be able to provide solutions or in this case improve documentation. Hopefully, I will learn how to do pull requests during my next local Python meetup group meeting this Friday.

[jreback]

@pybokeh no shame!

everyone starts the same way
see here for some guidelines/howto: https://github.com/pydata/pandas/wiki/Contributing

[rockg]

Or the developers page on the main pandas website. http://pandas.pydata.org/developers.html. We need to add some meat to that Contributing page on the wiki as it doesn't tell you how to push your changes to github. I will do that.

[jreback]

@rockg thanks! organizing of the contributing docs is a huge plus!

IIRC we even discussed ONLY having them in the docs (and pointing at them from the pandas.pydata.org location.