Repository: pandas-dev/pandas

Issue:
axis='index' or axis='columns' not widely known as alternative to axis=1 or 0
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.



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

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.

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)
```

@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.

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

@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.

@pybokeh no shame!

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

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.

@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.


Resolving patch:
diff --git a/pandas/core/frame.py b/pandas/core/frame.py
--- a/pandas/core/frame.py
+++ b/pandas/core/frame.py
@@ -2745,7 +2745,7 @@ def dropna(self, axis=0, how='any', thresh=None, subset=None,
 
         Parameters
         ----------
-        axis : {0, 1}, or tuple/list thereof
+        axis : {0 or 'index', 1 or 'columns'}, or tuple/list thereof
             Pass tuple or list to drop on multiple axes
         how : {'any', 'all'}
             * any : if any NA values are present, drop that label
@@ -2890,7 +2890,7 @@ def sort(self, columns=None, axis=0, ascending=True,
         ascending : boolean or list, default True
             Sort ascending vs. descending. Specify list for multiple sort
             orders
-        axis : {0, 1}
+        axis : {0 or 'index', 1 or 'columns'}, default 0
             Sort index/rows versus columns
         inplace : boolean, default False
             Sort the DataFrame without creating a new instance
@@ -2919,7 +2919,7 @@ def sort_index(self, axis=0, by=None, ascending=True, inplace=False,
 
         Parameters
         ----------
-        axis : {0, 1}
+        axis : {0 or 'index', 1 or 'columns'}, default 0
             Sort index/rows versus columns
         by : object
             Column name(s) in frame. Accepts a column name or a list
@@ -3027,7 +3027,7 @@ def sortlevel(self, level=0, axis=0, ascending=True,
         Parameters
         ----------
         level : int
-        axis : {0, 1}
+        axis : {0 or 'index', 1 or 'columns'}, default 0
         ascending : boolean, default True
         inplace : boolean, default False
             Sort the DataFrame without creating a new instance
@@ -3639,9 +3639,9 @@ def apply(self, func, axis=0, broadcast=False, raw=False, reduce=None,
         ----------
         func : function
             Function to apply to each column/row
-        axis : {0, 1}
-            * 0 : apply function to each column
-            * 1 : apply function to each row
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            * 0 or 'index': apply function to each column
+            * 1 or 'columns': apply function to each row
         broadcast : boolean, default False
             For aggregation functions, return object of same size with values
             propagated
@@ -4162,8 +4162,8 @@ def corrwith(self, other, axis=0, drop=False):
         Parameters
         ----------
         other : DataFrame
-        axis : {0, 1}
-            0 to compute column-wise, 1 for row-wise
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            0 or 'index' to compute column-wise, 1 or 'columns' for row-wise
         drop : boolean, default False
             Drop missing indices from result, default returns union of all
 
@@ -4214,8 +4214,8 @@ def count(self, axis=0, level=None, numeric_only=False):
 
         Parameters
         ----------
-        axis : {0, 1}
-            0 for row-wise, 1 for column-wise
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            0 or 'index' for row-wise, 1 or 'columns' for column-wise
         level : int or level name, default None
             If the axis is a MultiIndex (hierarchical), count along a
             particular level, collapsing into a DataFrame
@@ -4368,8 +4368,8 @@ def idxmin(self, axis=0, skipna=True):
 
         Parameters
         ----------
-        axis : {0, 1}
-            0 for row-wise, 1 for column-wise
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            0 or 'index' for row-wise, 1 or 'columns' for column-wise
         skipna : boolean, default True
             Exclude NA/null values. If an entire row/column is NA, the result
             will be NA
@@ -4399,8 +4399,8 @@ def idxmax(self, axis=0, skipna=True):
 
         Parameters
         ----------
-        axis : {0, 1}
-            0 for row-wise, 1 for column-wise
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            0 or 'index' for row-wise, 1 or 'columns' for column-wise
         skipna : boolean, default True
             Exclude NA/null values. If an entire row/column is NA, the result
             will be first index.
@@ -4446,9 +4446,9 @@ def mode(self, axis=0, numeric_only=False):
 
         Parameters
         ----------
-        axis : {0, 1, 'index', 'columns'} (default 0)
-            * 0/'index' : get mode of each column
-            * 1/'columns' : get mode of each row
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            * 0 or 'index' : get mode of each column
+            * 1 or 'columns' : get mode of each row
         numeric_only : boolean, default False
             if True, only apply to numeric columns
 
@@ -4553,7 +4553,7 @@ def rank(self, axis=0, numeric_only=None, method='average',
 
         Parameters
         ----------
-        axis : {0, 1}, default 0
+        axis : {0 or 'index', 1 or 'columns'}, default 0
             Ranks over columns (0) or rows (1)
         numeric_only : boolean, default None
             Include only float, int, boolean data
@@ -4605,7 +4605,7 @@ def to_timestamp(self, freq=None, how='start', axis=0, copy=True):
         how : {'s', 'e', 'start', 'end'}
             Convention for converting period to timestamp; start of period
             vs. end
-        axis : {0, 1} default 0
+        axis : {0 or 'index', 1 or 'columns'}, default 0
             The axis to convert (the index by default)
         copy : boolean, default True
             If false then underlying input data is not copied
@@ -4636,7 +4636,7 @@ def to_period(self, freq=None, axis=0, copy=True):
         Parameters
         ----------
         freq : string, default
-        axis : {0, 1}, default 0
+        axis : {0 or 'index', 1 or 'columns'}, default 0
             The axis to convert (the index by default)
         copy : boolean, default True
             If False then underlying input data is not copied


Test patch: