From 5ed1a4fcd1e98c413c916b51b544a7b4c3b3a6a9 Mon Sep 17 00:00:00 2001
From: Scott Sanderson <ssanderson@quantopian.com>
Date: Tue, 22 Mar 2016 22:08:50 -0400
Subject: [PATCH] ENH: Add quartiles/quintiles/deciles.

They're all syntactic sugar for the equivalent invocations of quantiles.
---
 tests/pipeline/test_factor.py      | 16 +++++++
 zipline/pipeline/factors/factor.py | 72 ++++++++++++++++++++++++++++++
 2 files changed, 88 insertions(+)

diff --git a/tests/pipeline/test_factor.py b/tests/pipeline/test_factor.py
index 3a049bc1..3a7d4819 100644
--- a/tests/pipeline/test_factor.py
+++ b/tests/pipeline/test_factor.py
@@ -806,3 +806,19 @@ class FactorTestCase(BasePipelineTestCase):
 
         for key, (res, exp) in dzip_exact(results, expected).items():
             check_arrays(res, exp)
+
+    def test_quantile_helpers(self):
+        f = self.f
+        m = Mask()
+
+        self.assertIs(f.quartiles(), f.quantiles(bins=4))
+        self.assertIs(f.quartiles(mask=m), f.quantiles(bins=4, mask=m))
+        self.assertIsNot(f.quartiles(), f.quartiles(mask=m))
+
+        self.assertIs(f.quintiles(), f.quantiles(bins=5))
+        self.assertIs(f.quintiles(mask=m), f.quantiles(bins=5, mask=m))
+        self.assertIsNot(f.quintiles(), f.quintiles(mask=m))
+
+        self.assertIs(f.deciles(), f.quantiles(bins=10))
+        self.assertIs(f.deciles(mask=m), f.quantiles(bins=10, mask=m))
+        self.assertIsNot(f.deciles(), f.deciles(mask=m))
diff --git a/zipline/pipeline/factors/factor.py b/zipline/pipeline/factors/factor.py
index 774ed7e4..27e0e476 100644
--- a/zipline/pipeline/factors/factor.py
+++ b/zipline/pipeline/factors/factor.py
@@ -712,6 +712,78 @@ class Factor(RestrictedDTypeMixin, ComputableTerm):
             mask = self.mask
         return Quantiles(inputs=(self,), bins=bins, mask=mask)
 
+    @expect_types(mask=(Filter, NotSpecifiedType))
+    def quartiles(self, mask=NotSpecified):
+        """
+        Construct a Classifier computing quartiles over the output of ``self``.
+
+        Every non-NaN data point the output is labelled with a value of either
+        0, 1, 2, or 3, corresponding to the first, second, third, or fourth
+        quartile over each row.  NaN data points are labelled with -1.
+
+        If ``mask`` is supplied, ignore data points in locations for which
+        ``mask`` produces False, and emit a label of -1 at those locations.
+
+        Parameters
+        ----------
+        mask : zipline.pipeline.Filter, optional
+            Mask of values to ignore when computing quartiles.
+
+        Returns
+        -------
+        quartiles : zipline.pipeline.classifiers.Quantiles
+            A Classifier producing integer labels ranging from 0 to 3.
+        """
+        return self.quantiles(bins=4, mask=mask)
+
+    @expect_types(mask=(Filter, NotSpecifiedType))
+    def quintiles(self, mask=NotSpecified):
+        """
+        Construct a Classifier computing quintile labels on ``self``.
+
+        Every non-NaN data point the output is labelled with a value of either
+        0, 1, 2, or 3, 4, corresonding to quintiles over each row.  NaN data
+        points are labelled with -1.
+
+        If ``mask`` is supplied, ignore data points in locations for which
+        ``mask`` produces False, and emit a label of -1 at those locations.
+
+        Parameters
+        ----------
+        mask : zipline.pipeline.Filter, optional
+            Mask of values to ignore when computing quintiles.
+
+        Returns
+        -------
+        quintiles : zipline.pipeline.classifiers.Quantiles
+            A Classifier producing integer labels ranging from 0 to 4.
+        """
+        return self.quantiles(bins=5, mask=mask)
+
+    @expect_types(mask=(Filter, NotSpecifiedType))
+    def deciles(self, mask=NotSpecified):
+        """
+        Construct a Classifier computing decile labels on ``self``.
+
+        Every non-NaN data point the output is labelled with a value from 0 to
+        9 corresonding to deciles over each row.  NaN data points are labelled
+        with -1.
+
+        If ``mask`` is supplied, ignore data points in locations for which
+        ``mask`` produces False, and emit a label of -1 at those locations.
+
+        Parameters
+        ----------
+        mask : zipline.pipeline.Filter, optional
+            Mask of values to ignore when computing deciles.
+
+        Returns
+        -------
+        deciles : zipline.pipeline.classifiers.Quantiles
+            A Classifier producing integer labels ranging from 0 to 4.
+        """
+        return self.quantiles(bins=10, mask=mask)
+
     def top(self, N, mask=NotSpecified):
         """
         Construct a Filter matching the top N asset values of self each day.