parameterized empty neighborhoods feature

Signed-off-by: Emily Strong <emily.strong@fmr.com>

Author: Emily Strong

CHANGELOG.txt

@@ -2,6 +2,14 @@
 MABWiser CHANGELOG
 =====================
 
+
+-------------------------------------------------------------------------------
+Aug, 13, 2019 1.6.0
+-------------------------------------------------------------------------------
+major:
+- Configurable empty neighborhood operation for Radius policy
+- Empty neighborhood operation changed to use numpy.random.choice instead of numpy.random.randint. Observed predictions for empty neighborhoods may differ from versions 1.5 and prior.
+
 -------------------------------------------------------------------------------
 August, 12, 2019 1.5.10
 -------------------------------------------------------------------------------

README.md

@@ -96,7 +96,7 @@ To confirm that cloning the repo was successful, run the tests and all should pa
 ```bash
 git clone https://github.com/fmr-llc/mabwiser.git
 cd mabwiser
-python -m unittest discover tests
+python -m unittest discover -v tests
 ```
 
 To confirm that installation was successful, import the library in Python shell or notebook. 

dist/mabwiser-1.5.10-py3-none-any.whl

@@ -271,7 +271,7 @@
 </tr>
 <tr class="field-even field"><th class="field-name">Email:</th><td class="field-body"><a class="reference external" href="mailto:mabwiser&#37;&#52;&#48;fmr&#46;com">mabwiser<span>&#64;</span>fmr<span>&#46;</span>com</a></td>
 </tr>
-<tr class="field-odd field"><th class="field-name">Version:</th><td class="field-body">1.5.9 of July 1, 2019</td>
+<tr class="field-odd field"><th class="field-name">Version:</th><td class="field-body">1.6.0 of August 13, 2019</td>
 </tr>
 </tbody>
 </table>
@@ -1091,6 +1091,22 @@
 </table>
 </dd></dl>
 
+<dl class="attribute">
+<dt id="mabwiser.mab.NeighborhoodPolicy.Radius.no_nhood_prob_of_arm">
+<code class="descname">no_nhood_prob_of_arm</code><a class="headerlink" href="#mabwiser.mab.NeighborhoodPolicy.Radius.no_nhood_prob_of_arm" title="Permalink to this definition">¶</a></dt>
+<dd><p>The probabilities associated with each arm.
+If not given, a uniform random distribution over all arms is assumed.
+The probabilities should sum up to 1.</p>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Type:</th><td class="field-body">None or List</td>
+</tr>
+</tbody>
+</table>
+</dd></dl>
+
 <p class="rubric">Example</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">mabwiser.mab</span> <span class="k">import</span> <span class="n">MAB</span><span class="p">,</span> <span class="n">LearningPolicy</span><span class="p">,</span> <span class="n">NeighborhoodPolicy</span>
 <span class="gp">&gt;&gt;&gt; </span><span class="n">list_of_arms</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">]</span>
@@ -1109,6 +1125,12 @@
 <dd><p>Alias for field number 1</p>
 </dd></dl>
 
+<dl class="attribute">
+<dt>
+<code class="descname">no_nhood_prob_of_arm</code></dt>
+<dd><p>Alias for field number 2</p>
+</dd></dl>
+
 <dl class="attribute">
 <dt>
 <code class="descname">radius</code></dt>
@@ -1130,7 +1152,7 @@
 </tr>
 <tr class="field-even field"><th class="field-name">Email:</th><td class="field-body"><a class="reference external" href="mailto:mabwiser&#37;&#52;&#48;fmr&#46;com">mabwiser<span>&#64;</span>fmr<span>&#46;</span>com</a></td>
 </tr>
-<tr class="field-odd field"><th class="field-name">Version:</th><td class="field-body">1.5.9 of July 1, 2019</td>
+<tr class="field-odd field"><th class="field-name">Version:</th><td class="field-body">1.6.0 of August 13, 2019</td>
 </tr>
 </tbody>
 </table>

dist/mabwiser-1.6.0-py3-none-any.whl

@@ -403,15 +403,17 @@ <h2 id="N">N</h2>
       </ul></li>
       <li><a href="api.html#mabwiser.mab.MAB.neighborhood_policy">neighborhood_policy (mabwiser.mab.MAB attribute)</a>
 </li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="api.html#mabwiser.mab.NeighborhoodPolicy">NeighborhoodPolicy (class in mabwiser.mab)</a>
 </li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="api.html#mabwiser.mab.NeighborhoodPolicy.Clusters">NeighborhoodPolicy.Clusters (class in mabwiser.mab)</a>
 </li>
       <li><a href="api.html#mabwiser.mab.NeighborhoodPolicy.KNearest">NeighborhoodPolicy.KNearest (class in mabwiser.mab)</a>
 </li>
       <li><a href="api.html#mabwiser.mab.NeighborhoodPolicy.Radius">NeighborhoodPolicy.Radius (class in mabwiser.mab)</a>
+</li>
+      <li><a href="api.html#mabwiser.mab.NeighborhoodPolicy.Radius.no_nhood_prob_of_arm">no_nhood_prob_of_arm (mabwiser.mab.NeighborhoodPolicy.Radius attribute)</a>, <a href="api.html#mabwiser.mab.NeighborhoodPolicy.Radius.no_nhood_prob_of_arm">[1]</a>
 </li>
       <li><a href="api.html#mabwiser.utils.Num">Num (in module mabwiser.utils)</a>
 </li>

docs/_build/doctrees/api.doctree

@@ -58,7 +58,6 @@ def binarize(decision, reward):
 sim = Simulator(contextual_mabs, decisions, rewards, contexts,
                 scaler=StandardScaler(), test_size=0.5, is_ordered=False, batch_size=0, seed=123456)
 sim.run()
-sim.save_results()
 end = time()
 
 runtime = (end - start) / 60
@@ -84,7 +83,6 @@ def binarize(decision, reward):
 sim = Simulator(context_free_mabs, decisions, rewards, contexts=None,
                 scaler=None, test_size=0.5, is_ordered=False, batch_size=100, seed=123456)
 sim.run()
-sim.save_results()
 end = time()
 
 runtime = (end - start) / 60
@@ -110,7 +108,6 @@ def binarize(decision, reward):
 sim = Simulator(mixed, decisions, rewards, contexts,
                 scaler=StandardScaler(), test_size=0.5, is_ordered=False, batch_size=0, seed=123456)
 sim.run()
-sim.save_results()
 end = time()
 
 runtime = (end - start) / 60
@@ -138,7 +135,6 @@ def binarize(decision, reward):
 sim = Simulator(hyper_parameter_tuning, decisions, rewards, contexts,
                 scaler=StandardScaler(), test_size=0.5, is_ordered=False, batch_size=10, seed=123456)
 sim.run()
-sim.save_results()
 end = time()
 
 runtime = (end - start) / 60
@@ -165,7 +161,6 @@ def binarize(decision, reward):
 sim = Simulator(contextual_mabs, decisions, rewards, contexts,
                 scaler=StandardScaler(), test_size=0.5, is_ordered=False, batch_size=0, seed=123456, is_quick=True)
 sim.run()
-sim.save_results()
 end = time()
 
 runtime = (end - start) / 60

docs/_build/doctrees/environment.pickle

@@ -5,7 +5,7 @@
 """
 :Author: FMR LLC
 :Email: mabwiser@fmr.com
-:Version: 1.5.10 of August 12, 2019
+:Version: 1.6.0 of August 13, 2019
 
 This module defines the public interface of the **MABWiser Library** providing access to the following modules:
 
@@ -14,7 +14,7 @@
     - ``NeighborhoodPolicy``
 """
 
-from typing import List, Union, Dict, NamedTuple, NoReturn, Callable
+from typing import List, Union, Dict, NamedTuple, NoReturn, Callable, Optional
 
 import numpy as np
 import pandas as pd
@@ -36,7 +36,6 @@
 
 
 class LearningPolicy(NamedTuple):
-
     class EpsilonGreedy(NamedTuple):
         """Epsilon Greedy Learning Policy.
 
@@ -49,7 +48,7 @@ class EpsilonGreedy(NamedTuple):
             The probability of selecting a random arm for exploration.
             Integer or float. Must be between 0 and 1.
             Default value is 0.05.
-        
+
         Example
         -------
             >>> from mabwiser.mab import MAB, LearningPolicy
@@ -64,7 +63,6 @@ class EpsilonGreedy(NamedTuple):
         epsilon: Num = 0.05
 
         def _validate(self):
-
             check_true(isinstance(self.epsilon, (int, float)), TypeError("Epsilon must be an integer or float."))
             check_true(0 <= self.epsilon <= 1, ValueError("The value of epsilon must be between 0 and 1."))
 
@@ -286,7 +284,6 @@ def _validate(self):
 
 
 class NeighborhoodPolicy(NamedTuple):
-
     class Clusters(NamedTuple):
         """Clusters Neighborhood Policy.
 
@@ -378,6 +375,10 @@ class Radius(NamedTuple):
             The metric used to calculate distance.
             Accepts any of the metrics supported by scipy.spatial.distance.cdist.
             Default value is Euclidean distance.
+        no_nhood_prob_of_arm: None or List
+            The probabilities associated with each arm.
+            If not given, a uniform random distribution over all arms is assumed.
+            The probabilities should sum up to 1.
 
         Example
         -------
@@ -395,12 +396,18 @@ class Radius(NamedTuple):
         """
         radius: Num = 0.05
         metric: str = "euclidean"
+        no_nhood_prob_of_arm: Optional[List] = None
 
         def _validate(self):
             check_true(isinstance(self.radius, (int, float)), TypeError("Radius must be an integer or a float."))
             check_true((self.metric in Constants.distance_metrics),
                        ValueError("Metric must be supported by scipy.spatial.distance.cdist"))
             check_true(self.radius > 0, ValueError("Radius must be greater than zero."))
+            check_true((self.no_nhood_prob_of_arm == None) or isinstance(self.no_nhood_prob_of_arm, List),
+                       TypeError("no_nhood_prob_of_arm must be None or List."))
+            if isinstance(self.no_nhood_prob_of_arm, List):
+                check_true(np.isclose(sum(self.no_nhood_prob_of_arm), 1.0),
+                           ValueError("no_nhood_prob_of_arm should sum up to 1.0"))
 
 
 class MAB:
@@ -494,7 +501,6 @@ def __init__(self,
             If set to -1, all CPUs are used.
             If set to -2, all CPUs but one are used, and so on.
 
-
         Raises
         ------
         TypeError:  Arms were not provided in a list.
@@ -511,6 +517,7 @@ def __init__(self,
         TypeError:  For Clusters, n_clusters must be an integer.
         TypeError:  For Clusters, is_minibatch must be a boolean.
         TypeError:  For Radius, radius must be an integer or float.
+        TypeError:  For Radius, no_nhood_prob_of_arm must be None or List that sums up to 1.0.
         TypeError:  For KNearest, k must be an integer or float.
 
         ValueError: Invalid number of arms.
@@ -525,6 +532,7 @@ def __init__(self,
         ValueError: For Clusters, n_clusters cannot be less than 2.
         ValueError: For Radius and KNearest, metric is not supported by scipy.spatial.distance.cdist.
         ValueError: For Radius, radius must be greater than zero.
+        ValueError: For Radius, if given, no_nhood_prob_of_arm list should sum up to 1.0.
         ValueError: For KNearest, k must be greater than zero.
         """
 
@@ -564,15 +572,16 @@ def __init__(self,
         if neighborhood_policy:
             self.is_contextual = True
 
-            # Do not use parallel fit or predict for Learning Policy when co
+            # Do not use parallel fit or predict for Learning Policy when contextual
             lp.n_jobs = 1
 
             if isinstance(neighborhood_policy, NeighborhoodPolicy.Clusters):
                 self._imp = _Clusters(self._rng, self.arms, self.n_jobs, lp, self.neighborhood_policy.n_clusters,
                                       self.neighborhood_policy.is_minibatch)
             elif isinstance(neighborhood_policy, NeighborhoodPolicy.Radius):
                 self._imp = _Radius(self._rng, self.arms, self.n_jobs, lp,
-                                    self.neighborhood_policy.radius, self.neighborhood_policy.metric)
+                                    self.neighborhood_policy.radius, self.neighborhood_policy.metric,
+                                    self.neighborhood_policy.no_nhood_prob_of_arm)
             elif isinstance(neighborhood_policy, NeighborhoodPolicy.KNearest):
                 self._imp = _KNearest(self._rng, self.arms, self.n_jobs, lp,
                                       self.neighborhood_policy.k, self.neighborhood_policy.metric)
@@ -881,7 +890,7 @@ def _validate_fit_args(self, decisions, rewards, contexts) -> NoReturn:
             # Sync contexts data with contextual policy
             check_true(self.is_contextual,
                        TypeError("Fitting contexts data requires context policy or parametric learning policy."))
-            check_true((len(decisions) == len(contexts)) or (len(decisions)==1 and isinstance(contexts, pd.Series)),
+            check_true((len(decisions) == len(contexts)) or (len(decisions) == 1 and isinstance(contexts, pd.Series)),
                        ValueError("Decisions and contexts should be same length: len(decision) = " +
                                   str(len(decisions)) + " vs. len(contexts) = " + str(len(contexts))))
 

docs/_build/html/api.html

@@ -18,6 +18,7 @@
 
 
 class _Neighbors(BaseMAB):
+
     def __init__(self, rng: np.random.RandomState, arms: List[Arm], n_jobs: int,
                  lp: Union[_EpsilonGreedy, _Linear, _Random, _Softmax, _ThompsonSampling, _UCB1], metric: str):
         super().__init__(rng, arms, n_jobs)
@@ -79,6 +80,17 @@ def _predict_contexts(self, contexts: np.ndarray, is_predict: bool,
         """Abstract method to be implemented by child classes."""
         pass
 
+    def _get_nhood_predictions(self, lp, indices, row_2d, is_predict):
+
+        # Fit the decisions and rewards of the neighbors
+        lp.fit(self.decisions[indices], self.rewards[indices], self.contexts[indices])
+
+        # Predict based on the neighbors
+        if is_predict:
+            return lp.predict(row_2d)
+        else:
+            return lp.predict_expectations(row_2d)
+
     def _uptake_new_arm(self, arm: Arm, binarizer: Callable = None, scaler: Callable = None):
         self.lp.add_arm(arm, binarizer)
 
@@ -87,10 +99,11 @@ class _Radius(_Neighbors):
 
     def __init__(self, rng: np.random.RandomState, arms: List[Arm], n_jobs: int,
                  lp: Union[_EpsilonGreedy, _Softmax, _ThompsonSampling, _UCB1, _Linear],
-                 radius: Num, metric: str):
+                 radius: Num, metric: str, no_nhood_prob_of_arm=Optional[List]):
         super().__init__(rng, arms, n_jobs, lp, metric)
 
         self.radius = radius
+        self.no_nhood_prob_of_arm = no_nhood_prob_of_arm
 
     def _predict_contexts(self, contexts: np.ndarray, is_predict: bool,
                           seeds: Optional[np.ndarray] = None, start_index: Optional[int] = None) -> List:
@@ -119,26 +132,25 @@ def _predict_contexts(self, contexts: np.ndarray, is_predict: bool,
 
             # If neighbors exist
             if indices[0].size > 0:
-
-                # Fit the decisions and rewards of the neighbors
-                lp.fit(self.decisions[indices], self.rewards[indices], self.contexts[indices])
-
-                # Predict based on the neighbors
-                if is_predict:
-                    predictions[index] = lp.predict(row_2d)
-                else:
-                    predictions[index] = lp.predict_expectations(row_2d)
-
+                predictions[index] = self._get_nhood_predictions(lp, indices, row_2d, is_predict)
             else:  # When there are no neighbors
-                # Random arm (or nan expectations)
-                if is_predict:
-                    predictions[index] = self.arms[lp.rng.randint(0, len(self.arms))]
-                else:
-                    predictions[index] = self.arm_to_expectation.copy()
+                predictions[index] = self._get_no_nhood_predictions(lp, is_predict)
 
         # Return the list of predictions
         return predictions
 
+    def _get_no_nhood_predictions(self, lp, is_predict):
+
+        if is_predict:
+            # if no_nhood_prob_of_arm is None, select a random int
+            # else, select a non-uniform random arm
+            # choice returns an array, hence get zero index
+            rand_int = lp.rng.choice(len(self.arms), 1, p=self.no_nhood_prob_of_arm)[0]
+            return self.arms[rand_int]
+        else:
+            # Expectations will be nan when there are no neighbors
+            return self.arm_to_expectation.copy()
+
 
 class _KNearest(_Neighbors):
 
@@ -173,15 +185,7 @@ def _predict_contexts(self, contexts: np.ndarray, is_predict: bool,
             # Find the k nearest neighbor indices
             indices = np.argpartition(distances_to_row, self.k - 1)[:self.k]
 
-            # Fit the decisions and rewards of the neighbors learning from the contexts
-            lp.fit(self.decisions[indices], self.rewards[indices], self.contexts[indices])
-
-            # Predict (or predict_expectations) based on the neighbors
-            # The row is used only for parametric learning policies, and it has to be 2D
-            if is_predict:
-                predictions[index] = lp.predict(row_2d)
-            else:
-                predictions[index] = lp.predict_expectations(row_2d)
+            predictions[index] = self._get_nhood_predictions(lp, indices, row_2d, is_predict)
 
         # Return the list of predictions
         return predictions