docs: refactor utils.combination module

Author: nikolay-bushkov

modAL/utils/combination.py

@@ -1,31 +1,28 @@
+from typing import Callable, Optional, Collection, Tuple
+
 import numpy as np
-from itertools import chain
+from sklearn.base import BaseEstimator
 
+from modAL.utils.data import modALinput
 
-def make_linear_combination(*functions, weights=None):
-    """
-    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.
 
-    :param functions:
-        Base functions for the linear combination.The functions shall have the same
-        argument and if they return numpy arrays, the returned arrays shall have the same shape.
-    :type functions:
-        function
+def make_linear_combination(*functions: Callable, weights: Optional[Collection] = 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.
 
-    :param weights:
-        Coefficients of the functions in the linear combination. The i-th given function
-        will be multiplied with with weights[i].
-    :type weights:
-        array-like, length shall match the number of functions given
+    Args:
+        *functions: Base functions for the linear combination.The functions shall have the same argument and if they
+            return numpy arrays, the returned arrays shall have the same shape.
+        weights: Coefficients of the functions in the linear combination. The i-th given function will be multiplied
+            with weights[i].
 
+    Todo:
+        Doesn't it better to accept functions as a Collection explicitly?
 
-    :returns:
-      - **linear_combination** *(function)* --
+    Returns:
         A function which returns the linear combination of the given functions output.
     """
-
     if weights is None:
         weights = np.ones(shape=(len(functions)))
     else:
@@ -38,29 +35,20 @@ def linear_combination(*args, **kwargs):
     return linear_combination
 
 
-def make_product(*functions, exponents=None):
+def make_product(*functions: Callable, exponents: Optional[Collection] = 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.
-
-    :param functions:
-        Base functions for the product. The functions shall have the same argument and if
-        they return numpy arrays, the returned arrays shall have the same shape.
-    :type functions:
-        function
-
-    :param exponents:
-        Exponents of the functions in the product. The i-th given function in the product
-        will be raised to the power of exponents[i].
-    :type exponents:
-        array-like, length shall match the number of functions given
-
-    :returns:
-      - **product_function** *(function)* --
+    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.
+
+    Args:
+        *functions: Base functions for the product. The functions shall have the same argument and if they return numpy
+            arrays, the returned arrays shall have the same shape.
+        exponents: Exponents of the functions in the product. The i-th given function in the product will be raised to
+            the power of exponents[i].
+
+    Returns:
         A function which returns the product function of the given functions output.
     """
-
     if exponents is None:
         exponents = np.ones(shape=(len(functions)))
     else:
@@ -74,31 +62,21 @@ def product_function(*args, **kwargs):
     return product_function
 
 
-def make_query_strategy(utility_measure, selector):
-    """
-    Takes the given utility measure and selector functions and makes a query strategy
-    by combining them.
-
-    :param utility_measure:
-        Utility measure, for instance modAL.disagreement.vote_entropy, but it can be
-        a custom function as well. Should take a classifier and the unlabelled data
-        and should return an array containing the utility scores.
-    :type utility_measure:
-        function
-
-    :param selector:
-        Function selecting instances for query. Should take an array of utility scores
-        and should return an array containing the queried items.
-    :type selector:
-        function
-
-    :returns:
-      - **query_strategy** *(function)* --
-        A function which returns queried instances given a classifier and an unlabelled
-        pool.
+def make_query_strategy(utility_measure: Callable, selector: Callable) -> Callable:
     """
+    Takes the given utility measure and selector functions and makes a query strategy by combining them.
 
-    def query_strategy(classifier, X):
+    Args:
+        utility_measure: Utility measure, for instance :func:`~modAL.disagreement.vote_entropy`, but it can be a custom
+            function as well. Should take a classifier and the unlabelled data and should return an array containing the
+            utility scores.
+        selector: Function selecting instances for query. Should take an array of utility scores and should return an
+            array containing the queried items.
+
+    Returns:
+        A function which returns queried instances given a classifier and an unlabelled pool.
+    """
+    def query_strategy(classifier: BaseEstimator, X: modALinput) -> Tuple:
         utility = utility_measure(classifier, X)
         query_idx = selector(utility)
         return query_idx, X[query_idx]