modAL.density docstrings added, the function similarity() was renamed to information_density()

Author: cosmic-cortex

modAL/__init__.py

@@ -3,13 +3,13 @@
                          uncertainty_sampling, margin_sampling, entropy_sampling
 from .disagreement import vote_entropy, consensus_entropy, KL_max_disagreement, \
                           vote_entropy_sampling, consensus_entropy_sampling, max_disagreement_sampling, max_std_sampling
-from .density import similarity
+from .density import information_density
 
 __all__ = [
     'ActiveLearner', 'Committee', 'CommitteeRegressor',
     'classifier_uncertainty', 'classifier_margin', 'classifier_entropy',
     'uncertainty_sampling', 'margin_sampling', 'entropy_sampling',
     'vote_entropy', 'consensus_entropy', 'KL_max_disagreement',
     'vote_entropy_sampling', 'consensus_entropy_sampling', 'max_disagreement_sampling', 'max_std_sampling'
-    'similarity'
+    'information_density'
 ]

modAL/density.py

@@ -12,7 +12,19 @@
 
 
 def similarize_distance(distance_measure):
-
+    """
+    Takes a distance measure and converts it into a information_density measure.
+
+    Parameters
+    ----------
+    distance_measure: function
+        The distance measure to be converted into information_density measure.
+
+    Returns
+    -------
+    sim: function
+        The information_density measure obtained from the given disance measure.
+    """
     def sim(*args, **kwargs):
         return 1/(1 + distance_measure(*args, **kwargs))
 
@@ -22,9 +34,25 @@ def sim(*args, **kwargs):
 cosine_similarity = similarize_distance(cosine)
 
 
-def similarity(X_pool, similarity_measure=cosine_similarity):
-    sim = np.zeros(shape=(len(X_pool), ))
+def information_density(X_pool, similarity_measure=cosine_similarity):
+    """
+
+    Parameters
+    ----------
+    X_pool: numpy.ndarray of shape (n_samples, n_features)
+        The data for which the information density is to be calculated.
+
+    similarity_measure: function
+        The similarity measure to be used. Should take two 1d numpy.ndarrays for argument.
+
+    Returns
+    -------
+    inf_density: numpy.ndarray of shape (n_samples, )
+        The information density for each sample.
+
+    """
+    inf_density = np.zeros(shape=(len(X_pool), ))
     for X_idx, X in enumerate(X_pool):
-        sim[X_idx] = sum(similarity_measure(X, X_j) for X_j in X_pool)
+        inf_density[X_idx] = sum(similarity_measure(X, X_j) for X_j in X_pool)
 
-    return sim/len(X_pool)
+    return inf_density/len(X_pool)

tests/core_tests.py

@@ -194,11 +194,11 @@ def test_similarize_distance(self):
                     1/(1 + cosine(X_1, X_2))
                 )
 
-    def test_similarity(self):
+    def test_information_density(self):
         for n_samples in range(1, 10):
             for n_dim in range(1, 10):
                 X_pool = np.random.rand(n_samples, n_dim)
-                similarities = modAL.density.similarity(X_pool)
+                similarities = modAL.density.information_density(X_pool)
                 np.testing.assert_equal(len(similarities), n_samples)