Encoders

Classes for encoding different types into SDRs for HTM input.

Base Encoder

class nupic.encoders.base.Encoder

An encoder converts a value to a sparse distributed representation.

This is the base class for encoders that are compatible with the OPF. The OPF requires that values can be represented as a scalar value for use in places like the SDR Classifier.

Note

The Encoder superclass implements:

Warning

The following methods and properties must be implemented by subclasses:

closenessScores(expValues, actValues, fractional=True)

Compute closeness scores between the expected scalar value(s) and actual scalar value(s). The expected scalar values are typically those obtained from the getScalars() method. The actual scalar values are typically those returned from topDownCompute().

This method returns one closeness score for each value in expValues (or actValues which must be the same length). The closeness score ranges from 0 to 1.0, 1.0 being a perfect match and 0 being the worst possible match.

If this encoder is a simple, single field encoder, then it will expect just 1 item in each of the expValues and actValues arrays. Multi-encoders will expect 1 item per sub-encoder.

Each encoder type can define it’s own metric for closeness. For example, a category encoder may return either 1 or 0, if the scalar matches exactly or not. A scalar encoder might return a percentage match, etc.

Parameters:
  • expValues – Array of expected scalar values, typically obtained from getScalars()
  • actValues – Array of actual values, typically obtained from topDownCompute()
Returns:

Array of closeness scores, one per item in expValues (or actValues).
decode(encoded, parentFieldName='')

Takes an encoded output and does its best to work backwards and generate the input that would have generated it.

In cases where the encoded output contains more ON bits than an input would have generated, this routine will return one or more ranges of inputs which, if their encoded outputs were ORed together, would produce the target output. This behavior makes this method suitable for doing things like generating a description of a learned coincidence in the SP, which in many cases might be a union of one or more inputs.

If instead, you want to figure the most likely single input scalar value that would have generated a specific encoded output, use the topDownCompute() method.

If you want to pretty print the return value from this method, use the decodedToStr() method.

Parameters:
  • encoded – The encoded output that you want decode
  • parentFieldName – The name of the encoder which is our parent. This name is prefixed to each of the field names within this encoder to form the keys of the dict() in the retval.
Returns:

tuple(fieldsDict, fieldOrder)

fieldsDict is a dict() where the keys represent field names (only 1 if this is a simple encoder, > 1 if this is a multi or date encoder) and the values are the result of decoding each field. If there are no bits in encoded that would have been generated by a field, it won’t be present in the dict. The key of each entry in the dict is formed by joining the passed in parentFieldName with the child encoder name using a ‘.’.

Each ‘value’ in fieldsDict consists of (ranges, desc), where ranges is a list of one or more (minVal, maxVal) ranges of input that would generate bits in the encoded output and ‘desc’ is a pretty print description of the ranges. For encoders like the category encoder, the ‘desc’ will contain the category names that correspond to the scalar values included in the ranges.

fieldOrder is a list of the keys from fieldsDict, in the same order as the fields appear in the encoded output.

TODO: when we switch to Python 2.7 or 3.x, use OrderedDict

Example retvals for a scalar encoder:

{'amount':  ( [[1,3], [7,10]], '1-3, 7-10' )}
{'amount':  ( [[2.5,2.5]],     '2.5'       )}

Example retval for a category encoder:

{'country': ( [[1,1], [5,6]], 'US, GB, ES' )}

Example retval for a multi encoder:

{'amount':  ( [[2.5,2.5]],     '2.5'       ),
 'country': ( [[1,1], [5,6]],  'US, GB, ES' )}
decodedToStr(decodeResults)

Return a pretty print string representing the return value from decode().

encode(inputData)

Convenience wrapper for encodeIntoArray().

This may be less efficient because it allocates a new numpy array every call.

Parameters:inputData – input data to be encoded
Returns:a numpy array with the encoded representation of inputData
encodeIntoArray(inputData, output)

Encodes inputData and puts the encoded value into the numpy output array, which is a 1-D array of length returned by getWidth().

Note

The numpy output array is reused, so clear it before updating it.

Parameters:
  • inputData – Data to encode. This should be validated by the encoder.
  • output – numpy 1-D array of same length returned by getWidth().
encodedBitDescription(bitOffset, formatted=False)

Return a description of the given bit in the encoded output. This will include the field name and the offset within the field.

Parameters:
  • bitOffset – Offset of the bit to get the description of
  • formatted – If True, the bitOffset is w.r.t. formatted output, which includes separators
Returns:

tuple(fieldName, offsetWithinField)
getBucketIndices(inputData)

Returns an array containing the sub-field bucket indices for each sub-field of the inputData. To get the associated field names for each of the buckets, call getScalarNames().

Parameters:inputData – The data from the source. This is typically an object with members.
Returns:array of bucket indices
getBucketInfo(buckets)

Returns a list of EncoderResult namedtuples describing the inputs for each sub-field that correspond to the bucket indices passed in buckets. To get the associated field names for each of the values, call getScalarNames().

Parameters:buckets – The list of bucket indices, one for each sub-field encoder. These bucket indices for example may have been retrieved from the getBucketIndices() call.
Returns:A list of EncoderResult.
getBucketValues()

Must be overridden by subclasses.

Returns a list of items, one for each bucket defined by this encoder. Each item is the value assigned to that bucket, this is the same as the EncoderResult.value that would be returned by getBucketInfo() for that bucket and is in the same format as the input that would be passed to encode().

This call is faster than calling getBucketInfo() on each bucket individually if all you need are the bucket values.

Returns:list of items, each item representing the bucket value for that bucket.
getDecoderOutputFieldTypes()

Returns a sequence of field types corresponding to the elements in the decoded output field array. The types are defined by FieldMetaType.

Returns:list of FieldMetaType objects
getDescription()

Must be overridden by subclasses.

This returns a list of tuples, each containing (name, offset). The name is a string description of each sub-field, and offset is the bit offset of the sub-field for that encoder.

For now, only the ‘multi’ and ‘date’ encoders have multiple (name, offset) pairs. All other encoders have a single pair, where the offset is 0.

Returns:list of tuples containing (name, offset)
getDisplayWidth()

Calculate width of display for bits plus blanks between fields.

Returns:(int) width of display for bits plus blanks between fields
getEncodedValues(inputData)

Returns the input in the same format as is returned by topDownCompute(). For most encoder types, this is the same as the input data. For instance, for scalar and category types, this corresponds to the numeric and string values, respectively, from the inputs. For datetime encoders, this returns the list of scalars for each of the sub-fields (timeOfDay, dayOfWeek, etc.)

This method is essentially the same as getScalars() except that it returns strings.

Parameters:inputData – The input data in the format it is received from the data source
Returns:A list of values, in the same format and in the same order as they are returned by topDownCompute().
getEncoderList()
Returns:a reference to each sub-encoder in this encoder. They are returned in the same order as they are for getScalarNames() and getScalars().
getFieldDescription(fieldName)

Return the offset and length of a given field within the encoded output.

Parameters:fieldName – Name of the field
Returns:tuple(offset, width) of the field within the encoded output
getScalarNames(parentFieldName='')

Return the field names for each of the scalar values returned by getScalars.

Parameters:parentFieldName – The name of the encoder which is our parent. This name is prefixed to each of the field names within this encoder to form the keys of the dict() in the retval.
Returns:array of field names
getScalars(inputData)

Returns a numpy array containing the sub-field scalar value(s) for each sub-field of the inputData. To get the associated field names for each of the scalar values, call getScalarNames().

For a simple scalar encoder, the scalar value is simply the input unmodified. For category encoders, it is the scalar representing the category string that is passed in. For the datetime encoder, the scalar value is the the number of seconds since epoch.

The intent of the scalar representation of a sub-field is to provide a baseline for measuring error differences. You can compare the scalar value of the inputData with the scalar value returned from topDownCompute() on a top-down representation to evaluate prediction accuracy, for example.

Parameters:inputData – The data from the source. This is typically an object with members
Returns:array of scalar values
getWidth()

Should return the output width, in bits.

Returns:(int) output width in bits
pprint(output, prefix='')

Pretty-print the encoded output using ascii art.

Parameters:
  • output – to print
  • prefix – printed before the header if specified
pprintHeader(prefix='')

Pretty-print a header that labels the sub-fields of the encoded output. This can be used in conjuction with pprint().

Parameters:prefix – printed before the header if specified
scalarsToStr(scalarValues, scalarNames=None)

Return a pretty print string representing the return values from getScalars() and getScalarNames().

Parameters:
  • scalarValues – input values to encode to string
  • scalarNames – optional input of scalar names to convert. If None, gets scalar names from getScalarNames()
Returns:

string representation of scalar values
setFieldStats(fieldName, fieldStatistics)

This method is called by the model to set the statistics like min and max for the underlying encoders if this information is available.

Parameters:
  • fieldName – name of the field this encoder is encoding, provided by MultiEncoder.
  • fieldStatistics – dictionary of dictionaries with the first level being the fieldname and the second index the statistic ie: fieldStatistics['pounds']['min']
setLearning(learningEnabled)

Set whether learning is enabled.

Parameters:learningEnabled – (bool) whether learning should be enabled
setStateLock(lock)

Setting this to true freezes the state of the encoder This is separate from the learning state which affects changing parameters. Implemented in subclasses.

topDownCompute(encoded)

Returns a list of EncoderResult namedtuples describing the top-down best guess inputs for each sub-field given the encoded output. These are the values which are most likely to generate the given encoded output. To get the associated field names for each of the values, call getScalarNames().

Parameters:encoded – The encoded output. Typically received from the topDown outputs from the spatial pooler just above us.
Returns:A list of EncoderResult

Encoder Result

class nupic.encoders.base.EncoderResult(value, scalar, encoding)

Tuple to represent the results of computations in different forms.

value

A representation of the encoded value in the same format as the input (i.e. float for scalars, string for categories). This is the value for the sub-field in a format that is consistent with the type specified by getDecoderOutputFieldTypes(). Note that this value is not necessarily numeric.

scalar

The scalar representation of value (e.g. for categories, this is the internal index used by the encoder). This number is consistent with what is returned by getScalars(). This value is always an int or float, and can be used for numeric comparisons.

encoding

This is the encoded bit-array (numpy array) that represents value. That is, if value was passed to encode(), an identical bit-array should be returned.

Category Encoders

class nupic.encoders.category.CategoryEncoder(w, categoryList, name='category', verbosity=0, forced=False)

Bases: nupic.encoders.base.Encoder

Encodes a list of discrete categories (described by strings), that aren’t related to each other, so we never emit a mixture of categories.

The value of zero is reserved for “unknown category”

Internally we use a ScalarEncoder with a radius of 1, but since we only encode integers, we never get mixture outputs.

The SDRCategoryEncoder uses a different method to encode categories.

Parameters:
  • categoryList – list of discrete string categories
  • forced – if True, skip checks for parameters’ settings; see ScalarEncoder for details. (default False)
class nupic.encoders.sdr_category.SDRCategoryEncoder(n, w, categoryList=None, name='category', verbosity=0, encoderSeed=1, forced=False)

Bases: nupic.encoders.base.Encoder

Encodes a list of discrete categories (described by strings), that aren’t related to each other.

Each encoding is an SDR in which w out of n bits are turned on.

Unknown categories are encoded as a single value.

Internally we use a ScalarEncoder with a radius of 1, but since we only encode integers, we never get mixture outputs.

The CategoryEncoder uses a different method to encode categories

Parameters:
  • categoryList – list of discrete string categories, if None then categories will automatically be added as they are encountered
  • forced – if True, skip checks for parameters’ settings; see ScalarEncoder for details. (default False)

Scalar Encoders

class nupic.encoders.scalar.ScalarEncoder(w, minval, maxval, periodic=False, n=0, radius=0, resolution=0, name=None, verbosity=0, clipInput=False, forced=False)

Bases: nupic.encoders.base.Encoder

A scalar encoder encodes a numeric (floating point) value into an array of bits. The output is 0’s except for a contiguous block of 1’s. The location of this contiguous block varies continuously with the input value.

The encoding is linear. If you want a nonlinear encoding, just transform the scalar (e.g. by applying a logarithm function) before encoding. It is not recommended to bin the data as a pre-processing step, e.g. “1” = $0 - $.20, “2” = $.21-$0.80, “3” = $.81-$1.20, etc. as this removes a lot of information and prevents nearby values from overlapping in the output. Instead, use a continuous transformation that scales the data (a piecewise transformation is fine).

Warning

There are three mutually exclusive parameters that determine the overall size of of the output. Exactly one of n, radius, resolution must be set. “0” is a special value that means “not set”.

Parameters:
  • w – The number of bits that are set to encode a single value - the “width” of the output signal restriction: w must be odd to avoid centering problems.
  • minval – The minimum value of the input signal.
  • maxval – The upper bound of the input signal. (input is strictly less if periodic == True)
  • periodic – If true, then the input value “wraps around” such that minval = maxval. For a periodic value, the input must be strictly less than maxval, otherwise maxval is a true upper bound.
  • n – The number of bits in the output. Must be greater than or equal to w
  • radius – Two inputs separated by more than the radius have non-overlapping representations. Two inputs separated by less than the radius will in general overlap in at least some of their bits. You can think of this as the radius of the input.
  • resolution – Two inputs separated by greater than, or equal to the resolution are guaranteed to have different representations.
  • name – an optional string which will become part of the description
  • clipInput – if true, non-periodic inputs smaller than minval or greater than maxval will be clipped to minval/maxval
  • forced – if true, skip some safety checks (for compatibility reasons), default false

Note

radius and resolution are specified with respect to the input, not output. w is specified with respect to the output.

Example: day of week

w = 3
Minval = 1 (Monday)
Maxval = 8 (Monday)
periodic = true
n = 14
[equivalently: radius = 1.5 or resolution = 0.5]

The following values would encode midnight – the start of the day

monday (1)   -> 11000000000001
tuesday(2)   -> 01110000000000
wednesday(3) -> 00011100000000
...
sunday (7)   -> 10000000000011

Since the resolution is 12 hours, we can also encode noon, as

monday noon  -> 11100000000000
monday midnt-> 01110000000000
tuesday noon -> 00111000000000
etc.

`n` vs `resolution`

It may not be natural to specify “n”, especially with non-periodic data. For example, consider encoding an input with a range of 1-10 (inclusive) using an output width of 5. If you specify resolution = 1, this means that inputs of 1 and 2 have different outputs, though they overlap, but 1 and 1.5 might not have different outputs. This leads to a 14-bit representation like this:

1 ->  11111000000000  (14 bits total)
2 ->  01111100000000
...
10->  00000000011111
[resolution = 1; n=14; radius = 5]

You could specify resolution = 0.5, which gives

1   -> 11111000... (22 bits total)
1.5 -> 011111.....
2.0 -> 0011111....
[resolution = 0.5; n=22; radius=2.5]

You could specify radius = 1, which gives

1   -> 111110000000....  (50 bits total)
2   -> 000001111100....
3   -> 000000000011111...
...
10  ->                           .....000011111
[radius = 1; resolution = 0.2; n=50]

An N/M encoding can also be used to encode a binary value, where we want more than one bit to represent each state. For example, we could have: w = 5, minval = 0, maxval = 1, radius = 1 (which is equivalent to n=10)

0 -> 1111100000
1 -> 0000011111

Implementation details

range = maxval - minval
h = (w-1)/2  (half-width)
resolution = radius / w
n = w * range/radius (periodic)
n = w * range/radius + 2 * h (non-periodic)
class nupic.encoders.adaptive_scalar.AdaptiveScalarEncoder(w, minval=None, maxval=None, periodic=False, n=0, radius=0, resolution=0, name=None, verbosity=0, clipInput=True, forced=False)

Bases: nupic.encoders.scalar.ScalarEncoder

This is an implementation of the scalar encoder that adapts the min and max of the scalar encoder dynamically. This is essential to the streaming model of the online prediction framework.

Initialization of an adapive encoder using resolution or radius is not supported; it must be intitialized with n. This n is kept constant while the min and max of the encoder changes.

The adaptive encoder must be have periodic set to false.

The adaptive encoder may be initialized with a minval and maxval or with None for each of these. In the latter case, the min and max are set as the 1st and 99th percentile over a window of the past 100 records.

Note: the sliding window may record duplicates of the values in the dataset, and therefore does not reflect the statistical distribution of the input data and may not be used to calculate the median, mean etc.

For params, see ScalarEncoder.

Raises:Exception if input is periodic.
class nupic.encoders.random_distributed_scalar.RandomDistributedScalarEncoder(resolution, w=21, n=400, name=None, offset=None, seed=42, verbosity=0)

Bases: nupic.encoders.base.Encoder

A scalar encoder encodes a numeric (floating point) value into an array of bits.

This class maps a scalar value into a random distributed representation that is suitable as scalar input into the spatial pooler. The encoding scheme is designed to replace a simple ScalarEncoder. It preserves the important properties around overlapping representations. Unlike ScalarEncoder the min and max range can be dynamically increased without any negative effects. The only required parameter is resolution, which determines the resolution of input values.

Scalar values are mapped to a bucket. The class maintains a random distributed encoding for each bucket. The following properties are maintained by RandomDistributedEncoder:

1) Similar scalars should have high overlap. Overlap should decrease smoothly as scalars become less similar. Specifically, neighboring bucket indices must overlap by a linearly decreasing number of bits.

2) Dissimilar scalars should have very low overlap so that the SP does not confuse representations. Specifically, buckets that are more than w indices apart should have at most maxOverlap bits of overlap. We arbitrarily (and safely) define “very low” to be 2 bits of overlap or lower.

Properties 1 and 2 lead to the following overlap rules for buckets i and j:

If abs(i-j) < w then:
  overlap(i,j) = w - abs(i-j)
else:
  overlap(i,j) <= maxOverlap

3) The representation for a scalar must not change during the lifetime of the object. Specifically, as new buckets are created and the min/max range is extended, the representation for previously in-range sscalars and previously created buckets must not change.

Parameters:
  • resolution – A floating point positive number denoting the resolution of the output representation. Numbers within [offset-resolution/2, offset+resolution/2] will fall into the same bucket and thus have an identical representation. Adjacent buckets will differ in one bit. resolution is a required parameter.
  • w – Number of bits to set in output. w must be odd to avoid centering problems. w must be large enough that spatial pooler columns will have a sufficiently large overlap to avoid false matches. A value of w=21 is typical.
  • n – Number of bits in the representation (must be > w). n must be large enough such that there is enough room to select new representations as the range grows. With w=21 a value of n=400 is typical. The class enforces n > 6*w.
  • name – An optional string which will become part of the description.
  • offset – A floating point offset used to map scalar inputs to bucket indices. The middle bucket will correspond to numbers in the range [offset - resolution/2, offset + resolution/2). If set to None, the very first input that is encoded will be used to determine the offset.
  • seed – The seed used for numpy’s random number generator. If set to -1 the generator will be initialized without a fixed seed.
  • verbosity – An integer controlling the level of debugging output. A value of 0 implies no output. verbosity=1 may lead to one-time printouts during construction, serialization or deserialization. verbosity=2 may lead to some output per encode operation. verbosity>2 may lead to significantly more output.
mapBucketIndexToNonZeroBits(index)

Given a bucket index, return the list of non-zero bits. If the bucket index does not exist, it is created. If the index falls outside our range we clip it.

:param index The bucket index to get non-zero bits for. @returns numpy array of indices of non-zero bits for specified index.

class nupic.encoders.delta.DeltaEncoder(w, minval=None, maxval=None, periodic=False, n=0, radius=0, resolution=0, name=None, verbosity=0, clipInput=True, forced=False)

Bases: nupic.encoders.adaptive_scalar.AdaptiveScalarEncoder

This is an implementation of a delta encoder. The delta encoder encodes differences between successive scalar values instead of encoding the actual values. It returns an actual value when decoding and not a delta.

class nupic.encoders.logarithm.LogEncoder(w=5, minval=1e-07, maxval=10000, periodic=False, n=0, radius=0, resolution=0, name='log', verbosity=0, clipInput=True, forced=False)

Bases: nupic.encoders.base.Encoder

This class wraps the ScalarEncoder.

A Log encoder represents a floating point value on a logarithmic scale.

valueToEncode = log10(input)
Parameters:
  • resolution – The minimum change in scaled value needed to produce a change in encoding. This should be specified in log space. For example, the scaled values 10 and 11 will be distinguishable in the output. In terms of the original input values, this means 10^1 (1) and 10^1.1 (1.25) will be distinguishable.
  • radius – inputs separated by more than this distance in log space will have non-overlapping representations

Date Encoder

class nupic.encoders.date.DateEncoder(season=0, dayOfWeek=0, weekend=0, holiday=0, timeOfDay=0, customDays=0, name='', forced=True)

Bases: nupic.encoders.base.Encoder

A date encoder encodes a date according to encoding parameters specified in its constructor. The input to a date encoder is a datetime.datetime object. The output is the concatenation of several sub-encodings, each of which encodes a different aspect of the date. Which sub-encodings are present, and details of those sub-encodings, are specified in the DateEncoder constructor.

Each parameter describes one attribute to encode. By default, the attribute is not encoded.

Parameters:
  • season –

    (int | tuple) Season of the year, where units = day.

    • (int) width of attribute; default radius = 91.5 days (1 season)
    • (tuple) season[0] = width; season[1] = radius
  • dayOfWeek –

    (int | tuple) Day of week, where monday = 0, units = 1 day.

    • (int) width of attribute; default radius = 1 day
    • (tuple) dayOfWeek[0] = width; dayOfWeek[1] = radius
  • weekend –

    (int) Is a weekend or not. A block of bits either 0s or 1s.

    • (int) width of attribute
  • holiday –

    (int) Is a holiday or not, boolean: 0, 1

    • (int) width of attribute
  • timeOfday –

    (int | tuple) Time of day, where midnight = 0, units = hour.

    • (int) width of attribute: default radius = 4 hours
    • (tuple) timeOfDay[0] = width; timeOfDay[1] = radius
  • customDays –

    (tuple) A way to custom encode specific days of the week.

    • [0] (int) Width of attribute
    • [1] (str | list) Either a string representing a day of the week like “Monday” or “mon”, or a list of these strings.
  • forced – (default True) if True, skip checks for parameters’ settings. See ScalarEncoder for details.
getScalars(input)

See method description in getScalars().

Parameters:input – (datetime) representing the time being encoded
Returns:A numpy array of the corresponding scalar values in the following order: season, dayOfWeek, weekend, holiday, timeOfDay. Some of these fields might be omitted if they were not specified in the encoder.

Coordinate Encoders

class nupic.encoders.coordinate.CoordinateEncoder(w=21, n=1000, name=None, verbosity=0)

Bases: nupic.encoders.base.Encoder

Given a coordinate in an N-dimensional space, and a radius around that coordinate, the Coordinate Encoder returns an SDR representation of that position.

The Coordinate Encoder uses an N-dimensional integer coordinate space. For example, a valid coordinate in this space is (150, -49, 58), whereas an invalid coordinate would be (55.4, -5, 85.8475).

It uses the following algorithm:

  1. Find all the coordinates around the input coordinate, within the specified radius.
  2. For each coordinate, use a uniform hash function to deterministically map it to a real number between 0 and 1. This is the “order” of the coordinate.
  3. Of these coordinates, pick the top W by order, where W is the number of active bits desired in the SDR.
  4. For each of these W coordinates, use a uniform hash function to deterministically map it to one of the bits in the SDR. Make this bit active.
  5. This results in a final SDR with exactly W bits active (barring chance hash collisions).
class nupic.encoders.geospatial_coordinate.GeospatialCoordinateEncoder(scale, timestep, w=21, n=1000, name=None, verbosity=0)

Bases: nupic.encoders.coordinate.CoordinateEncoder

Given a GPS coordinate and a speed reading, the Geospatial Coordinate Encoder returns an SDR representation of that position.

Param:scale (int) Scale of the map, as measured by distance between two coordinates (in meters per dimensional unit)
Param:timestep (int) Time between readings (in seconds)
coordinateForPosition(longitude, latitude, altitude=None)

Returns coordinate for given GPS position.

Param:longitude (float) Longitude of position
Param:latitude (float) Latitude of position
Param:altitude (float) Altitude of position
Returns:(numpy.array) Coordinate that the given GPS position maps to
radiusForSpeed(speed)

Returns radius for given speed.

Tries to get the encodings of consecutive readings to be adjacent with some overlap.

Param:speed (float) Speed (in meters per second)
Returns:(int) Radius for given speed

Multi Encoder

class nupic.encoders.multi.MultiEncoder(encoderDefinitions=None)

Bases: nupic.encoders.base.Encoder

A MultiEncoder encodes a dictionary or object with multiple components. A MultiEncoder contains a number of sub-encoders, each of which encodes a separate component.

Parameters:encoderDefinitions – a dict of dicts, mapping field names to the field params dict. Sent directly to addMultipleEncoders().
addEncoder(name, encoder)

Adds one encoder.

Parameters:
  • name – (string) name of encoder, should be unique
  • encoder – (Encoder) the encoder to add
addMultipleEncoders(fieldEncodings)
Parameters:fieldEncodings –

dict of dicts, mapping field names to the field params dict.

Each field params dict has the following keys:

  1. fieldname: data field name
  2. type an encoder type
  3. All other keys are encoder parameters

For example,

fieldEncodings={
    'dateTime': dict(fieldname='dateTime', type='DateEncoder',
                     timeOfDay=(5,5)),
    'attendeeCount': dict(fieldname='attendeeCount', type='ScalarEncoder',
                          name='attendeeCount', minval=0, maxval=250,
                          clipInput=True, w=5, resolution=10),
    'consumption': dict(fieldname='consumption',type='ScalarEncoder',
                        name='consumption', minval=0,maxval=110,
                        clipInput=True, w=5, resolution=5),
}

would yield a vector with a part encoded by the DateEncoder, and to parts seperately taken care of by the ScalarEncoder with the specified parameters. The three seperate encodings are then merged together to the final vector, in such a way that they are always at the same location within the vector.

Pass Through Encoders

Used to pass raw SDRs through to the algorithms when data is already encoded.

class nupic.encoders.pass_through.PassThroughEncoder(n, w=None, name='pass_through', forced=False, verbosity=0)

Bases: nupic.encoders.base.Encoder

Pass an encoded SDR straight to the model.

Each encoding is an SDR in which w out of n bits are turned on. The input should be a 1-D array or numpy.ndarray of length n

Parameters:
  • n – the total #bits in output
  • w – used to normalize the sparsity of the output, exactly w bits ON, if None (default) - do not alter the input, just pass it further.
  • forced – if forced, encode will accept any data, and just return it back
closenessScores(expValues, actValues, **kwargs)

Does a bitwise compare of the two bitmaps and returns a fractonal value between 0 and 1 of how similar they are.

  • 1 => identical
  • 0 => no overlaping bits

kwargs will have the keyword “fractional”, which is assumed by this encoder.

class nupic.encoders.sparse_pass_through.SparsePassThroughEncoder(n, w=None, name='sparse_pass_through', forced=False, verbosity=0)

Bases: nupic.encoders.pass_through.PassThroughEncoder

Convert a bitmap encoded as array indices to an SDR.

Each encoding is an SDR in which w out of n bits are turned on. The input should be an array or string of indices to turn on.

Note: the value for n must equal input length * w, for example:

for n=8 w=1 [0,2,5] => 101001000

or:

for n=8 w=1 "0,2,5" => 101001000

and:

for n=24 w=3 [0,2,5] => 111000111000000111000000000

or:

for n=24 w=3 "0,2,5" => 111000111000000111000000000