Spatial Pooling

class nupic.algorithms.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 – (iter) 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). Default (32, 32).
• columnDimensions – (iter) 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). Default ``(64, 64).
• potentialRadius – (int) 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. Default 16.
• potentialPct – (float) 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. Default 0.5.
• globalInhibition – (bool) 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. Default False.
• localAreaDensity – (float) 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). Default -1.0.
• numActiveColumnsPerInhArea – (float) 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. Default 10.0.
• stimulusThreshold – (int) 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. Default 0.
• synPermInactiveDec – (float) The amount by which an inactive synapse is decremented in each round. Specified as a percent of a fully grown synapse. Default 0.008.
• synPermActiveInc – (float) The amount by which an active synapse is incremented in each round. Specified as a percent of a fully grown synapse. Default 0.05.
• synPermConnected – (float) 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. Default 0.1.
• minPctOverlapDutyCycle – (float) 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. Default 0.001.
• dutyCyclePeriod – (int) 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. Default 1000.
• boostStrength – (float) 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. Default 0.0.
• seed – (int) Seed for our own pseudo-random number generator. Default -1.
• spVerbosity – (int) spVerbosity level: 0, 1, 2, or 3. Default 0.
• wrapAround – (bool) Determines if inputs at the beginning and end of an input dimension should be considered neighbors when mapping columns to inputs. Default True.

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)

Gets the activity duty cycles for all columns. Input list will be overwritten.

Parameters:activeDutyCycles – (list) size must match number of columns.

getBoostFactors(boostFactors)

Gets the boost factors for all columns. Input list will be overwritten.

Parameters:boostFactors – (list) size must match number of columns.

getBoostStrength()

Returns:(float) the maximum boost value used.

getBoostedOverlaps()

Returns:(list) the boosted overlap score for each column.

getColumnDimensions()

Returns:(iter) the dimensions of the columns in the region

getConnectedCounts(connectedCounts)

Parameters:connectedCounts – (list) will be overwritten Returns:(int) the number of connected synapses for all columns. connectedCounts size must match the number of columns.

getConnectedSynapses(columnIndex, connectedSynapses)

Parameters:connectedSynapses – (list) will be overwritten Returns:(iter) the connected synapses for a given column. connectedSynapses size must match the number of inputs

getDutyCyclePeriod()

Returns:(int) the duty cycle period

getGlobalInhibition()

Returns:(bool) whether global inhibition is enabled.

getInhibitionRadius()

Returns:(int) the inhibition radius

getInputDimensions()

Returns:(iter) the dimensions of the input vector

getIterationLearnNum()

Returns:(int) The number of iterations that have been learned.

getIterationNum()

Returns:the iteration number

getLocalAreaDensity()

Returns:(float) the local area density. Returns a value less than 0 if parameter is unused.

getMinOverlapDutyCycles(minOverlapDutyCycles)

Returns:(list) the minimum overlap duty cycles for all columns. minOverlapDutyCycles size must match the number of columns.

getMinPctOverlapDutyCycles()

Returns:(float) the minimum tolerated overlaps, given as percent of neighbors overlap score

getNumActiveColumnsPerInhArea()

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

getNumColumns()

Returns:(int) the total number of columns

getNumInputs()

Returns:(int) the total number of inputs.

getOverlapDutyCycles(overlapDutyCycles)

Gets the overlap duty cycles for all columns. overlapDutyCycles size must match the number of columns.

Parameters:overlapDutyCycles – (list) will be overwritten.

getOverlaps()

Returns:(iter) 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.

Parameters:

• columnIndex – (int) column index to get permanence for.
• permanence – (list) will be overwritten with permanences.

getPotential(columnIndex, potential)

Parameters:

• columnIndex – (int) column index to get potential for.
• potential – (list) will be overwritten with column potentials. Must match the number of inputs.

getPotentialPct()

Returns:(float) the potential percent

getPotentialRadius()

Returns:(float) the potential radius

getSpVerbosity()

Returns:(int) the verbosity level, larger is more verbose.

getStimulusThreshold()

Returns:(int) the stimulus threshold

getSynPermActiveInc()

Returns:(float) the permanence increment amount for active synapses inputs

getSynPermBelowStimulusInc()

Returns:(float) the permanence increment amount for columns that have not been recently active.

getSynPermConnected()

Returns:(float) the permanence amount that qualifies a synapse as being connected.

getSynPermInactiveDec()

Returns:(float) the permanence decrement amount for inactive synapses.

getSynPermTrimThreshold()

Sparsity is enforced by trimming out all permanence values below this value.

Returns:(float) the permanence trim threshold

getUpdatePeriod()

Returns:(int) The period at which active duty cycles are updated.

printParameters()

Useful for debugging.

setActiveDutyCycles(activeDutyCycles)

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

Parameters:activeDutyCycles – (list) value to set.

setBoostFactors(boostFactors)

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

Parameters:boostFactors – (iter) value to set.

setBoostStrength(boostStrength)

Sets the maximum boost value. :param boostStrength: (float) value to set

setDutyCyclePeriod(dutyCyclePeriod)

Parameters:dutyCyclePeriod – (int) value to set.

setGlobalInhibition(globalInhibition)

Parameters:globalInhibition – (bool) value to set.

setInhibitionRadius(inhibitionRadius)

Parameters:inhibitionRadius – (int) value to set

setIterationLearnNum(iterationLearnNum)

Parameters:iterationLearnNum – (int) value to set

setIterationNum(iterationNum)

Parameters:iterationNum – (int) value to set

setLocalAreaDensity(localAreaDensity)

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

Parameters:localAreaDensity – (float) value to set

setMinOverlapDutyCycles(minOverlapDutyCycles)

Sets the minimum overlap duty cycles for all columns. minOverlapDutyCycles size must match the number of columns.

Parameters:minOverlapDutyCycles – (iter) value to set.

setMinPctOverlapDutyCycles(minPctOverlapDutyCycles)

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

Parameters:minPctOverlapDutyCycles – (float) value to set.

setNumActiveColumnsPerInhArea(numActiveColumnsPerInhArea)

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

Parameters:numActiveColumnsPerInhArea – (float) value to set

setOverlapDutyCycles(overlapDutyCycles)

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

Parameters:overlapDutyCycles – (list) value to set.

setPermanence(columnIndex, permanence)

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

Parameters:

• columnIndex – (int) column index to set permanence for.
• permanence – (list) value to set.

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.

Parameters:

• columnIndex – (int) column index to set potential for.
• potential – (list) value to set.

setPotentialPct(potentialPct)

Parameters:potentialPct – (float) value to set

setPotentialRadius(potentialRadius)

Parameters:potentialRadius – (float) value to set

setSpVerbosity(spVerbosity)

Parameters:spVerbosity – (int) value to set, larger is more verbose.

setStimulusThreshold(stimulusThreshold)

Parameters:stimulusThreshold – (float) value to set.

setSynPermActiveInc(synPermActiveInc)

Sets the permanence increment amount for active synapses.

Parameters:synPermActiveInc – (float) value to set.

setSynPermBelowStimulusInc(synPermBelowStimulusInc)

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

Parameters:synPermBelowStimulusInc – (float) value to set.

setSynPermConnected(synPermConnected)

Sets the permanence amount that qualifies a synapse as being connected.

Parameters:synPermConnected – (float) value to set.

setSynPermInactiveDec(synPermInactiveDec)

Sets the permanence decrement amount for inactive synapses.

Parameters:synPermInactiveDec – (float) value to set.

setSynPermTrimThreshold(synPermTrimThreshold)

Sparsity is enforced by trimming out all permanence values below this value.

Parameters:synPermTrimThreshold – (float) the permanence trim threshold

setUpdatePeriod(updatePeriod)

Parameters:updatePeriod – (int) The period at which active duty cycles are updated.

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