Rename Categorize's 'pairs' as 'bins' for better coherence with CentrallyBin, IrregularlyBin, Stack, etc.

Author: jpivarski

histogrammar/primitives/categorize.py

@@ -29,30 +29,30 @@ class Categorize(Factory, Container):
     """
 
     @staticmethod
-    def ed(entries, contentType, pairsAsDict=None, **pairs):
+    def ed(entries, contentType, binsAsDict=None, **bins):
         """Create a Categorize that is only capable of being added.
 
         Parameters:
             entries (float): the number of entries.
             contentType (str): the value's sub-aggregator type (must be provided to determine type for the case when `bins` is empty).
-            pairs (dict from str to :doc:`Container <histogrammar.defs.Container>`): the non-empty bin categories and their values.
+            bins (dict from str to :doc:`Container <histogrammar.defs.Container>`): the non-empty bin categories and their values.
         """
         if not isinstance(entries, numbers.Real) and entries not in ("nan", "inf", "-inf"):
             raise TypeError("entries ({0}) must be a number".format(entries))
         if not isinstance(contentType, basestring):
             raise TypeError("contentType ({0}) must be a string".format(contentType))
-        if not all(isinstance(k, basestring) and isinstance(v, Container) for k, v in pairs.items()):
-            raise TypeError("pairs ({0}) must be a dict from strings to Containers".format(pairs))
+        if not all(isinstance(k, basestring) and isinstance(v, Container) for k, v in bins.items()):
+            raise TypeError("bins ({0}) must be a dict from strings to Containers".format(bins))
         if entries < 0.0:
             raise ValueError("entries ({0}) cannot be negative".format(entries))
 
         out = Categorize(None, None)
         out.entries = float(entries)
-        if pairsAsDict is None:
-            out.pairs = {}
+        if binsAsDict is None:
+            out.bins = {}
         else:
-            out.pairs = pairsAsDict
-        out.pairs.update(pairs)
+            out.bins = binsAsDict
+        out.bins.update(bins)
         out.contentType = contentType
         return out.specialize()
 
@@ -70,55 +70,55 @@ def __init__(self, quantity, value=Count()):
 
         Other Parameters:
             entries (float): the number of entries, initially 0.0.
-            pairs (dict from str to :doc:`Container <histogrammar.defs.Container>`): the map, probably a hashmap, to fill with values when their `entries` become non-zero.
+            bins (dict from str to :doc:`Container <histogrammar.defs.Container>`): the map, probably a hashmap, to fill with values when their `entries` become non-zero.
         """
         if value is not None and not isinstance(value, Container):
             raise TypeError("value ({0}) must be None or a Container".format(value))
         self.entries = 0.0
         self.quantity = serializable(quantity)
         self.value = value
-        self.pairs = {}
+        self.bins = {}
         if value is not None:
             self.contentType = str(value.factory.name)
         super(Categorize, self).__init__()
         self.specialize()
 
     @property
-    def pairsMap(self):
-        """Input ``pairs`` as a key-value map."""
-        return self.pairs
+    def binsMap(self):
+        """Input ``bins`` as a key-value map."""
+        return self.bins
 
     @property
     def size(self):
-        """Number of ``pairs``."""
-        return len(self.pairs)
+        """Number of ``bins``."""
+        return len(self.bins)
 
     @property
     def keys(self):
-        """Iterable over the keys of the ``pairs``."""
-        return self.pairs.keys()
+        """Iterable over the keys of the ``bins``."""
+        return self.bins.keys()
 
     @property
     def values(self):
-        """Iterable over the values of the ``pairs``."""
-        return list(self.pairs.values())
+        """Iterable over the values of the ``bins``."""
+        return list(self.bins.values())
 
     @property
     def keySet(self):
-        """Set of keys among the ``pairs``."""
-        return set(self.pairs.keys())
+        """Set of keys among the ``bins``."""
+        return set(self.bins.keys())
 
     def __call__(self, x):
         """Attempt to get key ``x``, throwing an exception if it does not exist."""
-        return self.pairs[x]
+        return self.bins[x]
 
     def get(self, x):
         """Attempt to get key ``x``, returning ``None`` if it does not exist."""
-        return self.pairs.get(x)
+        return self.bins.get(x)
 
     def getOrElse(self, x, default):
         """Attempt to get key ``x``, returning an alternative if it does not exist."""
-        return self.pairs.get(x, default)
+        return self.bins.get(x, default)
 
     @inheritdoc(Container)
     def zero(self): return Categorize(self.quantity, self.value)
@@ -128,14 +128,14 @@ def __add__(self, other):
         if isinstance(other, Categorize):
             out = Categorize(self.quantity, self.value)
             out.entries = self.entries + other.entries
-            out.pairs = {}
+            out.bins = {}
             for k in self.keySet.union(other.keySet):
-                if k in self.pairs and k in other.pairs:
-                    out.pairs[k] = self.pairs[k] + other.pairs[k]
-                elif k in self.pairs:
-                    out.pairs[k] = self.pairs[k].copy()
+                if k in self.bins and k in other.bins:
+                    out.bins[k] = self.bins[k] + other.bins[k]
+                elif k in self.bins:
+                    out.bins[k] = self.bins[k].copy()
                 else:
-                    out.pairs[k] = other.pairs[k].copy()
+                    out.bins[k] = other.bins[k].copy()
             return out.specialize()
 
         else:
@@ -150,9 +150,9 @@ def fill(self, datum, weight=1.0):
             if not isinstance(q, basestring):
                 raise TypeError("function return value ({0}) must be a string".format(q))
 
-            if q not in self.pairs:
-                self.pairs[q] = self.value.zero()
-            self.pairs[q].fill(datum, weight)
+            if q not in self.bins:
+                self.bins[q] = self.value.zero()
+            self.bins[q].fill(datum, weight)
 
             # no possibility of exception from here on out (for rollback)
             self.entries += weight
@@ -161,29 +161,29 @@ def _cppGenerateCode(self, parser, generator, inputFieldNames, inputFieldTypes,
         normexpr = self._c99QuantityExpr(parser, generator, inputFieldNames, inputFieldTypes, derivedFieldTypes, derivedFieldExprs, None)
 
         initCode.append(" " * initIndent + self._c99ExpandPrefix(*initPrefix) + ".entries = 0.0;")
-        initCode.append(" " * initIndent + self._c99ExpandPrefix(*initPrefix) + ".pairs.clear();")
+        initCode.append(" " * initIndent + self._c99ExpandPrefix(*initPrefix) + ".bins.clear();")
         fillCode.append(" " * fillIndent + self._c99ExpandPrefix(*fillPrefix) + ".entries += " + weightVarStack[-1] + ";")
 
         value = "value_" + str(len(tmpVarTypes))
         tmpVarTypes[value] = self.value._c99StorageType() + "*"
 
-        fillCode.append("""{indent}if ({pairs}.find({q}) == {pairs}.end())
-{indent}  {pairs}[{q}] = {prototype};    // copy
-{indent}{value} = &({pairs}[{q}]);    // reference""".format(
+        fillCode.append("""{indent}if ({bins}.find({q}) == {bins}.end())
+{indent}  {bins}[{q}] = {prototype};    // copy
+{indent}{value} = &({bins}[{q}]);    // reference""".format(
             indent = " " * fillIndent,
             q = normexpr,
             value = value,
             prototype = self._c99ExpandPrefix(*fillPrefix) + ".value",
-            pairs = self._c99ExpandPrefix(*fillPrefix) + ".pairs"))
+            bins = self._c99ExpandPrefix(*fillPrefix) + ".bins"))
 
         self.value._c99GenerateCode(parser, generator, inputFieldNames, inputFieldTypes, derivedFieldTypes, derivedFieldExprs, storageStructs, initCode, initPrefix + (("var", "value"),), initIndent, fillCode, (("var", "(*" + value + ")"),), fillIndent, weightVars, weightVarStack, tmpVarTypes)
 
         storageStructs[self._c99StructName()] = """
   typedef struct {{
     double entries;
     {1} value;
-    std::unordered_map<std::string, {1}> pairs;
-    {1}& getValues(std::string i) {{ return pairs[i]; }}
+    std::unordered_map<std::string, {1}> bins;
+    {1}& getValues(std::string i) {{ return bins[i]; }}
   }} {0};
 """.format(self._c99StructName(), self.value._c99StorageType())
 
@@ -194,11 +194,11 @@ def _clingUpdate(self, filler, *extractorPrefix):
         obj = self._clingExpandPrefix(filler, *extractorPrefix)
         self.entries += obj.entries
 
-        for i in obj.pairs:
+        for i in obj.bins:
             key = i.first
-            if key not in self.pairs:
-                self.pairs[key] = self.value.copy()
-            self.pairs[key]._clingUpdate(obj, ("func", ["getValues", key]))
+            if key not in self.bins:
+                self.bins[key] = self.value.copy()
+            self.bins[key]._clingUpdate(obj, ("func", ["getValues", key]))
 
     def _c99StructName(self):
         return "Cz" + self.value._c99StructName()
@@ -212,17 +212,17 @@ def _numpy(self, data, weights, shape):
         # no possibility of exception from here on out (for rollback)
         for x, w in zip(q, weights):
             if w > 0.0:
-                if x not in self.pairs:
-                    self.pairs[x] = self.value.zero()
-                self.pairs[x].fill(x, w)
+                if x not in self.bins:
+                    self.bins[x] = self.value.zero()
+                self.bins[x].fill(x, w)
 
         # no possibility of exception from here on out (for rollback)
         self.entries += float(weights.sum())
 
     @property
     def children(self):
         """List of sub-aggregators, to make it possible to walk the tree."""
-        return [self.value] + list(self.pairs.values())
+        return [self.value] + list(self.bins.values())
 
     @inheritdoc(Container)
     def toJsonFragment(self, suppressName):
@@ -233,11 +233,11 @@ def toJsonFragment(self, suppressName):
                 binsName = self.value.quantityName
             else:
                 binsName = None
-        elif len(self.pairs) > 0:
-            if getattr(list(self.pairs.values())[0], "quantity", None) is not None:
-                binsName = list(self.pairs.values())[0].quantity.name
-            elif getattr(list(self.pairs.values())[0], "quantityName", None) is not None:
-                binsName = list(self.pairs.values())[0].quantityName
+        elif len(self.bins) > 0:
+            if getattr(list(self.bins.values())[0], "quantity", None) is not None:
+                binsName = list(self.bins.values())[0].quantity.name
+            elif getattr(list(self.bins.values())[0], "quantityName", None) is not None:
+                binsName = list(self.bins.values())[0].quantityName
             else:
                 binsName = None
         else:
@@ -246,7 +246,7 @@ def toJsonFragment(self, suppressName):
         return maybeAdd({
             "entries": floatToJson(self.entries),
             "bins:type": self.value.name if self.value is not None else self.contentType,
-            "bins": dict((k, v.toJsonFragment(True)) for k, v in self.pairs.items()),
+            "bins": dict((k, v.toJsonFragment(True)) for k, v in self.bins.items()),
             }, **{"name": None if suppressName else self.quantity.name,
                   "bins:name": binsName})
 
@@ -280,11 +280,11 @@ def fromJsonFragment(json, nameFromParent):
                 raise JsonFormatException(json["bins:name"], "Categorize.bins:name")
 
             if isinstance(json["bins"], dict):
-                pairs = dict((k, factory.fromJsonFragment(v, dataName)) for k, v in json["bins"].items())
+                bins = dict((k, factory.fromJsonFragment(v, dataName)) for k, v in json["bins"].items())
             else:
                 raise JsonFormatException(json, "Categorize.bins")
 
-            out = Categorize.ed(entries, contentType, **pairs)
+            out = Categorize.ed(entries, contentType, **bins)
             out.quantity.name = nameFromParent if name is None else name
             return out.specialize()
 
@@ -295,11 +295,11 @@ def __repr__(self):
         return "<Categorize values={0} size={1}".format(self.values[0].name if self.size > 0 else self.value.name if self.value is not None else self.contentType, self.size)
 
     def __eq__(self, other):
-        return isinstance(other, Categorize) and numeq(self.entries, other.entries) and self.quantity == other.quantity and self.pairs == other.pairs
+        return isinstance(other, Categorize) and numeq(self.entries, other.entries) and self.quantity == other.quantity and self.bins == other.bins
 
     def __ne__(self, other): return not self == other
 
     def __hash__(self):
-        return hash((self.entries, self.quantity, tuple(sorted(self.pairs.items()))))
+        return hash((self.entries, self.quantity, tuple(sorted(self.bins.items()))))
 
 Factory.register(Categorize)

test/specification.py

@@ -405,25 +405,25 @@ def IrregularlyBin_combine(one, two):
 def Categorize_fill(categorizing, datum, weight):
     if weight > 0.0:
         q = categorizing.quantity(datum)
-        if q not in categorizing.pairs:
-            categorizing.pairs[q] = categorizing.value.copy()
-        fill(categorizing.pairs[q], datum, weight)
+        if q not in categorizing.bins:
+            categorizing.bins[q] = categorizing.value.copy()
+        fill(categorizing.bins[q], datum, weight)
         categorizing.entries += weight
 
 def Categorize_combine(one, two):
     if one.contentType != two.contentType:
         raise Exception
     entries = one.entries + two.entries
     contentType = one.contentType
-    pairs = {}
-    for key in set(one.pairs.keys()).union(set(two.pairs.keys())):
-        if key in one.pairs and key in two.pairs:
-            pairs[key] = combine(one.pairs[key], two.pairs[key])
-        elif key in one.pairs:
-            pairs[key] = one.pairs[key].copy()
-        elif key in two.pairs:
-            pairs[key] = two.pairs[key].copy()
-    return Categorize.ed(entries, contentType, pairs)
+    bins = {}
+    for key in set(one.bins.keys()).union(set(two.bins.keys())):
+        if key in one.bins and key in two.bins:
+            bins[key] = combine(one.bins[key], two.bins[key])
+        elif key in one.bins:
+            bins[key] = one.bins[key].copy()
+        elif key in two.bins:
+            bins[key] = two.bins[key].copy()
+    return Categorize.ed(entries, contentType, bins)
 
 def Fraction_fill(fractioning, datum, weight):
     if weight > 0.0:

test/testbasic.py

@@ -803,7 +803,7 @@ def testCategorize(self):
         categorizing = Categorize(named("something", lambda x: x.string[0]))
         for _ in self.struct: categorizing.fill(_)
 
-        self.assertEqual(dict((k, v.entries) for k, v in categorizing.pairsMap.items()), {"n": 1.0, "e": 1.0, "t": 3.0, "s": 2.0, "f": 2.0, "o": 1.0})
+        self.assertEqual(dict((k, v.entries) for k, v in categorizing.binsMap.items()), {"n": 1.0, "e": 1.0, "t": 3.0, "s": 2.0, "f": 2.0, "o": 1.0})
 
         self.checkJson(categorizing)
         self.checkPickle(categorizing)