NUP-2405: quick-start guide for the Network API

docs/examples/network/example-add-classifier.py

@@ -0,0 +1,2 @@
+clParams = modelParams["clParams"]
+network.addRegion("classifier", "py.SDRClassifierRegion", json.dumps(clParams))

docs/examples/network/example-add-sensor-region.py

@@ -0,0 +1 @@
+network.addRegion("sensor", "py.RecordSensor", '{}')

docs/examples/network/example-add-sp.py

@@ -0,0 +1,7 @@
+spParams = modelParams["spParams"]
+
+# Make sure the SP input width matches the sensor output width.
+spParams["inputWidth"] = sensorRegion.encoder.getWidth()
+
+# Add SP region.
+network.addRegion("SP", "py.SPRegion", json.dumps(spParams))

docs/examples/network/example-add-tm.py

@@ -0,0 +1,2 @@
+tmParams = modelParams["tmParams"]
+network.addRegion("TM", "py.TPRegion", json.dumps(tmParams))

docs/examples/network/example-create-encoder.py

@@ -0,0 +1,13 @@
+from nupic.encoders import MultiEncoder
+
+def createEncoder(encoderParams):
+  encoder = MultiEncoder()
+  encoder.addMultipleEncoders(encoderParams)
+  return encoder
+
+# Use the same modelParams extracted from the YAML file earlier.
+encoderParams = modelParams["sensorParams"]["encoders"]
+
+# Add encoder to the sensor region.
+sensorRegion = network.regions["sensor"].getSelf()
+sensorRegion.encoder = createEncoder(encoderParams)

docs/examples/network/example-create-network.py

@@ -0,0 +1,4 @@
+from nupic.engine import Network
+
+# A network that will hold the regions.
+network = Network()

docs/examples/network/example-create-regions.py

@@ -0,0 +1,49 @@
+import json
+
+# Add a sensor region, set its encoder and data source.
+network.addRegion("sensor", "py.RecordSensor", json.dumps({"verbosity": 0}))
+
+# Make sure the SP input width matches the sensor region output width.
+model_params["spParams"]["inputWidth"] = sensorRegion.encoder.getWidth()
+
+# Add the SP and TM regions.
+network.addRegion("SP", "py.SPRegion", json.dumps(model_params["spParams"]))
+network.addRegion("TM", "py.TPRegion", json.dumps(model_params["tmParams"]))
+
+# Add the classifier region.
+clName = "py.%s" % model_params[]
+network.addRegion("classifier", , json.dumps(model_params["clParams"]))
+
+
+
+# Add all links
+createSensorToClassifierLinks(network, "sensor", "classifier")
+
+# Link the sensor region to the SP region so that it can pass it data.
+createDataOutLink(network, "sensor", "SP")
+
+# Create feed-forward links between regions.
+createFeedForwardLink(network, "SP", "TM")
+createFeedForwardLink(network, "TM", "classifier")
+
+# Propagate reset signals to SP and TM regions.
+# Optional if you know that your sensor regions does not send resets.
+createResetLink(network, "sensor", "SP")
+createResetLink(network, "sensor", "TM")
+
+
+
+# Set the data source to the sensor region
+sensorRegion = network.regions["sensor"].getSelf()
+sensorRegion.dataSource = dataSource
+
+# Set the encoder to the sensor region
+sensorRegion.encoder = createEncoder(model_params["sensorParams"]["encoders"])
+
+
+
+# Make sure all objects are initialized.
+network.initialize()
+
+
+

docs/examples/network/example-data-source.py

@@ -0,0 +1,8 @@
+from nupic.data.file_record_stream import FileRecordStream
+
+_INPUT_FILE_PATH = "/path/to/your/data.csv"
+dataSource = FileRecordStream(streamID=_INPUT_FILE_PATH)
+
+# Add the data source to the sensor region.
+sensorRegion = network.regions["sensor"].getSelf()
+sensorRegion.dataSource = dataSource

docs/examples/network/example-enable-learning-and-inference.py

@@ -0,0 +1,9 @@
+# Enable learning for all regions.
+network.regions["SP"].setParameter("learningMode", 1)
+network.regions["TM"].setParameter("learningMode", 1)
+network.regions["classifier"].setParameter("learningMode", 1)
+
+# Enable inference for all regions.
+network.regions["SP"].setParameter("inferenceMode", 1)
+network.regions["TM"].setParameter("inferenceMode", 1)
+network.regions["classifier"].setParameter("inferenceMode", 1)

docs/examples/network/example-extract-results.py

@@ -0,0 +1,20 @@
+def getPredictionResults(network, clRegionName):
+  """Helper function to extract results for all prediction steps."""
+
+
+  classifierRegion = network.regions[clRegionName]
+  actualValues = classifierRegion.getOutputData("actualValues")
+  probabilities = classifierRegion.getOutputData("probabilities")
+  steps = classifierRegion.getSelf().stepsList
+
+  N = classifierRegion.getSelf().maxCategoryCount
+  results = {step: {} for step in steps}
+  for i in range(len(steps)):
+    # stepProbabilities are probabilities for this prediction step only.
+    stepProbabilities = probabilities[i * N:(i + 1) * N - 1]
+    mostLikelyCategoryIdx = stepProbabilities.argmax()
+    predictedValue = actualValues[mostLikelyCategoryIdx]
+    predictionConfidence = stepProbabilities[mostLikelyCategoryIdx]
+    results[steps[i]]["predictedValue"] = predictedValue
+    results[steps[i]]["predictionConfidence"] = predictionConfidence
+  return results

docs/examples/network/example-link-all.py

@@ -0,0 +1,32 @@
+def createDataOutLink(network, sensorRegionName, regionName):
+  """Link sensor region to other region so that it can pass it data."""
+  network.link(sensorRegionName, regionName, "UniformLink", "",
+               srcOutput="dataOut", destInput="bottomUpIn")
+
+
+def createFeedForwardLink(network, regionName1, regionName2):
+  """Create a feed-forward link between 2 regions: regionName1 -> regionName2"""
+  network.link(regionName1, regionName2, "UniformLink", "",
+               srcOutput="bottomUpOut", destInput="bottomUpIn")
+
+
+def createSensorToClassifierLinks(network, sensorRegionName, classifierRegionName):
+  """Create required links from a sensor region to a classifier region."""
+  network.link(sensorRegionName, classifierRegionName, "UniformLink", "",
+               srcOutput="bucketIdxOut", destInput="bucketIdxIn")
+  network.link(sensorRegionName, classifierRegionName, "UniformLink", "",
+               srcOutput="actValueOut", destInput="actValueIn")
+  network.link(sensorRegionName, classifierRegionName, "UniformLink", "",
+               srcOutput="categoryOut", destInput="categoryIn")
+
+
+# 1. Add data link between sensor and SP.
+createDataOutLink(network, "sensor", "SP")
+
+# 2. Add feed forward links.
+createFeedForwardLink(network, "SP", "TM")
+createFeedForwardLink(network, "TM", "classifier")
+
+# 3. Add links between sensor and classifier.
+createSensorToClassifierLinks(network, "sensor", "classifier")
+

docs/examples/network/example-run-network.py

@@ -0,0 +1,6 @@
+# Make sure all objects are initialized.
+network.initialize()
+
+N = 1  # Run the network, N iterations at a time.
+for iteration in range(0, numRecords, N):
+  network.run(N)

docs/examples/network/example-set-predicted-field.py

@@ -0,0 +1,3 @@
+predictedIdx = dataSource.getFieldNames().index("consumption")
+
+network.regions["sensor"].setParameter("predictedFieldIdx", predictedIdx)

docs/examples/network/example-yaml-import.py

@@ -0,0 +1,6 @@
+import yaml
+
+_PARAMS_PATH = "/path/to/model.yaml"
+
+with open(_PARAMS_PATH, "r") as f:
+  modelParams = yaml.safe_load(f)["modelParams"]

docs/examples/opf/example-model-param-encoders.yaml

@@ -0,0 +1,18 @@
+# List of encoders and their parameters.
+encoders:
+  consumption:
+    fieldname: consumption
+    name: consumption
+    resolution: 0.88
+    seed: 1
+    type: RandomDistributedScalarEncoder
+  timestamp_timeOfDay:
+    fieldname: timestamp
+    name: timestamp_timeOfDay
+    timeOfDay: [21, 1]
+    type: DateEncoder
+  timestamp_weekend:
+    fieldname: timestamp
+    name: timestamp_weekend
+    type: DateEncoder
+    weekend: 21