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:

• __init__
• initialize
• compute

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:

• getSpec (class method)
• setParameter
• setParameterArray
• getOutputElementCount

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:

• getParameter
• getParameterArray
• getParameterArrayCount
• executeMethod

compute(inputs, outputs)

Perform the main computation

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

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.

filePath: 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.

methodName: 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)

Return the number of elements in the output of a single node

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.

name: the name of the output

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.

name: name of requested parameter index: 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.

name: name of requested parameter index: index of node inside the region (if relevant) array: output numpy array that the value is written to

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.

name: name of requested parameter index: index of node inside the region (if relevant)

static getProtoType()

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.

classmethod getSpec()

Returns the region spec for this region. The Region Spec is a dictionary with the following keys: description – a string

singleNodeOnly – a boolean (True if this Region supports only a single node)

inputs – a dictionary in which the keys are the names of the inputs and the values are dictionaries with these keys:

description - string regionLevel – True if this is a “region-level” input. dataType - a string describing the data type, usually ‘Real32’ count - the number of items in the input. 0 means unspecified. required – boolean - whether the input is must be connected isDefaultInput – must be True for exactly one input requireSplitterMap – [just set this to False.]

outputs – a dictionary with similar structure to inputs. The keys are:

description dataType count regionLevel isDefaultOutput

parameters – a dictionary of dictionaries with the following keys:

description dataType count constraints (optional) accessMode (one of “ReadWrite”, “Read”, “Create”)

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

guardedCompute(inputs, outputs)

The C++ entry point to compute.

inputs: dict of numpy arrays (one per input) outputs: dict of numpy arrays (one per output)

initialize(inputs, outputs)

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.

inputs: dict of numpy arrays (one per input) outputs: dict of numpy arrays (one per output)

classmethod read(proto)

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

proto: PyRegionProto capnproto object

classmethod readFromProto(proto)

Read state from proto object.

The type of proto is determined by getProtoType().

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.

filePath: 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.

name: name of requested parameter index: index of node inside the region (if relevant) value: the value to assign to the requested parameter

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.

name: name of requested parameter index: index of node inside the region (if relevant) array: the value to assign to the requested parameter (a numpy array)

write(proto)

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

proto: PyRegionProto capnproto object

writeToProto(proto)

Write state to proto object.

The type of proto is determined by getProtoType().

AnomalyRegion

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

Bases: nupic.bindings.regions.PyRegion.PyRegion

Region for computing the anomaly score.

SPRegion

class nupic.regions.SPRegion.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. This node has just one SpatialPooler instance for the enitire level and does not support the concept of “baby nodes” within it.

Automatic parameter handling:

Parameter names, default values, and descriptions are retrieved automatically from SpatialPooler. Thus, there are only a few hardcoded arguments in __init__, and the rest are passed to the appropriate underlying class. The NodeSpec is mostly built automatically from these parameters, too.

If you add a parameter to SpatialPooler, it will be exposed through SPRegion automatically as if it were in SPRegion.__init__, with the right default value. Add an entry in the __init__ docstring for it too, and that will be brought into the NodeSpec. SPRegion will maintain the parameter as its own instance variable and also pass it to SpatialPooler. If the parameter is changed, SPRegion will propagate the change.

If you want to do something different with the parameter, add it as an argument into SPRegion.__init__, which will override all the default handling.

compute(inputs, outputs)

Run one iteration of SPRegion’s compute, profiling it if requested.

The guts of the compute are contained in the _compute() call so that we can profile it if requested.

getAlgorithmInstance()

Returns instance of the underlying SpatialPooler algorithm object.

classmethod getBaseSpec()

Return the base Spec for SPRegion.

Doesn’t include the spatial, temporal and other parameters

getParameter(parameterName, index=-1)

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

static getProtoType()

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

classmethod getSpec()

Return the Spec for SPRegion.

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

classmethod readFromProto(proto)

Read state from proto object.

proto: SPRegionProto capnproto object

setParameter(parameterName, index, parameterValue)

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)

Write state to proto object.

proto: SPRegionProto capnproto object

TPRegion

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

Bases: nupic.bindings.regions.PyRegion.PyRegion

TPRegion is designed to implement the temporal pooler compute for a given CLA level.

Uses a subclass of TP to do most of the work. The specific TP implementation is specified using the temporalImp parameter.

Automatic parameter handling:

Parameter names, default values, and descriptions are retrieved automatically from the temporal pooler class. Thus, there are only a few hardcoded arguments in __init__, and the rest are passed to the appropriate underlying class. The RegionSpec is mostly built automatically from these parameters.

If you add a parameter to a TP class, it will be exposed through TPRegion automatically as if it were in TPRegion.__init__, with the right default value. Add an entry in the __init__ docstring for it too, and that will be brought into the RegionSpec. TPRegion will maintain the parameter as its own instance variable and also pass it to the temporal pooler instance. If the parameter is changed, TPRegion will propagate the change.

If you want to do something different with the parameter, add it as an argument into TPRegion.__init__, which will override all the default handling.

compute(inputs, outputs)

Run one iteration of TPRegion’s compute, profiling it if requested.

The guts of the compute are contained in the _compute() call so that we can profile it if requested.

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.

filePath: full filepath and name

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()

Return the base Spec for TPRegion.

Doesn’t include the spatial, temporal and other parameters

getParameter(parameterName, index=-1)

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.

classmethod getSpec()

Return the Spec for TPRegion.

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

resetSequenceStates()

Resets the region’s sequence states

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.

filePath: full filepath and name

setParameter(parameterName, index, parameterValue)

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.

AnomalyLikelihoodRegion

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

Bases: nupic.bindings.regions.PyRegion.PyRegion

Region for computing the anomaly likelihoods.

CLAClassifierRegion

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

Bases: nupic.bindings.regions.PyRegion.PyRegion

CLAClassifierRegion implements a CLA specific 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.

When learning, for every bit in activation pattern, it records a history of the classification each time that bit was active. The history is bounded by a maximum allowed age so that old entries are thrown away.

For inference, it takes an ensemble approach. For every active bit in the activationPattern, it looks up the most likely classification(s) from the history stored for that bit and then votes across these to get the resulting classification(s).

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.

compute(inputs, outputs)

Process one input sample. This method is called by the runtime engine. @param inputs – inputs of the classifier region @param outputs – outputs of the classifier region

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: The method customCompute() is here to maintain backward compatibility. This method is deprecated, and will be removed. Use network.run() instead, which will call the compute() method.

recordNum: 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

retval: 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 bucketIdx 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 instance of the underlying CLAClassifier algorithm object.

getOutputElementCount(outputName)

Returns the width of dataOut.

getOutputValues(outputName)

Return the dictionary of output values. Note that these are normal Python lists, rather than numpy arrays. This is to support lists with mixed scalars and strings, as in the case of records with categorical variables

getParameter(name, index=-1)

Get the value of the parameter.

@param name – the name of the parameter to retrieve, as defined

by the Node Spec.

static getProtoType()

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

classmethod readFromProto(proto)

Read state from proto object.

proto: CLAClassifierRegionProto capnproto object

setParameter(name, index, value)

Set the value of the parameter.

@param name – the name of the parameter to update, as defined

by the Node Spec.

@param value – the value to which the parameter is to be set.

writeToProto(proto)

Write state to proto object.

proto: CLAClassifierRegionProto capnproto object

KNNAnomalyClassifierRegion

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

Bases: nupic.bindings.regions.PyRegion.PyRegion

KNNAnomalyClassifierRegion wraps the KNNClassifierRegion to classify clamodel 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:

compute() - called by clamodel during record processing getLabels() - return points with classification records addLabel() - add a set label to a given set of points removeLabels() - remove labels from a given set of points

Parameters:

trainRecords - number of records to skip before classification anomalyThreshold - threshold on anomaly score to automatically classify

record as an anomaly

cacheSize - number of records to keep in cache. Can only recalculate

records kept in cache when setting the trainRecords.

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.

classifyState(state)

Reclassifies given state.

classifyStates()

Reclassifies all internal state

compute(inputs, outputs)

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

constructClassificationRecord(inputs)

Construct a _CLAClassificationRecord based on the state of the model passed in through the inputs.

Types for self.classificationVectorType:

1 - TP active cells in learn state 2 - SP columns concatenated with error from TP column predictions and SP

getLabelResults()

Get the labels of the previously computed record.

retval - array 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.

reval - dict of 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

}

getParameter(name, index=-1)

Get the value of the parameter.

@param name – the name of the parameter to retrieve, as defined

by the Node Spec.

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 eqaul to labelFilter.

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

setParameter(name, index, value)

Set the value of the parameter.

@param name – the name of the parameter to update, as defined

by the Node Spec.

@param value – the value to which the parameter is to be set.

KNNClassifierRegion

class nupic.regions.KNNClassifierRegion.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.

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

disableTap()

Disable writing of output tap files.

doInference(activeInput)

Explicitly run inference on a vector that is passed in and return the category id. Useful for debugging.

enableTap(tapPath)

Begin writing output tap files.

@param tapPath – base name of the output tap files to write.

getAlgorithmInstance()

Returns instance of the underlying KNNClassifier algorithm object.

getAllDistances()

Return all the prototype distances from all computes available.

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

getCategoryList()

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

It returns an array 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.

It returns an array 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)

This method will be called only when the node is used in nuPIC 2

getParameter(name, index=-1)

Get the value of the parameter.

@param name – the name of the parameter to retrieve, as defined

by the Node Spec.

handleLogInput(inputs)

Write inputs to output tap file.

handleLogOutput(output)

Write outputs to output tap file.

setParameter(name, index, value)

Set the value of the parameter.

@param name – the name of the parameter to update, as defined

by the Node Spec.

@param value – the value to which the parameter is to be set.

SDRClassifierRegion

class nupic.regions.SDRClassifierRegion.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.

compute(inputs, outputs)

Process one input sample. This method is called by the runtime engine. @param inputs – inputs of the classifier region @param outputs – outputs of the classifier region

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: The method customCompute() is here to maintain backward compatibility. This method is deprecated, and will be removed. Use network.run() instead, which will call the compute() method.

recordNum: 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

retval: 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 bucketIdx 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 instance of the underlying SDRClassifier algorithm object.

getOutputElementCount(outputName)

Returns the number of output elements.

getParameter(name, index=-1)

Get the value of the parameter.

@param name – the name of the parameter to retrieve, as defined

by the Node Spec.

static getProtoType()

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

initialize(inputs, outputs)

Is called once by NuPIC before the first call to compute(). Initializes self._sdrClassifier is it is not already initialized. @param inputs – inputs of the classifier region @param outputs – outputs of the classifier region

classmethod readFromProto(proto)

Read state from proto object.

proto: SDRClassifierRegionProto capnproto object

setParameter(name, index, value)

Set the value of the parameter.

@param name – the name of the parameter to update, as defined

by the Node Spec.

@param value – the value to which the parameter is to be set.

writeToProto(proto)

Write state to proto object.

proto: SDRClassifierRegionProto capnproto object