pyactup 2.1__tar.gz → 2.2__tar.gz

{pyactup-2.1 → pyactup-2.2}/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.1
 Name: pyactup
-Version: 2.1
+Version: 2.2
 Summary: A lightweight Python implementation of a subset of the ACT-R cognitive architecture’s Declarative Memory
 Home-page: https://bitbucket.org/dfmorrison/pyactup/
 Author: Don Morrison
 Author-email: dfm2@cmu.edu
-License: UNKNOWN
 Platform: any
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -56,5 +55,3 @@ PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIG
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
 OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-

{pyactup-2.1 → pyactup-2.2}/pyactup.egg-info/PKG-INFO

@@ -1,11 +1,10 @@
 Metadata-Version: 2.1
 Name: pyactup
-Version: 2.1
+Version: 2.2
 Summary: A lightweight Python implementation of a subset of the ACT-R cognitive architecture’s Declarative Memory
 Home-page: https://bitbucket.org/dfmorrison/pyactup/
 Author: Don Morrison
 Author-email: dfm2@cmu.edu
-License: UNKNOWN
 Platform: any
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -56,5 +55,3 @@ PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIG
 HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE
 OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
-
-

{pyactup-2.1 → pyactup-2.2}/pyactup.py

@@ -37,7 +37,7 @@ may be strictly algorithmic, may interact with human subjects, or may be embedde
 sites.
 """
 
-__version__ = "2.1"
+__version__ = "2.2"
 
 if "dev" in __version__:
     print("PyACTUp version", __version__)
@@ -47,7 +47,6 @@ import csv
 import io
 import math
 import numpy as np
-import numpy.ma as ma
 import operator
 import random
 import re
@@ -214,7 +213,7 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"color": "red"})
-        True
+        <Chunk 0000 {'color': 'red'} 1>
         >>> m.advance()
         1
         >>> m.activation_history = []
@@ -342,11 +341,11 @@ class Memory(dict):
 
         >>> m = Memory(temperature=1, noise=0)
         >>> m.learn({"size": 1})
-        True
+        <Chunk 0000 {'size': 1} 1>
         >>> m.advance(10)
         10
         >>> m.learn({"size": 10})
-        True
+        <Chunk 0001 {'size': 10} 1>
         >>> m.advance()
         11
         >>> m.blend("size")
@@ -653,11 +652,11 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"color": "red", "size": 3})
-        True
+        <Chunk 0005 {'color': 'red', 'size': 3} 1>
         >>> m.advance()
         1
         >>> m.learn({"color": "red", "size": 5})
-        True
+        <Chunk 0006 {'color': 'red', 'size': 5} 1>
         >>> m.advance()
         2
         >>> m.activation_history = []
@@ -684,7 +683,6 @@ class Memory(dict):
           'activation_noise': 0.4191470689622754,
           'activation': 0.4191470689622754,
           'retrieval_probability': 0.905269525909957}]
-
         """
         return self._activation_history
 
@@ -778,16 +776,16 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"color":"red", "size":4})
-        True
+        <Chunk 0000 {'color': 'red', 'size': 4} 1>
         >>> m.advance()
         1
         >>> m.learn({"color":"blue", "size":4}, advance=1)
+        <Chunk 0001 {'color': 'blue', 'size': 4} 1>
+        >>> m.learn({"color":"red", "size":4}) is None
         True
-        >>> m.learn({"color":"red", "size":4})
-        False
         >>> m.advance()
         3
-        >>> m.retrieve({"color": "red"})
+        >>>
         <Chunk 0000 {'color': 'red', 'size': 4} 2>
         """
         slots = self._ensure_slots(slots, True)
@@ -954,9 +952,9 @@ class Memory(dict):
                                   - self._decay * np.log(ages))
                     else:
                         result = np.empty(nchunks)
-                        counts = ma.masked_all(nchunks)
-                        ages = ma.masked_all(nchunks)
-                        middles = ma.masked_all(nchunks)
+                        counts = np.ma.masked_all(nchunks)
+                        ages = np.ma.masked_all(nchunks)
+                        middles = np.ma.masked_all(nchunks)
                         for c, i in zip(chunks, count()):
                             if c._reference_count <= self._optimized_learning:
                                 result[i] = np.sum((self._time - c._references[0:c._reference_count])
@@ -1011,6 +1009,12 @@ class Memory(dict):
                     penalties = np.empty((nchunks, len(partial_slots)))
                     for c, row in zip(chunks, count()):
                         penalties[row] = [s._similarity(c[n], v) for n, v, s in partial_slots]
+                    if self._activation_history is not None:
+                        offset = 0 if self.use_actr_similarity else 1
+                        for i, pens in zip(count(initial_history_length), penalties):
+                            similarities = {ps[0]: p + offset
+                                            for ps, p in zip(partial_slots, pens)}
+                            self._activation_history[i]["similarities"] = similarities
                     penalties = np.sum(penalties, 1) * self._mismatch
                     result += penalties
                     if self._activation_history is not None:
@@ -1034,9 +1038,9 @@ class Memory(dict):
                             self._activation_history[i]["meets_threshold"] = (r >= self._threshold)
                 raw_activations_count = len(result)
                 if self._threshold is not None:
-                    m = ma.masked_less(result, self._threshold)
-                    if ma.is_masked(m):
-                        chunks = ma.array(chunks, mask=ma.getmask(m)).compressed()
+                    m = np.ma.masked_less(result, self._threshold)
+                    if np.ma.is_masked(m):
+                        chunks = np.ma.array(chunks, mask=np.ma.getmask(m)).compressed()
                         result = m.compressed()
             except FloatingPointError as e:
                 raise RuntimeError(f"Error when computing activations, perhaps a chunk's "
@@ -1065,11 +1069,11 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"widget":"thromdibulator", "color":"red", "size":2})
-        True
+        <Chunk 0000 {'widget': 'thromdibulator', 'color': 'red', 'size': 2} 1>
         >>> m.advance()
         1
         >>> m.learn({"widget":"snackleizer", "color":"blue", "size":1})
-        True
+        <Chunk 0001 {'widget': 'snackleizer', 'color': 'blue', 'size': 1} 1>
         >>> m.advance()
         2
         >>> m.retrieve({"color":"blue"})["widget"]
@@ -1094,60 +1098,123 @@ class Memory(dict):
             self._cite(result)
         return result
 
-    def _blend(self, outcome_attribute, slots):
+    def _blend(self, outcome_attribute, slots, instance_salience, feature_salience):
         Memory._ensure_slot_name(outcome_attribute)
         activations, chunks, raw = self._activations(self._ensure_slots(slots),
                                                      extra=outcome_attribute)
         if chunks is None:
-            return None, None
+            return None, None, None, None
         with np.errstate(divide="raise", over="raise", under="ignore", invalid="raise"):
             wp = np.exp(activations / self._temperature)
             wp /= np.sum(wp)
-            if self._activation_history is not None:
-                h = self._activation_history
-                # this i malarkey is in case one or more candidates didn't clear the threshold
-                i = len(h) - raw
-                for p, c in zip(wp, chunks):
-                    while h[i]["name"] != c._name:
-                        i += 1
-                        assert i < len(h)
-                    h[i]["retrieval_probability"] = p
-        return wp, chunks
-
-    def blend(self, outcome_attribute, slots={}):
+        if self._activation_history is not None:
+            h = self._activation_history
+            # this i malarkey is in case one or more candidates didn't clear the threshold
+            i = len(h) - raw
+            for p, c in zip(wp, chunks):
+                while h[i]["name"] != c._name:
+                    i += 1
+                    assert i < len(h)
+                h[i]["retrieval_probability"] = p
+        def normalize(v):
+            v = np.array(v)
+            norm = np.linalg.norm(v)
+            return v / norm if norm > 0 else v
+        isal = None
+        if instance_salience:
+            vals = np.array([c[outcome_attribute] for c in chunks])
+            isal = normalize(wp * (vals - np.sum(wp * vals)) / self._temperature)
+        fsal = None
+        if feature_salience and self._mismatch is not None:
+            pslots = [a for a in slots if self._similarities.get(a)]
+            if self._mismatch != 0:
+                def slot_salience(attr, attrval):
+                    deriv = self._similarities[attr]._derivative
+                    weight = self._similarities[attr]._weight
+                    if not deriv:
+                        raise RuntimeError(f"No derivative defined for {attr} similarities")
+                    dvals = np.array([weight * deriv(c[attr], attrval) for c in chunks])
+                    dsum = np.sum(wp * dvals)
+                    return np.sum(wp * (dvals - dsum) * np.array([c[outcome_attribute]
+                                                                  for c in chunks]))
+                # Doing the division up front could make for loss of precision
+                # but this is unlikely to matter in any realistic use case.
+                coef = self._mismatch / self._temperature
+                fsal = [coef * slot_salience(a, slots[a]) for a in pslots]
+            else:
+                fsal = [0] * len(pslots)
+            fsal = dict(zip(pslots, normalize(fsal)))
+        return wp, chunks, isal, fsal
+
+    def blend(self, outcome_attribute, slots={}, instance_salience=False, feature_salience=False):
         """Returns a blended value for the given attribute of those chunks matching *slots*, and which contain *outcome_attribute*, and have activations greater than or equal to this Memory's threshold, if any.
         Returns ``None`` if there are no matching chunks that contain
         *outcome_attribute*. If any matching chunk has a value of *outcome_attribute*
         that is not a real number an :exc:`Exception` is raised.
 
+        If neither ``instance_salience`` nor ``feature_salience`` is true, the sole return
+        value is the blended value; otherwise a tuple of three values is returned. The
+        first the blended value. If ``instance_salience`` is true the second is a dict
+        mapping a descriptions of the slot values of each of the matched chunks that
+        contributed to the blended value to the normalized instance salience value, a real
+        number between -1 and 1, inclusive; otherwise the second value is ``None``. The
+        slot representation of slot values in this dict is a tuple of tuples, the inner
+        tuples being the slot name and value.
+
+        If ``feature_salience`` is true the third value is a dict mapping slot names,
+        corresponding to those slots that were partially matched in this blending
+        operation, to their normalized feature salience values, a real number between -1
+        and 1, inclusive; otherwise the third value is ``None``. To compute feature
+        salience a derivative of the similarity function must have been specified for
+        every partially match slot using :meth:`similarity`; if any are missing a
+        :exc:`RuntimeError`` is raised.
+
         >>> m = Memory()
         >>> m.learn({"color":"red", "size":2})
-        True
+        <Chunk 0000 {'color': 'red', 'size': 2} 1>
         >>> m.advance()
         1
         >>> m.learn({"color":"blue", "size":30})
-        True
+        <Chunk 0001 {'color': 'blue', 'size': 30} 1>
         >>> m.advance()
         2
         >>> m.learn({"color":"red", "size":1})
-        True
+        <Chunk 0002 {'color': 'red', 'size': 1} 1>
         >>> m.advance()
         3
         >>> m.blend("size", {"color":"red"})
-        1.221272238515685
+        1.3660254037844388
+        >>> m.blend("size", {"color":"red"}, instance_salience=True)
+        (1.3660254037844388,
+         {(('color', 'red'), ('size', 2)): 0.7071067811865472,
+          (('color', 'red'), ('size', 1)): -0.7071067811865478},
+         None)
+
         """
-        probs, chunks = self._blend(outcome_attribute, slots)
-        if chunks is None:
-            return None
-        with np.errstate(divide="raise", over="raise", under="ignore", invalid="raise"):
-            try:
-                return np.average(np.array([c[outcome_attribute] for c in chunks],
-                                           dtype=np.float64),
-                                  weights=probs)
-            except Exception as e:
-                raise RuntimeError(f"Error computing blended value, is perhaps the value "
-                                   f"of the {outcome_attribute} slotis  not numeric in "
-                                   f"one of the matching chunks? ({e})")
+        probs, chunks, isal, fsal = self._blend(outcome_attribute, slots,
+                                                instance_salience, feature_salience)
+        if chunks is not None:
+            with np.errstate(divide="raise", over="raise", under="ignore", invalid="raise"):
+                try:
+                    result = np.average(np.array([c[outcome_attribute] for c in chunks],
+                                                 dtype=np.float64),
+                                        weights=probs)
+                except Exception as e:
+                    raise RuntimeError(f"Error computing blended value, is perhaps the value "
+                                       f"of the {outcome_attribute} slotis not numeric in "
+                                       f"one of the matching chunks? ({e})")
+        else:
+            result = None
+        if not instance_salience and not feature_salience:
+            return result
+        if instance_salience:
+            if isal is not None:
+                isal = {tuple(c.items()): s for c, s in zip(chunks, isal)}
+            else:
+                isal = {}
+        if feature_salience and fsal is None:
+            fsal = {}
+        return result, isal, fsal
 
     def best_blend(self, outcome_attribute, iterable, select_attribute=None, minimize=False):
         """Returns two values (as a 2-tuple), describing the extreme blended value of the *outcome_attribute* over the values provided by *iterable*.
@@ -1173,25 +1240,25 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"color":"red", "utility":1})
-        True
+        <Chunk 0000 {'color': 'red', 'utility': 1} 1>
         >>> m.advance()
         1
         >>> m.learn({"color":"blue", "utility":2})
-        True
+        <Chunk 0001 {'color': 'blue', 'utility': 2} 1>
         >>> m.advance()
         2
         >>> m.learn({"color":"red", "utility":1.8})
-        True
+        <Chunk 0002 {'color': 'red', 'utility': 1.8} 1>
         >>> m.advance()
         3
         >>> m.learn({"color":"blue", "utility":0.9})
-        True
+        <Chunk 0003 {'color': 'blue', 'utility': 0.9} 1>
         >>> m.advance()
         4
         >>> m.best_blend("utility", ({"color": c} for c in ("red", "blue")))
         ({'color': 'blue'}, 1.5149259914576285)
         >>> m.learn({"color":"blue", "utility":-1})
-        True
+        <Chunk 0004 {'color': 'blue', 'utility': -1} 1>
         >>> m.advance()
         5
         >>> m.best_blend("utility", ("red", "blue"), "color")
@@ -1231,25 +1298,24 @@ class Memory(dict):
 
         >>> m = Memory()
         >>> m.learn({"kind": "tilset", "age": "old"})
-        True
+        <Chunk 0000 {'kind': 'tilset', 'age': 'old'} 1>
         >>> m.advance()
         1
         >>> m.learn({"kind": "limburger", "age": "old"})
-        True
+        <Chunk 0001 {'kind': 'limburger', 'age': 'old'} 1>
         >>> m.advance()
         2
         >>> m.learn({"kind": "tilset", "age": "old"})
-        False
         >>> m.advance()
         3
         >>> m.learn({"kind": "tilset", "age": "new"})
-        True
+        <Chunk 0002 {'kind': 'tilset', 'age': 'new'} 1>
         >>> m.advance()
         4
         >>> m.discrete_blend("kind", {"age": "old"})
         ('tilset', {'tilset': 0.9540373563209859, 'limburger': 0.04596264367901423})
         """
-        probs, chunks = self._blend(outcome_attribute, slots)
+        probs, chunks, isal, fsal = self._blend(outcome_attribute, slots, False, False)
         if not chunks:
             return None, None
         candidates = defaultdict(list)
@@ -1268,7 +1334,7 @@ class Memory(dict):
         return (random.choice(best),
                 dict(sorted(candidates.items(), key=lambda x: x[1], reverse=True)))
 
-    def similarity(self, attributes, function=None, weight=None):
+    def similarity(self, attributes, function=None, weight=None, derivative=None):
         """Assigns a similarity function and/or corresponding weight to be used when comparing attribute values with the given *attributes*.
         The *attributes* should be an :class:`Iterable` of strings, attribute names.
         The *function* should take two arguments, and return a real number between 0 and 1,
@@ -1281,12 +1347,23 @@ class Memory(dict):
         will, in most cases, be meaningless if they are.
         If ``True`` is supplied as the *function* a default similarity function is used
         that returns one if its two arguments are ``==`` and zero otherwise.
-        If only one of *function* or *weight* is supplied, it is changed without
-        changing the other; the initial defaults are ``True`` for *function* and ``1``
-        for *weight*.
-        If neither *function* nor *weight* is supplied both are removed, and these
-        *attributes* will no longer have an associated similarity computation, and will
-        be matched only exactly.
+
+        If *derivative* is supplied it should be a callable, the first partial derivative
+        of the similarity function with respect to its first argument, and will be used
+        if the feature saliences are requested in :meth:`blend`. The *derivative* must
+        be defined for all values that may occur for the relevant slots. It is common
+        that the strict mathematical derivative may not exists for one or a small number
+        of possibly values, most commonly when the similarly involves the absolute value
+        of the difference between the two arguments of the similarly function. Even in
+        these cases the argument to :meth:`similarity` should return a value; often zero
+        is a good choice in these cases.
+
+        If only one or two of *function*, *weight* and *derivatve* are supplied, they
+        changed without changing those not supplied; the initial defaults are ``True`` for
+        *function*, ``1`` for *weight*, and ``None`` for *derivative*. If none
+        of*function*, *weight* nor *derivative* are supplied all are removed, and these
+        *attributes* will no longer have an associated similarity computation, and will be
+        matched only exactly.
 
         As a convenience, if none of the attribute names contains commas or spaces, a
         string may be used instead of a list as the first argument to ``similarity``, the
@@ -1308,14 +1385,15 @@ class Memory(dict):
         ...         return f(y, x)
         ...     return 1 - (y - x) / y
         >>> similarity(["length", "width"], f, weight=2)
-
         """
         if function is not None and not (callable(function) or function is True):
             raise ValueError(f"Function {function} is neither callable nor True")
+        if derivative is not None and not callable(derivative):
+            raise(ValueError(f"Derivative {derivative} is not callable"))
         if weight is not None and weight <= 0:
             raise ValueError(f"Similarity weight, {weight}, is not a positive number")
         for a in Memory._ensure_slot_names(attributes):
-            if function is None and weight is None:
+            if function is None and weight is None and derivative is None:
                 if a in self._similarities:
                     del self._similarities[a]
             else:
@@ -1323,12 +1401,19 @@ class Memory(dict):
                 sim._memory = self
                 if function is not None and function != sim._function:
                     sim._function = function
+                if derivative is not None and function != sim._derivative:
+                    sim._derivative = derivative
                 if weight is not None and weight != sim._weight:
                     sim._weight = weight
                 sim._cache.clear()
 
 
 class Chunk(dict):
+    """A learned item.
+
+    A chunk acts much like a dictionary, and its slots can be retrieved with the usual
+    `[]` notation, or with `.get()`.
+    """
 
     __slots__ = ["_name", "_memory", "_creation", "_references", "_reference_count" ]
 
@@ -1350,6 +1435,11 @@ class Chunk(dict):
     def __str__(self):
         return f"Chunk-{self._name}"
 
+    @property
+    def memory(self):
+        """The :class:`Memory` object that contains this chunk."""
+        return self._memory
+
     @property
     def reference_count(self):
         """A non-negative integer, the number of times that this :class:`Chunk` has been reinforced.
@@ -1358,21 +1448,22 @@ class Chunk(dict):
 
     @property
     def references(self):
-        """A list of real numbers, the times at which that this :class:`Chunk` has been reinforced.
+        """A tuple of real numbers, the times at which that this :class:`Chunk` has been reinforced.
         If :attr:`optimized_learning` is being used this may be just the most recent
         reinforcements, or an empty list, depending upon the value of
-        :attr:`optimized_learning`
+        :attr:`optimized_learning`.
         """
-        return list(self._references[:(self._reference_count
-                                       if self._memory._optimized_learning is None
-                                       else min(self._reference_count,
-                                                self._memory._optimized_learning))])
+        return tuple(self._references[:(self._reference_count
+                                        if self._memory._optimized_learning is None
+                                        else min(self._reference_count,
+                                                 self._memory._optimized_learning))])
 
 
 @dataclass
 class Similarity:
     _memory: Memory = None
     _function: callable = True
+    _derivative: callable = None
     _weight: float = 1.0
     _cache: lrucache = field(default_factory=lambda: lrucache(SIMILARITY_CACHE_SIZE))
 

{pyactup-2.1 → pyactup-2.2}/pyactup.egg-info/requires.txt

@@ -1,3 +1,3 @@
 numpy
-prettytable
 pylru
+prettytable