Spatial Pooler

class nupic.research.spatial_pooler.SpatialPooler(inputDimensions=(32, 32), columnDimensions=(64, 64), potentialRadius=16, potentialPct=0.5, globalInhibition=False, localAreaDensity=-1.0, numActiveColumnsPerInhArea=10.0, stimulusThreshold=0, synPermInactiveDec=0.008, synPermActiveInc=0.05, synPermConnected=0.1, minPctOverlapDutyCycle=0.001, dutyCyclePeriod=1000, boostStrength=0.0, seed=-1, spVerbosity=0, wrapAround=True)

This class implements the spatial pooler. It is in charge of handling the relationships between the columns of a region and the inputs bits. The primary public interface to this function is the “compute” method, which takes in an input vector and returns a list of activeColumns columns.

sp = SpatialPooler(...)
for line in file:
  inputVector = numpy.array(line)
  sp.compute(inputVector)
  ...

Parameters:

• inputDimensions – A sequence representing the dimensions of the input vector. Format is (height, width, depth, ...), where each value represents the size of the dimension. For a topology of one dimension with 100 inputs use 100, or (100,). For a two dimensional topology of 10x5 use (10,5).
• columnDimensions – A sequence representing the dimensions of the columns in the region. Format is (height, width, depth, ...), where each value represents the size of the dimension. For a topology of one dimension with 2000 columns use 2000, or (2000,). For a three dimensional topology of 32x64x16 use (32, 64, 16).
• potentialRadius – This parameter determines the extent of the input that each column can potentially be connected to. This can be thought of as the input bits that are visible to each column, or a ‘receptiveField’ of the field of vision. A large enough value will result in ‘global coverage’, meaning that each column can potentially be connected to every input bit. This parameter defines a square (or hyper square) area: a column will have a max square potential pool with sides of length 2 * potentialRadius + 1.
• potentialPct – The percent of the inputs, within a column’s potential radius, that a column can be connected to. If set to 1, the column will be connected to every input within its potential radius. This parameter is used to give each column a unique potential pool when a large potentialRadius causes overlap between the columns. At initialization time we choose ((2*potentialRadius + 1)^(# inputDimensions) * potentialPct) input bits to comprise the column’s potential pool.
• globalInhibition – If true, then during inhibition phase the winning columns are selected as the most active columns from the region as a whole. Otherwise, the winning columns are selected with respect to their local neighborhoods. Using global inhibition boosts performance x60.
• localAreaDensity – The desired density of active columns within a local inhibition area (the size of which is set by the internally calculated inhibitionRadius, which is in turn determined from the average size of the connected potential pools of all columns). The inhibition logic will insure that at most N columns remain ON within a local inhibition area, where N = localAreaDensity * (total number of columns in inhibition area).
• numActiveColumnsPerInhArea – An alternate way to control the density of the active columns. If numActiveColumnsPerInhArea is specified then localAreaDensity must be less than 0, and vice versa. When using numActiveColumnsPerInhArea, the inhibition logic will insure that at most ‘numActiveColumnsPerInhArea’ columns remain ON within a local inhibition area (the size of which is set by the internally calculated inhibitionRadius, which is in turn determined from the average size of the connected receptive fields of all columns). When using this method, as columns learn and grow their effective receptive fields, the inhibitionRadius will grow, and hence the net density of the active columns will decrease. This is in contrast to the localAreaDensity method, which keeps the density of active columns the same regardless of the size of their receptive fields.
• stimulusThreshold – This is a number specifying the minimum number of synapses that must be on in order for a columns to turn ON. The purpose of this is to prevent noise input from activating columns. Specified as a percent of a fully grown synapse.
• synPermInactiveDec – The amount by which an inactive synapse is decremented in each round. Specified as a percent of a fully grown synapse.
• synPermActiveInc – The amount by which an active synapse is incremented in each round. Specified as a percent of a fully grown synapse.
• synPermConnected – The default connected threshold. Any synapse whose permanence value is above the connected threshold is a “connected synapse”, meaning it can contribute to the cell’s firing.
• minPctOverlapDutyCycle – A number between 0 and 1.0, used to set a floor on how often a column should have at least stimulusThreshold active inputs. Periodically, each column looks at the overlap duty cycle of all other columns within its inhibition radius and sets its own internal minimal acceptable duty cycle to: minPctDutyCycleBeforeInh * max(other columns’ duty cycles). On each iteration, any column whose overlap duty cycle falls below this computed value will get all of its permanence values boosted up by synPermActiveInc. Raising all permanences in response to a sub-par duty cycle before inhibition allows a cell to search for new inputs when either its previously learned inputs are no longer ever active, or when the vast majority of them have been “hijacked” by other columns.
• dutyCyclePeriod – The period used to calculate duty cycles. Higher values make it take longer to respond to changes in boost or synPerConnectedCell. Shorter values make it more unstable and likely to oscillate.
• boostStrength – A number greater or equal than 0.0, used to control the strength of boosting. No boosting is applied if it is set to 0. Boosting strength increases as a function of boostStrength. Boosting encourages columns to have similar activeDutyCycles as their neighbors, which will lead to more efficient use of columns. However, too much boosting may also lead to instability of SP outputs.
• seed – Seed for our own pseudo-random number generator.
• spVerbosity – spVerbosity level: 0, 1, 2, or 3
• wrapAround – Determines if inputs at the beginning and end of an input dimension should be considered neighbors when mapping columns to inputs.

compute(inputVector, learn, activeArray)

This is the primary public method of the SpatialPooler class. This function takes a input vector and outputs the indices of the active columns. If ‘learn’ is set to True, this method also updates the permanences of the columns.

Parameters:

• inputVector – A numpy array of 0’s and 1’s that comprises the input to the spatial pooler. The array will be treated as a one dimensional array, therefore the dimensions of the array do not have to match the exact dimensions specified in the class constructor. In fact, even a list would suffice. The number of input bits in the vector must, however, match the number of bits specified by the call to the constructor. Therefore there must be a ‘0’ or ‘1’ in the array for every input bit.
• learn – A boolean value indicating whether learning should be performed. Learning entails updating the permanence values of the synapses, and hence modifying the ‘state’ of the model. Setting learning to ‘off’ freezes the SP and has many uses. For example, you might want to feed in various inputs and examine the resulting SDR’s.
• activeArray – An array whose size is equal to the number of columns. Before the function returns this array will be populated with 1’s at the indices of the active columns, and 0’s everywhere else.

getActiveDutyCycles(activeDutyCycles)

Returns the activity duty cycles for all columns. ‘activeDutyCycles’ size must match the number of columns

getBoostFactors(boostFactors)

Returns the boost factors for all columns. ‘boostFactors’ size must match the number of columns

getBoostStrength()

Returns the maximum boost value

getBoostedOverlaps()

Returns the boosted overlap score for each column.

getColumnDimensions()

Returns the dimensions of the columns in the region

getConnectedCounts(connectedCounts)

Returns the number of connected synapses for all columns. ‘connectedCounts’ size must match the number of columns

getConnectedSynapses(columnIndex, connectedSynapses)

Returns the connected synapses for a given column. ‘connectedSynapses’ size must match the number of inputs

getDutyCyclePeriod()

Returns the duty cycle period

getGlobalInhibition()

Returns whether global inhibition is enabled

getInhibitionRadius()

Returns the inhibition radius

getInputDimensions()

Returns the dimensions of the input vector

getIterationLearnNum()

Returns the learning iteration number

getIterationNum()

Returns the iteration number

getLocalAreaDensity()

Returns the local area density. Returns a value less than 0 if parameter is unused

getMinOverlapDutyCycles(minOverlapDutyCycles)

Returns the minimum overlap duty cycles for all columns. ‘_minOverlapDutyCycles’ size must match the number of columns

getMinPctOverlapDutyCycles()

Returns the minimum tolerated overlaps, given as percent of neighbors overlap score

getNumActiveColumnsPerInhArea()

Returns the number of active columns per inhibition area. Returns a value less than 0 if parameter is unused

getNumColumns()

Returns the total number of columns

getNumInputs()

Returns the total number of inputs

getOverlapDutyCycles(overlapDutyCycles)

Returns the overlap duty cycles for all columns. ‘overlapDutyCycles’ size must match the number of columns

getOverlaps()

Returns the overlap score for each column.

getPermanence(columnIndex, permanence)

Returns the permanence values for a given column. ‘permanence’ size must match the number of inputs

getPotential(columnIndex, potential)

Returns the potential mapping for a given column. ‘potential’ size must match the number of inputs

getPotentialPct()

Returns the potential percent

getPotentialRadius()

Returns the potential radius

getSpVerbosity()

Returns the verbosity level

getStimulusThreshold()

Returns the stimulus threshold

getSynPermActiveInc()

Returns the permanence increment amount for active synapses inputs

getSynPermBelowStimulusInc()

Returns the permanence increment amount for columns that have not been recently active

getSynPermConnected()

Returns the permanence amount that qualifies a synapse as being connected

getSynPermInactiveDec()

Returns the permanence decrement amount for inactive synapses

getSynPermTrimThreshold()

Returns the permanence trim threshold

getUpdatePeriod()

Returns the update period

printParameters()

Useful for debugging.

setActiveDutyCycles(activeDutyCycles)

Sets the activity duty cycles for all columns. ‘activeDutyCycles’ size must match the number of columns

setBoostFactors(boostFactors)

Sets the boost factors for all columns. ‘boostFactors’ size must match the number of columns

setBoostStrength(boostStrength)

Sets the maximum boost value

setDutyCyclePeriod(dutyCyclePeriod)

Sets the duty cycle period

setGlobalInhibition(globalInhibition)

Sets global inhibition

setInhibitionRadius(inhibitionRadius)

Sets the inhibition radius

setIterationLearnNum(iterationLearnNum)

Sets the learning iteration number

setIterationNum(iterationNum)

Sets the iteration number

setLocalAreaDensity(localAreaDensity)

Sets the local area density. Invalidates the ‘numActiveColumnsPerInhArea’ parameter

setMinOverlapDutyCycles(minOverlapDutyCycles)

Sets the minimum overlap duty cycles for all columns. ‘_minOverlapDutyCycles’ size must match the number of columns

setMinPctOverlapDutyCycles(minPctOverlapDutyCycles)

Sets the minimum tolerated activity duty cycle, given as percent of neighbors’ activity duty cycle

setNumActiveColumnsPerInhArea(numActiveColumnsPerInhArea)

Sets the number of active columns per inhibition area. Invalidates the ‘localAreaDensity’ parameter

setOverlapDutyCycles(overlapDutyCycles)

Sets the overlap duty cycles for all columns. ‘overlapDutyCycles’ size must match the number of columns

setPermanence(columnIndex, permanence)

Sets the permanence values for a given column. ‘permanence’ size must match the number of inputs

setPotential(columnIndex, potential)

Sets the potential mapping for a given column. ‘potential’ size must match the number of inputs, and must be greater than _stimulusThreshold

setPotentialPct(potentialPct)

Sets the potential percent

setPotentialRadius(potentialRadius)

Sets the potential radius

setSpVerbosity(spVerbosity)

Sets the verbosity level

setStimulusThreshold(stimulusThreshold)

Sets the stimulus threshold

setSynPermActiveInc(synPermActiveInc)

Sets the permanence increment amount for active synapses

setSynPermBelowStimulusInc(synPermBelowStimulusInc)

Sets the permanence increment amount for columns that have not been recently active

setSynPermConnected(synPermConnected)

Sets the permanence amount that qualifies a synapse as being connected

setSynPermInactiveDec(synPermInactiveDec)

Sets the permanence decrement amount for inactive synapses

setSynPermTrimThreshold(synPermTrimThreshold)

Sets the permanence trim threshold

setUpdatePeriod(updatePeriod)

Sets the update period

stripUnlearnedColumns(activeArray)

Removes the set of columns who have never been active from the set of active columns selected in the inhibition round. Such columns cannot represent learned pattern and are therefore meaningless if only inference is required. This should not be done when using a random, unlearned SP since you would end up with no active columns.

Parameters:activeArray – An array whose size is equal to the number of columns. Any columns marked as active with an activeDutyCycle of 0 have never been activated before and therefore are not active due to learning. Any of these (unlearned) columns will be disabled (set to 0).