docs: improve utils

Author: nikolay-bushkov

modAL/utils/combination.py

@@ -1,12 +1,12 @@
-from typing import Callable, Optional, Collection, Tuple
+from typing import Callable, Optional, Sequence, Tuple
 
 import numpy as np
 from sklearn.base import BaseEstimator
 
 from modAL.utils.data import modALinput
 
 
-def make_linear_combination(*functions: Callable, weights: Optional[Collection] = None) -> Callable:
+def make_linear_combination(*functions: Callable, weights: Optional[Sequence] = None) -> Callable:
     """
     Takes the given functions and makes a function which returns the linear combination of the output of original
     functions. It works well with functions returning numpy arrays of the same shape.
@@ -35,7 +35,7 @@ def linear_combination(*args, **kwargs):
     return linear_combination
 
 
-def make_product(*functions: Callable, exponents: Optional[Collection] = None) -> Callable:
+def make_product(*functions: Callable, exponents: Optional[Sequence] = None) -> Callable:
     """
     Takes the given functions and makes a function which returns the product of the output of original functions. It
     works well with functions returning numpy arrays of the same shape.

modAL/utils/data.py

@@ -1,4 +1,5 @@
 from typing import Union
+from itertools import chain
 
 import numpy as np
 import scipy.sparse as sp
@@ -7,12 +8,20 @@
 modALinput = Union[list, np.ndarray, sp.csr_matrix]
 
 
-def data_vstack(blocks):
+def data_vstack(blocks: modALinput) -> modALinput:
     """
     Stack vertically both sparse and dense arrays.
+
+    Args:
+        blocks: Sequence of modALinput objects.
+
+    Returns:
+        New sequence of vertically stacked elements.
     """
     if isinstance(blocks[0], np.ndarray):
         return np.concatenate(blocks)
+    elif isinstance(blocks[0], list):
+        return list(chain(blocks))
     elif sp.issparse(blocks[0]):
         return sp.vstack(blocks)
     else:

modAL/utils/validation.py

@@ -1,22 +1,19 @@
+from typing import Sequence
+
 import numpy as np
 from sklearn.exceptions import NotFittedError
+from sklearn.base import BaseEstimator
 
 
-def check_class_labels(*args):
+def check_class_labels(*args: BaseEstimator) -> bool:
     """
-    Checks the known class labels for each classifier. Returns True if all classifier
-    knows the same labels and returns False if not.
+    Checks the known class labels for each classifier.
 
-    Parameters
-    ----------
-    *args: sklearn classifier objects
-        Classifier objects to check the known class labels.
+    Args:
+        *args: Classifier objects to check the known class labels.
 
-    Returns
-    -------
-    bool
-        True, if class labels match for all classifiers,
-        False otherwise.
+    Returns:
+        True, if class labels match for all classifiers, False otherwise.
     """
     try:
         classes_ = [estimator.classes_ for estimator in args]
@@ -30,31 +27,19 @@ def check_class_labels(*args):
     return True
 
 
-def check_class_proba(proba, known_labels, all_labels):
+def check_class_proba(proba: np.ndarray, known_labels: Sequence, all_labels: Sequence) -> np.ndarray:
     """
-    Checks the class probabilities and reshapes it if not all labels are present
-    in the classifier.
-
-    Parameters
-    ----------
-    proba: numpy.ndarray of shape (n_samples, n_known_classes)
-        The class probabilities of a classifier.
-
-    known_labels:
-        The class labels known by the classifier.
+    Checks the class probabilities and reshapes it if not all labels are present in the classifier.
 
-    all_labels:
-        All class labels.
-
-    Returns
-    -------
-    aug_proba: numpy.ndarray of shape (n_samples, n_classes)
-        Class probabilities augmented such that the probability of all classes
-        is present. If the classifier is unaware of a particular class, all
-        probabilities are zero.
+    Args:
+        proba: The class probabilities of a classifier.
+        known_labels: The class labels known by the classifier.
+        all_labels: All class labels.
 
+    Returns:
+        Class probabilities augmented such that the probability of all classes is present. If the classifier is unaware
+        of a particular class, all probabilities are zero.
     """
-
     # TODO: rewrite this function using numpy.insert
 
     label_idx_map = -np.ones(len(all_labels), dtype='int')