Regions

PyRegion

class nupic.bindings.regions.PyRegion.PyRegion(*args, **kwars)

PyRegion provides services to its sub-classes (the actual regions):

  • Define and document the interface of a Python region
  • Enforce implementation of required methods
  • Default implementation for some methods

PyRegion is an abstract base class (http://docs.python.org/library/abc.html). If a subclass doesn’t implement all its abstract methods it can’t be instantiated. Note, that the signature of implemented abstract method in the subclass doesn’t need to match the signature of the abstract method in the base class. This is very important for __init__() in this case.

The abstract methods (decorated with @abstract method) are:

In addition, some PyRegion methods raise NotImplementedError which throws an exception if called. A sub-class may opt not to implement these methods, but if such a methods is called then a NotImplementedError will be raised. This is useful for methods like setParameterArray() if a particular subclass has no array parameters.

The not implemented methods are:

The getSpec() is a class method, which is actually required but since it’s not an instance method the @abstractmethod decorator doesn’t apply.

Finally, PyRegion provides reasonable default implementation to some methods. Sub-classes may opt to override these methods or use the default implementation (often recommended).

The implemented methods are:

compute(inputs, outputs)

Perform the main computation.

This method is called in each iteration for each phase the node supports.

Parameters:
  • inputs – (dict) of numpy arrays (one per input)
  • outputs – (dict) of numpy arrays (one per output)
deSerializeExtraData(filePath)

This method is called during network deserialization with an external filename that can be used to bypass pickle for loading large binary states.

Parameters:filePath – (string) full filepath and name
executeMethod(methodName, args)

Executes a method named methodName with the specified arguments.

This method is called when the user executes a command as defined in the node spec. It provides a perfectly reasonble implementation of the command mechanism. As a sub-class developer you just need to implement a method for each command in the node spec. Note that due to the command mechanism only unnamed argument are supported.

Parameters:
  • methodName – (string) the name of the method that correspond to a command in the spec.
  • args – (list) of arguments that will be passed to the method
getOutputElementCount(name)

If the region has multiple nodes (all must have the same output size) then just the number of output elements of a single node should be returned.

Parameters:name – (string) the name of the output
Returns:(int) number of elements in the output of a single node.
getParameter(name, index)

Default implementation that return an attribute with the requested name.

This method provides a default implementation of getParameter() that simply returns an attribute with the parameter name. If the Region conceptually contains multiple nodes with separate state, the index argument is used to request a parameter of a specific node inside the region. In case of a region-level parameter the index should be -1.

The implementation prevents accessing parameters names that start with _. It may be better to enforce this convention at the node spec level.

Parameters:
  • name – (string) name of requested parameter
  • index – (int) index of node inside the region (if relevant)
getParameterArray(name, index, array)

Default implementation that return an attribute with the requested name.

This method provides a default implementation of getParameterArray() that returns an attribute with the parameter name. If the Region conceptually contains multiple nodes with separate state the index argument is used to request a parameter of a specific node inside the region. The attribute value is written into the output array. No type or sanity checks are performed for performance reasons. If something goes awry it will result in a low-level exception. If you are unhappy about it you can implement your own getParameterArray() method in the subclass.

The implementation prevents accessing parameters names that start with _. It may be better to enforce this convention at the node spec level.

Parameters:
  • name – (string) name of requested parameter
  • index – (int) index of node inside the region (if relevant)
  • array – output numpy array that the value is written to
Raises:

Exception if parameter starts with _.
getParameterArrayCount(name, index)

Default implementation that return the length of the attribute.

This default implementation goes hand in hand with getParameterArray(). If you override one of them in your subclass, you should probably override both of them.

The implementation prevents accessing parameters names that start with _. It may be better to enforce this convention at the node spec level.

Parameters:
  • name – (string) name of requested parameter
  • index – (int) index of node inside the region (if relevant)
Raises:

Exception if parameter starts with _.
static getSchema()

Return the pycapnp proto type that the class uses for serialization.

This is used to convert the proto into the proper type before passing it into the read or write method of the subclass.

Returns:PyRegionProto prototype object
Raises:NotImplementedError if function is not implemented in subclass
classmethod getSpec()

This class method is called by NuPIC before creating a Region.

Returns:(dict) the region spec for this region. Keys described below:
  • description (string) user-provided description
  • singleNodeOnly (bool) True if this Region supports only a single node
  • inputs (dict) keys are the names of the inputs and the values are dictionaries with these keys:
    • description (string) user-provided description
    • regionLevel (bool) True if this is a “region-level” input
    • dataType (string) describing the data type, usually Real32
    • count (int) items in the input. 0 means unspecified.
    • required (bool) whether the input is must be connected
    • isDefaultInput (bool) must be True for exactly one input
    • requireSplitterMap (bool) [just set this to False.]
  • outputs (dict) similar structure to inputs. The keys are:
    • description
    • dataType
    • count
    • regionLevel
    • isDefaultOutput
  • parameters (dict) of dicts with the following keys:
    • description
    • dataType
    • count
    • constraints (optional)
    • accessMode (one of “ReadWrite”, “Read”, “Create”)
guardedCompute(inputs, outputs)

The C++ entry point to compute.

Parameters:
  • inputs – (dict) of numpy arrays (one per input)
  • outputs – (dict) of numpy arrays (one per output)
initialize()

Initialize the node after the network is fully linked It is called once by NuPIC before the first call to compute(). It is a good place to perform one time initialization that depend on the inputs and/or outputs. The region may also remember its inputs and outputs here because they will not change.

classmethod read(proto)

Calls readFromProto() on subclass after converting proto to specific type using getSchema().

Parameters:proto – PyRegionProto capnproto object
classmethod readFromProto(proto)

Read state from proto object.

The type of proto is determined by getSchema().

Raises:NotImplementedError if function is not implemented in subclass
serializeExtraData(filePath)

This method is called during network serialization with an external filename that can be used to bypass pickle for saving large binary states.

Parameters:filePath – (string) full filepath and name
setParameter(name, index, value)

Set the value of a parameter.

If the Region conceptually contains multiple nodes with separate state the index argument is used set a parameter of a specific node inside the region.

Parameters:
  • name – (string) name of requested parameter
  • index – (int) index of node inside the region (if relevant)
  • value – (object) the value to assign to the requested parameter
Raises:

NotImplementedError if function is not implemented in subclass
setParameterArray(name, index, array)

Set the value of an array parameter

If the Region conceptually contains multiple nodes with separate state the ‘index’ argument is used set a parameter of a specific node inside the region.

Parameters:
  • name – (string) name of requested parameter
  • index – (int) index of node inside the region (if relevant)
  • array – the value to assign to the requested parameter (a numpy array)
Raises:

NotImplementedError if function is not implemented in subclass
write(proto)

Calls writeToProto() on subclass after converting proto to specific type using getSchema().

Parameters:proto – PyRegionProto capnproto object
writeToProto(proto)

Write state to proto object.

The type of proto is determined by getSchema().

Raises:NotImplementedError if function is not implemented in subclass

AnomalyRegion

class nupic.regions.anomaly_region.AnomalyRegion(*args, **kwargs)

Bases: nupic.bindings.regions.PyRegion.PyRegion, nupic.serializable.Serializable

Region for computing the anomaly score.

SPRegion

class nupic.regions.sp_region.SPRegion(columnCount, inputWidth, spatialImp='cpp', **kwargs)

Bases: nupic.bindings.regions.PyRegion.PyRegion

SPRegion is designed to implement the spatial pooler compute for a given HTM level.

Uses the SpatialPooler class to do most of the work.

Parameters:
  • columnCount – (int) Number of columns in the SP, a required parameter.
  • inputWidth – (int) Size of inputs to the SP, a required parameter.
  • spatialImp – (string) py or cpp` (default ``cpp).
compute(inputs, outputs)

Run one iteration, profiling it if requested.

Parameters:
  • inputs – (dict) mapping region input names to numpy.array values
  • outputs – (dict) mapping region output names to numpy.arrays that should be populated with output values by this method
getAlgorithmInstance()
Returns:(SpatialPooler) instance of the underlying algorithm object.
classmethod getBaseSpec()

Doesn’t include the spatial, temporal and other parameters

Returns:(dict) The base Spec for SPRegion.
getParameter(parameterName, index=-1)

Overrides getParameter().

Most parameters are handled automatically by PyRegion’s parameter get mechanism. The ones that need special treatment are explicitly handled here.

getParameterArray(name, index, a)

Overrides getParameterArray().

TODO: as a temporary hack, getParameterArray checks to see if there’s a variable, private or not, with that name. If so, it returns the value of the variable.

getParameterArrayCount(name, index)

Overrides getParameterArrayCount().

TODO: as a temporary hack, getParameterArrayCount checks to see if there’s a variable, private or not, with that name. If so, it returns the value of the variable.

static getSchema()

Overrides getSchema().

classmethod getSpec()

Overrides getSpec().

The parameters collection is constructed based on the parameters specified by the various components (spatialSpec, temporalSpec and otherSpec)

initialize()

Overrides initialize().

classmethod readFromProto(proto)

Overrides readFromProto().

Read state from proto object.

Parameters:proto – SPRegionProto capnproto object
setParameter(parameterName, index, parameterValue)

Overrides setParameter().

Set the value of a Spec parameter. Most parameters are handled automatically by PyRegion’s parameter set mechanism. The ones that need special treatment are explicitly handled here.

writeToProto(proto)

Overrides writeToProto().

Write state to proto object.

Parameters:proto – SPRegionProto capnproto object

TMRegion

class nupic.regions.tm_region.TMRegion(columnCount, inputWidth, cellsPerColumn, orColumnOutputs=False, cellsSavePath='', temporalImp='py', anomalyMode=False, computePredictedActiveCellIndices=False, **kwargs)

Bases: nupic.bindings.regions.PyRegion.PyRegion

TMRegion is designed to implement the temporal memory compute for a given HTM level.

Uses a form of Temporal Memory to do most of the work. The specific TM implementation is specified using the temporalImp parameter.

compute(inputs, outputs)

Run one iteration of TMRegion compute, profiling it if requested.

Parameters:
  • inputs – (dict) mapping region input names to numpy.array values
  • outputs – (dict) mapping region output names to numpy.arrays that should be populated with output values by this method
deSerializeExtraData(filePath)

Overrides deSerializeExtraData().

This method is called during network deserialization with an external filename that can be used to bypass pickle for loading large binary states.

Parameters:filePath – (string) absolute file path
finishLearning()

Perform an internal optimization step that speeds up inference if we know learning will not be performed anymore. This call may, for example, remove all potential inputs to each column.

getAlgorithmInstance()
Returns:instance of the underlying TemporalMemory algorithm object.
classmethod getBaseSpec()

Doesn’t include the spatial, temporal and other parameters

Returns:(dict) the base Spec for TMRegion.
getOutputElementCount(name)

Overrides getOutputElementCount().

getParameter(parameterName, index=-1)

Overrides getParameter().

Get the value of a parameter. Most parameters are handled automatically by PyRegion‘s parameter get mechanism. The ones that need special treatment are explicitly handled here.

getParameterArray(name, index, a)

Overrides getParameterArray().

getParameterArrayCount(name, index)

Overrides getParameterArrayCount().

static getSchema()

Overrides getSchema().

classmethod getSpec()

Overrides getSpec().

The parameters collection is constructed based on the parameters specified by the various components (spatialSpec, temporalSpec and otherSpec)

initialize()

Overrides initialize().

classmethod readFromProto(proto)

Overrides readFromProto().

Read state from proto object.

Parameters:proto – TMRegionProto capnproto object
resetSequenceStates()

Resets the region’s sequence states.

serializeExtraData(filePath)

Overrides serializeExtraData().

setParameter(parameterName, index, parameterValue)

Overrides setParameter().

writeToProto(proto)

Overrides writeToProto().

Write state to proto object.

Parameters:proto – TMRegionProto capnproto object

AnomalyLikelihoodRegion

class nupic.regions.anomaly_likelihood_region.AnomalyLikelihoodRegion(learningPeriod=288, estimationSamples=100, historicWindowSize=8640, reestimationPeriod=100)

Bases: nupic.bindings.regions.PyRegion.PyRegion, nupic.serializable.Serializable

Region for computing the anomaly likelihoods.

KNNAnomalyClassifierRegion

class nupic.regions.knn_anomaly_classifier_region.KNNAnomalyClassifierRegion(trainRecords, anomalyThreshold, cacheSize, classificationVectorType=1, activeColumnCount=40, classificationMaxDist=0.3, **classifierArgs)

Bases: nupic.bindings.regions.PyRegion.PyRegion

Wraps the KNNClassifierRegion to classify HTMPredictionModel state. It allows for individual records to be classified as anomalies and supports anomaly detection even after the model has learned the anomalous sequence.

Methods:

Parameters:
  • trainRecords – (int) number of records to skip before classification.
  • anomalyThreshold – (float) threshold on anomaly score to automatically classify record as an anomaly
  • cacheSize – (int) number of records to keep in cache. Can only recalculate records kept in cache when setting the trainRecords.
  • classificationVectorType – (int) default=1
  • activeColumnCount – (int) default=40,
  • classificationMaxDist – (float) default=0.30
addLabel(start, end, labelName)

Add the label labelName to each record with record ROWID in range from start to end, noninclusive of end.

This will recalculate all points from end to the last record stored in the internal cache of this classifier.

Parameters:
  • start – (int) start index
  • end – (int) end index (noninclusive)
  • labelName – (string) label name
compute(inputs, outputs)

Process one input sample. This method is called by the runtime engine.

getLabelResults()

Get the labels of the previously computed record.

Returns:(list) of strings representing the classification labels
getLabels(start=None, end=None)

Get the labels on classified points within range start to end. Not inclusive of end.

Returns:(dict) with format:
{
  'isProcessing': boolean,
  'recordLabels': list of results
}

isProcessing - currently always false as recalculation blocks; used if reprocessing of records is still being performed;

Each item in recordLabels is of format:

{
  'ROWID': id of the row,
  'labels': list of strings
}
getOutputElementCount(name)

Overrides nupic.bindings.regions.PyRegion.PyRegion.getOutputElementCount().

getParameter(name, index=-1)

Overrides nupic.bindings.regions.PyRegion.PyRegion.getParameter().

classmethod getSpec()

Overrides nupic.bindings.regions.PyRegion.PyRegion.getSpec().

removeLabels(start=None, end=None, labelFilter=None)

Remove labels from each record with record ROWID in range from start to end, noninclusive of end. Removes all records if labelFilter is None, otherwise only removes the labels equal to labelFilter.

This will recalculate all points from end to the last record stored in the internal cache of this classifier.

Parameters:
  • start – (int) start index
  • end – (int) end index (noninclusive)
  • labelFilter – (string) label filter
setParameter(name, index, value)

Overrides nupic.bindings.regions.PyRegion.PyRegion.setParameter().

KNNClassifierRegion

class nupic.regions.knn_classifier_region.KNNClassifierRegion(maxCategoryCount=0, bestPrototypeIndexCount=0, outputProbabilitiesByDist=False, k=1, distanceNorm=2.0, distanceMethod='norm', distThreshold=0.0, doBinarization=False, inputThresh=0.5, useSparseMemory=True, sparseThreshold=0.0, relativeThreshold=False, winnerCount=0, acceptanceProbability=1.0, seed=42, doSphering=False, SVDSampleCount=0, SVDDimCount=0, fractionOfMax=0, useAuxiliary=0, justUseAuxiliary=0, verbosity=0, replaceDuplicates=False, cellsPerCol=0, maxStoredPatterns=-1, minSparsity=0.0)

Bases: nupic.bindings.regions.PyRegion.PyRegion

KNNClassifierRegion implements the k Nearest Neighbor classification algorithm. By default it will implement vanilla 1-nearest neighbor using the L2 (Euclidean) distance norm. There are options for using different norms as well as various ways of sparsifying the input.

Note

categories are ints >= 0.

Parameters:
  • maxCategoryCount – (int)
  • bestPrototypeIndexCount – (int)
  • outputProbabilitiesByDist – (bool)
  • k – (int)
  • distanceNorm – (float)
  • distanceMethod – (string)
  • distThreshold – (float)
  • doBinarization – (bool)
  • inputThresh – (float)
  • useSparseMemory – (bool)
  • sparseThreshold – (float)
  • relativeThreshold – (bool)
  • winnerCount – (int)
  • acceptanceProbability – (float)
  • seed – (int)
  • doSphering – (bool)
  • SVDSampleCount – (int)
  • SVDDimCount – (int)
  • fractionOfMax – (int)
  • useAuxiliary – (int)
  • justUseAuxiliary – (int)
  • verbosity – (int)
  • replaceDuplicates – (bool)
  • cellsPerCol – (int)
  • maxStoredPatterns – (int)
  • minSparsity – (float)
compute(inputs, outputs)

Process one input sample. This method is called by the runtime engine.

Note

the number of input categories may vary, but the array size is fixed to the max number of categories allowed (by a lower region), so “unused” indices of the input category array are filled with -1s.

TODO: confusion matrix does not support multi-label classification

Parameters:
  • inputs – (dict) mapping region input names to numpy.array values
  • outputs – (dict) mapping region output names to numpy.arrays that should be populated with output values by this method
disableTap()

Disable writing of output tap files.

enableTap(tapPath)

Begin writing output tap files.

Parameters:tapPath – (string) base name of the output tap files to write.
getAlgorithmInstance()
Returns:(KNNClassifier)
getAllDistances()

Like getLatestDistances(), but returns all the scores if more than one set is available. getLatestDistances() will always just return one set of scores.

Returns:(list) all the prototype distances from all computes available.
getCategoryList()

Public API for returning the category list. This is a required API of the NearestNeighbor inspector.

Returns:(list) which has one entry per stored prototype. The value of the entry is the category # of that stored prototype.
getLatestDistances()

Public API for returning the full scores (distance to each prototype) from the last compute() inference call. This is a required API of the NearestNeighbor inspector.

Returns:(list) which has one entry per stored prototype. The value of the entry is distance of the most recenty inferred input from the stored prototype.
getOutputElementCount(name)

Overrides nupic.bindings.regions.PyRegion.PyRegion.getOutputElementCount().

getParameter(name, index=-1)

Overrides nupic.bindings.regions.PyRegion.PyRegion.getParameter().

classmethod getSpec()

Overrides nupic.bindings.regions.PyRegion.PyRegion.getSpec().

handleLogInput(inputs)

Write inputs to output tap file.

Parameters:inputs – (iter) some inputs.
handleLogOutput(output)

Write outputs to output tap file.

Parameters:outputs – (iter) some outputs.
removeCategory(categoryToRemove)

Removes a category.

Parameters:categoryToRemove – (string) label to remove
reset()

Resets confusion matrix.

setParameter(name, index, value)

Overrides nupic.bindings.regions.PyRegion.PyRegion.setParameter().

SDRClassifierRegion

class nupic.regions.sdr_classifier_region.SDRClassifierRegion(steps='1', alpha=0.001, verbosity=0, implementation=None, maxCategoryCount=None)

Bases: nupic.bindings.regions.PyRegion.PyRegion

SDRClassifierRegion implements a SDR classifier that accepts a binary input from the level below (the “activationPattern”) and information from the sensor and encoders (the “classification”) describing the input to the system at that time step.

The SDR classifier maps input patterns to class labels. There are as many output units as the number of class labels or buckets (in the case of scalar encoders). The output is a probabilistic distribution over all class labels.

During inference, the output is calculated by first doing a weighted summation of all the inputs, and then perform a softmax nonlinear function to get the predicted distribution of class labels

During learning, the connection weights between input units and output units are adjusted to maximize the likelihood of the model

The caller can choose to tell the region that the classifications for iteration N+K should be aligned with the activationPattern for iteration N. This results in the classifier producing predictions for K steps in advance. Any number of different K’s can be specified, allowing the classifier to learn and infer multi-step predictions for a number of steps in advance.

Parameters:
  • steps – (int) default=1
  • alpha – (float) default=0.001
  • verbosity – (int) How verbose to log, default=0
  • implementation – (string) default=None
  • maxCategoryCount – (int) default=None
compute(inputs, outputs)

Process one input sample. This method is called by the runtime engine.

Parameters:
  • inputs – (dict) mapping region input names to numpy.array values
  • outputs – (dict) mapping region output names to numpy.arrays that should be populated with output values by this method
customCompute(recordNum, patternNZ, classification)

Just return the inference value from one input sample. The actual learning happens in compute() – if, and only if learning is enabled – which is called when you run the network.

Warning

This method is deprecated and exists only to maintain backward compatibility. This method is deprecated, and will be removed. Use nupic.engine.Network.run() instead, which will call compute().

Parameters:
  • recordNum – (int) Record number of the input sample.
  • patternNZ – (list) of the active indices from the output below
  • classification –

    (dict) of the classification information:

    • bucketIdx: index of the encoder bucket
    • actValue: actual value going into the encoder
Returns:

(dict) containing inference results, one entry for each step in self.steps. The key is the number of steps, the value is an array containing the relative likelihood for each bucketIdx starting from 0.

For example:

{'actualValues': [0.0, 1.0, 2.0, 3.0]
  1 : [0.1, 0.3, 0.2, 0.7]
  4 : [0.2, 0.4, 0.3, 0.5]}

getAlgorithmInstance()
Returns:(nupic.regions.sdr_classifier_region.SDRClassifierRegion)
getOutputElementCount(outputName)

Overrides nupic.bindings.regions.PyRegion.PyRegion.getOutputElementCount().

getParameter(name, index=-1)

Overrides nupic.bindings.regions.PyRegion.PyRegion.getParameter().

static getSchema()
Returns:the pycapnp proto type that the class uses for serialization.
classmethod getSpec()

Overrides nupic.bindings.regions.PyRegion.PyRegion.getSpec().

initialize()

Overrides nupic.bindings.regions.PyRegion.PyRegion.initialize().

Is called once by NuPIC before the first call to compute(). Initializes self._sdrClassifier if it is not already initialized.

classmethod readFromProto(proto)

Read state from proto object.

Parameters:proto – SDRClassifierRegionProto capnproto object
setParameter(name, index, value)

Overrides nupic.bindings.regions.PyRegion.PyRegion.setParameter().

writeToProto(proto)

Write state to proto object.

Parameters:proto – SDRClassifierRegionProto capnproto object