ENH: add new Warning class, improve tests, update docs

Author: dengemann

sklearn/utils/extmath.py

@@ -13,7 +13,7 @@
 from .fixes import qr_economic
 from ._logistic_sigmoid import _log_logistic_sigmoid
 from ..externals.six.moves import xrange
-from .validation import array2d, DataConversionWarning
+from .validation import array2d, NonBLASDotWarning
 
 
 def norm(v):
@@ -80,23 +80,35 @@ def _fast_dot(A, B):
     Parameters
     ----------
     A, B: instance of np.ndarray
-        input matrices.
+        input matrices. Matrices are supposed to be of the same types
+        and to have exactly 2 dimensions. Currently only floats are supported.
+        In case these requirements aren't met np.dot(A, B) is returned
+        instead. To activate the related warning issued in this case
+        execute the following lines of code:
+
+        >> import warnings
+        >> from sklearn.utils.validation import NonBLASDotWarning
+        >> warnings.simplefilter('always', NonBLASDotWarning)
     """
 
     if B.shape[0] != A.shape[A.ndim - 1]:  # check adopted from '_dotblas.c'
-        raise ValueError('matrices are not aligned')
+        msg = ('Invalid array shapes: A.shape[%d] should be the same as '
+               'B.shape[0]. Got A.shape=%r B.shape=%r' % (A.ndim - 1,
+                A.shape, B.shape))
+        raise ValueError(msg)
 
     if A.dtype != B.dtype or any(x.dtype not in (np.float32, np.float64)
-        for x in [A, B]):
+                                 for x in [A, B]):
         warnings.warn('Data must be of same type. Supported types '
                       'are 32 and 64 bit float. '
-                      'Falling back to np.dot.', DataConversionWarning)
+                      'Falling back to np.dot.', NonBLASDotWarning)
         return np.dot(A, B)
+
     if ((A.ndim == 1 or B.ndim == 1) or
         (min(A.shape) == 1) or (min(B.shape) == 1) or
         (A.ndim != 2) or (B.ndim != 2)):
         warnings.warn('Data must be 2D with more than one colum / row.'
-                      'Falling back to np.dot', DataConversionWarning)
+                      'Falling back to np.dot', NonBLASDotWarning)
         return np.dot(A, B)
 
     dot = linalg.get_blas_funcs('gemm', (A, B))
@@ -110,8 +122,7 @@ def _fast_dot(A, B):
     fast_dot = _fast_dot
 except (ImportError, AttributeError):
     fast_dot = np.dot
-    warnings.warn('Could not import BLAS, falling back to np.dot',
-                   DataConversionWarning)
+    warnings.warn('Could not import BLAS, falling back to np.dot')
 
 
 def density(w, **kwargs):

sklearn/utils/tests/test_extmath.py

@@ -24,7 +24,7 @@
 from sklearn.utils.extmath import cartesian
 from sklearn.utils.extmath import logistic_sigmoid
 from sklearn.utils.extmath import fast_dot
-from sklearn.utils.validation import DataConversionWarning
+from sklearn.utils.validation import NonBLASDotWarning
 from sklearn.datasets.samples_generator import make_low_rank_matrix
 
 
@@ -303,11 +303,29 @@ def test_fast_dot():
         has_blas = False
 
     if has_blas:
-        for dt1, dt2 in [['f8', 'f4'], ['i4', 'i4']]:
-            with warnings.catch_warnings(record=True) as w:
-                warnings.simplefilter("always", DataConversionWarning)
+        # test dispatch to np.dot
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter('always', NonBLASDotWarning)
+            # maltyped data
+            for dt1, dt2 in [['f8', 'f4'], ['i4', 'i4']]:
                 fast_dot(A.astype(dt1), B.astype(dt2).T)
-                assert_true(len(w) == 1)
+                assert_true(type(w.pop(-1)) == NonBLASDotWarning)
+            # malformed data
+            # ndim == 0
+            E = np.empty(0)
+            fast_dot(E, E)
+            assert_true(type(w.pop(-1)) == NonBLASDotWarning)
+            ## ndim == 1
+            fast_dot(A, A[0])
+            assert_true(type(w.pop(-1)) == NonBLASDotWarning)
+            ## ndim > 2
+            fast_dot(A.T, np.array([A, A]))
+            assert_true(type(w.pop(-1)) == NonBLASDotWarning)
+            ## min(shape) == 1
+            fast_dot(A, A[0, :][None, :])
+            assert_true(type(w.pop(-1)) == NonBLASDotWarning)
+        # test for matrix mismatch error
+        assert_raises(ValueError, fast_dot, A, A)
 
     # test cov-like use case + dtypes
     for dtype in ['f8', 'f4']:

sklearn/utils/validation.py

@@ -16,10 +16,16 @@ class DataConversionWarning(UserWarning):
     "A warning on implicit data conversions happening in the code"
     pass
 
-
 warnings.simplefilter("always", DataConversionWarning)
 
 
+class NonBLASDotWarning(UserWarning):
+    "A warning on implicit dispatch to numpy.dot"
+    pass
+
+warnings.simplefilter('ignore', NonBLASDotWarning)
+
+
 def _assert_all_finite(X):
     """Like assert_all_finite, but only for ndarray."""
     if (X.dtype.char in np.typecodes['AllFloat'] and not np.isfinite(X.sum())