Add thresholding preset.

Addresses #1058.

CHANGES.rst

@@ -30,6 +30,9 @@ Release History
   (`#1127 <https://github.com/nengo/nengo/pull/1127>`_)
 - Added ``ShapeParam`` to store array shapes.
   (`#1045 <https://github.com/nengo/nengo/pull/1045>`_)
+- Added ``ThresholdingPreset`` to configure ensembles for thresholding.
+  (`#1058 <https://github.com/nengo/nengo/issues/1058>`_,
+  `#1077 <https://github.com/nengo/nengo/pull/1077>`_)
 
 **Bug fixes**
 

nengo/__init__.py

@@ -31,7 +31,7 @@
 from .simulator import Simulator
 from .synapses import Alpha, LinearFilter, Lowpass, Triangle
 from .utils.logging import log
-from . import dists, exceptions, networks, processes, spa, utils
+from . import dists, exceptions, networks, presets, processes, spa, utils
 
 logger = logging.getLogger(__name__)
 try:

nengo/presets.py

@@ -0,0 +1,40 @@
+"""Configuration presets for common use cases."""
+
+import nengo
+
+
+def ThresholdingEnsembles(threshold):
+    """Configuration preset for a thresholding ensemble.
+
+    This preset adjust ensemble parameters for thresholding. The ensemble's
+    neurons will only fire for values above threshold. One can either decode
+    the represented value (if it is above the threshold) or decode
+    a step function if binary classification is desired.
+
+    This preset:
+
+    - Sets intercepts to be between ``threshold`` and 1 with an exponential
+      distribution (shape parameter of 0.15). This clusters intercepts near
+      the threshold for better approximation.
+    - Sets encoders to 1.
+    - Sets dimensions to 1.
+    - Sets evaluation points to be uniformly distributed between
+      ``threshold`` and 1.
+
+    Parameters
+    ----------
+    threshold : float
+        Point at which ensembles should start firing.
+
+    Returns
+    -------
+    `nengo.Config`
+        Configuration with presets.
+    """
+    config = nengo.Config(nengo.Ensemble)
+    config[nengo.Ensemble].dimensions = 1
+    config[nengo.Ensemble].intercepts = nengo.dists.Exponential(
+        0.15, threshold, 1.)
+    config[nengo.Ensemble].encoders = nengo.dists.Choice([[1]])
+    config[nengo.Ensemble].eval_points = nengo.dists.Uniform(threshold, 1.)
+    return config

nengo/tests/test_presets.py

@@ -0,0 +1,28 @@
+import numpy as np
+
+import nengo
+
+
+def test_thresholding_preset(Simulator, seed, plt):
+    threshold = 0.3
+    with nengo.Network(seed) as model:
+        with nengo.presets.ThresholdingEnsembles(threshold):
+            ens = nengo.Ensemble(50, 1)
+        stimulus = nengo.Node(lambda t: t)
+        nengo.Connection(stimulus, ens)
+        p = nengo.Probe(ens, synapse=0.01)
+
+    with Simulator(model) as sim:
+        sim.run(1.)
+
+    plt.plot(sim.trange(), sim.trange(), label="optimal")
+    plt.plot(sim.trange(), sim.data[p], label="actual")
+    plt.xlabel("Time [s]")
+    plt.ylabel("Value")
+    plt.title("Threshold = {}".format(threshold))
+    plt.legend(loc='best')
+
+    se = np.square(np.squeeze(sim.data[p]) - sim.trange())
+
+    assert np.allclose(sim.data[p][sim.trange() < threshold], 0.0)
+    assert np.sqrt(np.mean(se[sim.trange() > 0.5])) < 0.05