From 396d2f432747f40182639e7294f00123a2473f7b Mon Sep 17 00:00:00 2001
From: Scott Sanderson <ssanderson@quantopian.com>
Date: Sat, 19 Mar 2016 19:03:41 -0400
Subject: [PATCH] DOC: Update Filter/Factor/Classifier docstrings.

---
 zipline/pipeline/classifiers/classifier.py |  9 +++++
 zipline/pipeline/factors/factor.py         | 25 +++++++++++-
 zipline/pipeline/filters/filter.py         | 46 +++++++++++++++++++++-
 3 files changed, 78 insertions(+), 2 deletions(-)

diff --git a/zipline/pipeline/classifiers/classifier.py b/zipline/pipeline/classifiers/classifier.py
index 84c9bb83..6777e03e 100644
--- a/zipline/pipeline/classifiers/classifier.py
+++ b/zipline/pipeline/classifiers/classifier.py
@@ -15,6 +15,15 @@ from ..mixins import (
 
 
 class Classifier(RestrictedDTypeMixin, ComputableTerm):
+    """
+    A Pipeline expression computing a categorical output.
+
+    Classifiers are most commonly useful for describing grouping keys for
+    complex transformations on Factor outputs. For example, Factor.demean() and
+    Factor.zscore() can be passed a Classifier in their ``groupby`` argument,
+    indicating that means/standard deviations should be computed on assets for
+    which the classifier produced the same label.
+    """
     ALLOWED_DTYPES = (int64_dtype,)  # Used by RestrictedDTypeMixin
 
 
diff --git a/zipline/pipeline/factors/factor.py b/zipline/pipeline/factors/factor.py
index c510878e..b9054e5d 100644
--- a/zipline/pipeline/factors/factor.py
+++ b/zipline/pipeline/factors/factor.py
@@ -397,7 +397,30 @@ FACTOR_DTYPES = frozenset([datetime64ns_dtype, float64_dtype, int64_dtype])
 
 class Factor(RestrictedDTypeMixin, ComputableTerm):
     """
-    Pipeline API expression producing numerically-valued outputs.
+    Pipeline API expression producing a numerical or date-valued output.
+
+    Factors are the most commonly-used Pipeline term, representing the result
+    of any computation producing a numerical result.
+
+    Factors can be combined, both with other Factors and with scalar values,
+    via any of the builtin mathematical operators (``+``, ``-``, ``*``, etc).
+    This makes it easy to write complex expressions that combine multiple
+    Factors.  For example, constructing a Factor that computes the average of
+    two other Factors is simply::
+
+        >>> f1 = SomeFactor(...)
+        >>> f2 = SomeOtherFactor(...)
+        >>> average = (f1 + f2) / 2.0
+
+    Factors can also be converted into :class:`zipline.pipeline.Filter` objects
+    via comparison operators: (``<``, ``<=``, ``!=``, ``eq``, ``>``, ``>=``).
+
+    There are many natural operators defined on Factors besides the basic
+    numerical operators. These include methods identifying missing or
+    extreme-valued outputs (isnull, notnull, isnan, notnan), methods for
+    normalizing outputs (rank, demean, zscore), and methods for constructing
+    Filters based on rank-order properties of results (top, bottom,
+    percentile_between).
     """
     ALLOWED_DTYPES = FACTOR_DTYPES  # Used by RestrictedDTypeMixin
 
diff --git a/zipline/pipeline/filters/filter.py b/zipline/pipeline/filters/filter.py
index 9d412329..a2e2c6e0 100644
--- a/zipline/pipeline/filters/filter.py
+++ b/zipline/pipeline/filters/filter.py
@@ -117,7 +117,51 @@ def unary_operator(op):
 
 class Filter(RestrictedDTypeMixin, ComputableTerm):
     """
-    Pipeline API expression producing boolean-valued outputs.
+    Pipeline expression computing a boolean output.
+
+    Filters are most commonly useful for describing sets of assets to include
+    or exclude for some particular purpose. Many Pipeline API functions accept
+    a ``mask`` argument, which can be supplied a Filter indicating that only
+    values passing the Filter should be considered when performing the
+    requested computation. For example, :meth:`zipline.pipeline.Factor.top`
+    accepts a mask indicating that ranks should be computed only on assets that
+    passed the specified Filter.
+
+    The most common way to construct a Filter is via one of the comparison
+    operators (``<``, ``<=``, ``!=``, ``eq``, ``>``, ``>=``) of
+    :class:`~zipline.pipeline.Factor`. For example, a natural way to construct
+    a Filter for stocks with a 10-day VWAP less than $20.0 is to first
+    construct a Factor computing 10-day VWAP and compare it to the scalar value
+    20.0::
+
+        >>> from zipline.pipeline.factors import VWAP
+        >>> vwap_10 = VWAP(window_length=10)
+        >>> vwaps_under_20 = (vwap_10 <= 20)
+
+    Filters can also be constructed via comparisons between two Factors.  For
+    example, to construct a Filter producing True for asset/date pairs where
+    the asset's 10-day VWAP was greater than it's 30-day VWAP::
+
+        >>> short_vwap = VWAP(window_length=10)
+        >>> long_vwap = VWAP(window_length=30)
+        >>> higher_short_vwap = (short_vwap > long_vwap)
+
+    Filters can be combined via the ``&`` (and) and ``|`` (or) operators.
+
+    ``&``-ing together two filters produces a new Filter that produces True if
+    **both** of the inputs produced True.
+
+    ``|``-ing together two filters produces a new Filter that produces True if
+    **either** of its inputs produced True.
+
+    The ``~`` operator can be used to invert a Filter, swapping all True values
+    with Falses and vice-versa.
+
+    Filters may be set as the ``screen`` attribute of a Pipeline, indicating
+    asset/date pairs for which the filter produces False should be excluded
+    from the Pipeline's output.  This is useful both for reducing noise in the
+    output of a Pipeline and for reducing memory consumption of Pipeline
+    results.
     """
     ALLOWED_DTYPES = (bool_dtype,)  # Used by RestrictedDTypeMixin
     dtype = bool_dtype