DOC: Add a note about None values in the average documentation (#1180)

It was suggested in issue #1180 to add an ignore_None= parameter to
average, but I think this does not fit cleanly into NumPy, and rather
educating users about Python list comprehensions is better. This is
an attempt to do that.

1 files changed, 15 insertions, 0 deletions

diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py
index dd792c509..f04018cce 100644
--- a/numpy/lib/function_base.py
+++ b/numpy/lib/function_base.py
@@ -421,6 +421,21 @@ def average(a, axis=None, weights=None, returned=False):
         When the length of 1D `weights` is not the same as the shape of `a`
         along axis.
 
+    Notes
+    -----
+    When the array `a` contains `None` values, this function will throw
+    an error. If you would like to calculate the average without the `None`
+    values in the calculation, the `list comprehension`_ feature in Python
+    is a great way to do that. If you're new to Python, learning about
+    list comprehensions is well worth your while, as they make
+    manipulating and filtering lists very convenient.
+
+    .. _list comprehension: http://docs.python.org/tutorial/datastructures.html#list-comprehensions
+
+    >>> a = [1, None, 2, None]
+    >>> np.average([x for x in a if x != None])
+    1.5
+
     See Also
     --------
     mean