probability-flow 1.4.3__tar.gz → 1.4.4__tar.gz

{probability_flow-1.4.3 → probability_flow-1.4.4}/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.4.4
+
+### Added
+
+- **`variable.set_baseline(probability)`**, for changing P(a node) with every
+  parent absent after the CPD is written.
+
+  It takes a PROBABILITY, which is the unit `set_prior` takes and the unit the
+  file format stores. There is no relative form and no `bits=` flag: a
+  `shift_baseline(0.2)` beside a `set_baseline(0.2)` is two calls that read the
+  same and mean different things, since `0.2` is a plausible probability and a
+  plausible number of bits.
+
+### Fixed
+
+- **A removed id could be handed out again.** Removing a variable from the
+  middle of a graph left a hole that the next auto-assigned id stepped past,
+  but removing the LAST variable simply freed its id, and the next variable
+  took it back. Anything still referring to the removed node then pointed at a
+  different proposition, silently. Ids are retired on removal now.
+
+- **Three more silent no-ops in the additive family.** `cpd.baseline`,
+  `cpd.gates` and `Gate.weight_when_gated` all accepted an assignment, changed
+  nothing and reported nothing, because the value every query reads is a
+  derived copy. `baseline` was the worst: it read back as the number you had
+  assigned, so the object agreed with you while going on answering the old
+  question. All three raise now.
+
 ## 1.4.3
 
 ### Added
@@ -78,8 +106,6 @@
   the row where both hold, where an `and` over the two would be `1.0`. Tagging
   that `logical` would misdescribe the numbers.
 
-## Unreleased
-
 ### Fixed
 
 - **An evidence node's `name` is free text.** The reader used to refuse any name

{probability_flow-1.4.3 → probability_flow-1.4.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: probability-flow
-Version: 1.4.3
+Version: 1.4.4
 Summary: Discrete causal graphs and exact inference.
 Author-email: Alex Roman <dr.alexroman@gmail.com>
 License-Expression: MIT

{probability_flow-1.4.3 → probability_flow-1.4.4}/probability_flow/__init__.py

@@ -38,7 +38,7 @@ from .serialize import FORMAT, VERSION, from_json, to_json
 from .variable import BINARY, Definition, Variable
 from .viz import render, to_text
 
-__version__ = "1.4.3"
+__version__ = "1.4.4"
 
 __all__ = [
     "__version__",

{probability_flow-1.4.3 → probability_flow-1.4.4}/probability_flow/graph.py

@@ -39,6 +39,13 @@ class CausalGraph:
         self._by_name: "dict[str, Variable]" = {}
         self._position: "dict[int, int]" = {}
         self._by_id: "dict[str, Variable]" = {}
+        #: EVERY ID THIS GRAPH HAS EVER ISSUED, including ones whose variable
+        #: has since been removed. `_by_id` is not enough on its own: removing
+        #: the LAST variable freed its id, and the next auto-assigned one took
+        #: it back, so a decoration or an external reference keyed to the old
+        #: `v2` would silently attach to a different proposition. Ids are the
+        #: schema every external reference uses, so a removed one is retired.
+        self._issued: "set[str]" = set()
         #: Free-form provenance emitted at the top of a document: library
         #: version, generator identity, and a seed where one exists. The seed is
         #: what makes "regenerate the affected twelve" possible instead of
@@ -108,7 +115,7 @@ class CausalGraph:
             # variable used to hand the reader an auto id that was already
             # taken, so the graph could not round-trip at all.
             n = len(self._variables)
-            while f"v{n}" in self._by_id:
+            while f"v{n}" in self._by_id or f"v{n}" in self._issued:
                 n += 1
             variable.id = f"v{n}"
         if variable.id in self._by_id:
@@ -125,6 +132,7 @@ class CausalGraph:
         self._variables.append(variable)
         self._by_name[variable.name] = variable
         self._by_id[variable.id] = variable
+        self._issued.add(variable.id)
         self._position[id(variable)] = len(self._variables) - 1
         self._parent_list[id(variable)] = []
         self._child_list[id(variable)] = []

{probability_flow-1.4.3 → probability_flow-1.4.4}/probability_flow/independent.py

@@ -101,7 +101,7 @@ class Gate:
     whose polarity is ambiguous.
     """
 
-    __slots__ = ("source", "modulates", "weight_when_gated")
+    __slots__ = ("source", "modulates", "_weight_when_gated")
 
     def __init__(self, source, modulates,
                  weight_when_gated: float = 0.0):
@@ -116,7 +116,18 @@ class Gate:
             )
         self.source = source
         self.modulates = modulates
-        self.weight_when_gated = float(weight_when_gated)
+        self._weight_when_gated = float(weight_when_gated)
+
+    @property
+    def weight_when_gated(self) -> float:
+        """What the modulated edge carries while this gate holds, in bits. READ-ONLY.
+
+        The CPD converts it to nats once, at construction, so assigning here
+        changed nothing and reported nothing. A gate's weight is part of what
+        the gate IS, so changing it means declaring the gate again and setting
+        the CPD, which is the same amount of typing and cannot half-apply.
+        """
+        return self._weight_when_gated
 
     def __repr__(self) -> str:
         kind = ("hard" if self.weight_when_gated == 0.0
@@ -224,15 +235,15 @@ class IndependentEvidence(CPD):
 
         self.child = None                 # bound by set_cpd
         self.parents = tuple(parents)
-        self.baseline = float(baseline)
-        self.gates = tuple(gates)
+        self._baseline = float(baseline)
+        self._gates = tuple(gates)
         #: AUTHORED BITS, stored verbatim. Not re-derived from the nats below,
         #: because bits -> nats -> bits does not return the number that was
         #: written: speeding-camera carries 1.5154639175257731 and a document
         #: must hold what its author wrote.
         self._weights = {id(p): float(ratios.get(p, 0.0)) for p in parents}
 
-        self._log_baseline = math.log(self.baseline / (1.0 - self.baseline))
+        self._log_baseline = math.log(self._baseline / (1.0 - self._baseline))
         #: nats, derived once. Everything below this line is nats, because
         #: math.log is, and converting at every comparison is how a 1.4427
         #: factor goes missing.
@@ -254,6 +265,54 @@ class IndependentEvidence(CPD):
         from types import MappingProxyType
         return MappingProxyType(self._weights)
 
+    @property
+    def gates(self):
+        """The gates on this CPD. READ-ONLY.
+
+        `_gated` is built from these once, at construction, so replacing the
+        tuple changed nothing. Gates are declared when the CPD is written.
+        """
+        return self._gates
+
+    @property
+    def baseline(self) -> float:
+        """P(child) with every parent absent, as a PROBABILITY. Read-only.
+
+        `_log_baseline` holds the same number in nats and is what every query
+        reads, so `cpd.baseline = 0.2` used to change nothing, report nothing,
+        and then read back as 0.2: the object lied about itself. Use
+        `set_baseline`.
+        """
+        return self._baseline
+
+    def set_baseline(self, probability: float) -> None:
+        """Set the baseline, as a PROBABILITY.
+
+        ABSOLUTE, SO IT IS A PROBABILITY, which is the same unit `set_prior`
+        takes and the same unit the file format stores. The baseline is a claim
+        about the world -- what the child is worth when none of its parents
+        hold -- so it is the kind of thing you can write a sentence about, and
+        sentences about it are in probabilities.
+
+        THERE IS NO RELATIVE FORM, ON PURPOSE. A `shift_baseline(0.2)` beside
+        a `set_baseline(0.2)` is two calls that read the same and mean
+        different things, because 0.2 is a plausible probability AND a
+        plausible number of bits. That is the ambiguity a `bits=True` flag
+        would introduce, spread across two names instead of one keyword.
+        """
+        if not (isinstance(probability, (int, float))
+                and not isinstance(probability, bool)
+                and 0.0 < probability < 1.0):
+            raise ValueError(
+                f"a baseline is a probability strictly between 0 and 1 (got "
+                f"{probability!r}). It is P(child) with every parent absent, so "
+                "0 and 1 are both excluded: a baseline of 0 is a child no "
+                "evidence can ever raise, and the log-odds of either is "
+                "infinite."
+            )
+        self._baseline = float(probability)
+        self._log_baseline = math.log(self._baseline / (1.0 - self._baseline))
+
     def set_weight(self, parent, bits: float) -> None:
         """Set what one parent's edge carries, in BITS, keeping the derived form.
 
@@ -517,7 +576,7 @@ class IndependentEvidence(CPD):
         kept = {id(p) for p in parents}
         out._weights = {id(p): self.weights.get(id(p), 0.0) for p in parents}
         out._log_w = {k: v * _LN2 for k, v in out.weights.items()}
-        out.gates = tuple(g for g in self.gates
+        out._gates = tuple(g for g in self.gates
                           if id(g.source) in kept and id(g.modulates) in kept)
         out._gated = {id(g.modulates): (g.source, g.weight_when_gated * _LN2)
                       for g in out.gates}

{probability_flow-1.4.3 → probability_flow-1.4.4}/probability_flow/serialize.py

@@ -28,7 +28,7 @@ import json
 from .variable import short
 
 FORMAT = "probability-flow/causal-graph"
-VERSION = "1.4.3"
+VERSION = "1.4.4"
 
 #: Every key a document may carry, at each level. An unknown key is REJECTED.
 #:

{probability_flow-1.4.3 → probability_flow-1.4.4}/probability_flow/variable.py

@@ -599,6 +599,36 @@ class Variable:
         """P(this | its causes).  See `CausalGraph.set_cpd` for what `spec` may be."""
         self.graph._set_cpd(self, spec)
 
+    def _additive_cpd(self, doing: str):
+        """This node's CPD, if it is the family that has a baseline."""
+        try:
+            cpd = self.cpd
+        except KeyError:
+            # `graph._cpd` raises rather than returning None, so this is the
+            # path a caller takes before writing any numbers at all.
+            raise ValueError(
+                f"{short(self.name)!r} has no CPD yet, so there is no baseline "
+                "to set. Give it one first, with set_cpd() or set_prior()."
+            ) from None
+        if not hasattr(cpd, "set_baseline"):
+            leak = " Its `leak` is the same idea for this family." \
+                if hasattr(cpd, "leak") else ""
+            raise ValueError(
+                f"{short(self.name)!r} has a {type(cpd).__name__}, which has no "
+                f"baseline to {doing}. A baseline is P(child) with every parent "
+                "absent, which only the additive family states as a single "
+                f"number.{leak}"
+            )
+        return cpd
+
+    def set_baseline(self, probability: float) -> None:
+        """Set P(this) with every parent absent, as a PROBABILITY.
+
+        The same unit `set_prior` takes, because it is the same kind of claim:
+        what this node is worth before any of its causes do anything.
+        """
+        self._additive_cpd("set").set_baseline(probability)
+
     @property
     def parents(self) -> "tuple[Variable, ...]":
         return self.graph._parents(self)

{probability_flow-1.4.3 → probability_flow-1.4.4}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "probability-flow"
-version = "1.4.3"
+version = "1.4.4"
 description = "Discrete causal graphs and exact inference."
 readme = "README.md"
 requires-python = ">=3.11"