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)¶ Bases:
nupic.serializable.Serializable
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 subpar 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 pseudorandom 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
parameterParameters: 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 thanstimulusThreshold
.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).
 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