ENH: implement passed quantile array to qcut and document that plus factors, close #1407

Author: wesm

doc/source/basics.rst

@@ -369,6 +369,47 @@ index labels with the minimum and maximum corresponding values:
    df1.idxmin(axis=0)
    df1.idxmax(axis=1)
 
+Value counts (histogramming)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``value_counts`` Series method and top-level function computes a histogram
+of a 1D array of values. It can also be used as a function on regular arrays:
+
+.. ipython:: python
+
+   data = np.random.randint(0, 7, size=50)
+   data
+   s = Series(data)
+   s.value_counts()
+   value_counts(data)
+
+
+Discretization and quantiling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Continuous values can be discretized using the ``cut`` (bins based on values)
+and ``qcut`` (bins based on sample quantiles) functions:
+
+.. ipython:: python
+
+   arr = np.random.randn(20)
+   factor = cut(arr, 4)
+   factor
+
+   factor = cut(arr, [-5, -1, 0, 1, 5])
+   factor
+
+``qcut`` computes sample quantiles. For example, we could slice up some
+normally distributed data into equal-size quartiles like so:
+
+.. ipython:: python
+
+   arr = np.random.randn(30)
+   factor = qcut(arr, [0, .25, .5, .75, 1])
+   factor
+   value_counts(factor)
+
+
 .. _basics.apply:
 
 Function application

doc/source/groupby.rst

@@ -590,3 +590,17 @@ If there are any NaN values in the grouping key, these will be automatically
 excluded. So there will never be an "NA group". This was not the case in older
 versions of pandas, but users were generally discarding the NA group anyway
 (and supporting it was an implementation headache).
+
+Grouping with ordered factors
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Categorical variables represented as instance of pandas's ``Factor`` class can
+be used as group keys. If so, the order of the levels will be preserved:
+
+.. ipython:: python
+
+   data = Series(np.random.randn(100))
+
+   factor = qcut(data, [0, .25, .5, .75, 1.])
+
+   data.groupby(factor).mean()

doc/source/timeseries.rst

@@ -859,7 +859,7 @@ time zone:
 
    ts = Series(randn(len(rng)), rng)
 
-   ts_utc = ts.tz_convert('UTC')
+   ts_utc = ts.tz_localize('UTC')
    ts_utc
 
    ts_utc.tz_convert('US/Eastern')

pandas/tools/tests/test_tile.py

@@ -109,6 +109,13 @@ def test_qcut_bounds(self):
         factor = qcut(arr, 10, labels=False)
         self.assert_(len(np.unique(factor)) == 10)
 
+    def test_qcut_specify_quantiles(self):
+        arr = np.random.randn(100)
+
+        factor = qcut(arr, [0, .25, .5, .75, 1.])
+        expected = qcut(arr, 4)
+        self.assert_(factor.equals(expected))
+
     def test_cut_out_of_bounds(self):
         np.random.seed(12345)
 

pandas/tools/tile.py

@@ -111,7 +111,8 @@ def qcut(x, q=4, labels=None, retbins=False, precision=3):
     x : ndarray or Series
     q : integer or array of quantiles
         Number of quantiles. 10 for deciles, 4 for quartiles, etc. Alternately
-        array of quantiles, e.g. [0, .25, .5, .75, 1.] for quartiles
+        array of quantiles, e.g. [0, .25, .5, .75, 1.] for quartiles. Array of
+        quantiles must span [0, 1]
     labels : array or boolean, default None
         Labels to use for bin edges, or False to return integer bin labels
     retbins : bool, optional
@@ -129,12 +130,13 @@ def qcut(x, q=4, labels=None, retbins=False, precision=3):
     """
     if com.is_integer(q):
         quantiles = np.linspace(0, 1, q + 1)
-        bins = algos.quantile(x, quantiles)
-        bins[0] -= 0.001 * (x.max() - x.min())
-        return _bins_to_cuts(x, bins, labels=labels, retbins=retbins,
-                             precision=precision)
     else:
-        raise NotImplementedError
+        quantiles = q
+    bins = algos.quantile(x, quantiles)
+    bins[0] -= 0.001 * (x.max() - x.min())
+
+    return _bins_to_cuts(x, bins, labels=labels, retbins=retbins,
+                         precision=precision)
 
 
 def _bins_to_cuts(x, bins, right=True, labels=None, retbins=False,