oracular 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.11.0
+
+### Minor Changes
+
+- [#58](https://github.com/Yuribenjamin/oracular/pull/58) [`d6d1e87`](https://github.com/Yuribenjamin/oracular/commit/d6d1e87e176fc0112384e47fb4782e12d6fa1d1a) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - **Learning no longer drifts without outcomes.** The outcome rates a signal is judged by, with it and without it, were Laplace-smoothed, which centres both on 0.5 with one pseudo-hit each: two groups with no outcome at all then differ only by their sizes, so with zero outcomes a common signal drifted negative and a rare one positive, and a weight could change sign on no evidence (a weight of 2 seen in 90 of 100 outcome-free episodes ended at −0.59). Both rates are now shrunk toward the intent's own base rate by two pseudo-episodes, `(hits + 2·q₀) / (n + 2)` with `q₀ = outcomes / episodes`: a signal whose outcome rate equals the base rate learns exactly zero whatever the sample sizes, with no outcome every rate is 0 and no weight moves away from the developer's, and a weight never changes sign without outcomes on at least one side. The association-rule baseline becomes the base rate itself. `tune` fits with the same smoothing, so its weights, intervals and lifts move a little on small samples (a signal seen once with the outcome over a low base rate is worth a little less than before); on large samples the change is in the third decimal. Every learned number in the documentation's generated tables was regenerated. The state format is unchanged, and existing learned counts are kept: only the weight read from them moves.
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -193,8 +193,9 @@ A signal's weight is then a blend of your prior and the learned estimate:
 ```
 nWith    = hits + misses                                      episodes with the signal
 nWithout = episodes − nWith                                   episodes without it
-qWith    = (hits + 1) / (nWith + 2)                           outcome rate with the signal
-qWithout = (outcomes − hits + 1) / (nWithout + 2)             outcome rate without it
+q₀       = outcomes / episodes                                the intent's own base rate
+qWith    = (hits + 2·q₀) / (nWith + 2)                        outcome rate with the signal
+qWithout = (outcomes − hits + 2·q₀) / (nWithout + 2)          outcome rate without it
 lift     = (qWith − qWithout) / (1 − qWithout)  if qWith ≥ qWithout,  else  (qWith − qWithout) / qWithout   → in [−1, 1]
 learned  = gain × |w₀| × lift                                 0 until the signal has history
 nEff     = (nWith × nWithout) / (nWith + nWithout)            0 if either side is 0

package/dist/cli.js

@@ -437,6 +437,9 @@ import {
 function laplace(successes, total) {
   return (successes + 1) / (total + 2);
 }
+function smoothRate(successes, total, rate) {
+  return (successes + 2 * rate) / (total + 2);
+}
 function lift(q, b, type = "normalized-difference") {
   if (type === "absolute-difference") return q - b;
   if (type !== "normalized-difference") {
@@ -528,9 +531,10 @@ function fitSignal(signal, current, tally, strength, priorEpisodes, liftType) {
   const nWith = hits + misses;
   const without = Math.max(0, tally.episodes - nWith);
   const outcomesWithout = Math.min(without, Math.max(0, tally.outcomes - hits));
-  const qWith = laplace(hits, nWith);
-  const qWithout = laplace(outcomesWithout, without);
-  const baseline = liftType === "association-rule" ? (hits + outcomesWithout + 2) / (nWith + without + 4) : qWithout;
+  const base = tally.episodes === 0 ? 0 : tally.outcomes / tally.episodes;
+  const qWith = smoothRate(hits, nWith, base);
+  const qWithout = smoothRate(outcomesWithout, without, base);
+  const baseline = liftType === "association-rule" ? smoothRate(hits + outcomesWithout, nWith + without, base) : qWithout;
   const noContrast = without === 0;
   const rawLift = noContrast ? null : nWith === 0 ? 0 : lift(qWith, baseline, liftType);
   const score = rawLift === null ? null : nWith === 0 ? 0 : learningScore(rawLift, liftType);

package/dist/index.cjs

@@ -79,8 +79,8 @@ function lowerBound(alpha, beta, z, bound) {
 function repeatFactor(n) {
   return Math.log1p(1 / n) / Math.LN2;
 }
-function laplace(successes, total) {
-  return (successes + 1) / (total + 2);
+function smoothRate(successes, total, rate) {
+  return (successes + 2 * rate) / (total + 2);
 }
 function lift(q, b, type = "normalized-difference") {
   if (type === "absolute-difference") return q - b;
@@ -154,12 +154,13 @@ function signalWeights(state, intent, learning, signal) {
   }
   const record2 = getOwn(state.learned, signal) ?? NONE;
   const nWith = record2.hits + record2.misses;
-  const qWith = laplace(record2.hits, nWith);
   const totalEpisodes = state.episodes.hits + state.episodes.misses;
   const nWithout = Math.max(0, totalEpisodes - nWith);
   const outcomesWithout = Math.min(nWithout, Math.max(0, state.episodes.hits - record2.hits));
-  const qWithout = laplace(outcomesWithout, nWithout);
-  const baseline = learning.lift === "association-rule" ? (record2.hits + outcomesWithout + 2) / (nWith + nWithout + 4) : qWithout;
+  const base = totalEpisodes === 0 ? 0 : state.episodes.hits / totalEpisodes;
+  const qWith = smoothRate(record2.hits, nWith, base);
+  const qWithout = smoothRate(outcomesWithout, nWithout, base);
+  const baseline = learning.lift === "association-rule" ? smoothRate(record2.hits + outcomesWithout, nWith + nWithout, base) : qWithout;
   const score = learningScore(lift(qWith, baseline, learning.lift), learning.lift);
   const learned = nWith === 0 ? 0 : learning.gain * Math.abs(initial) * score;
   const nEff = nWith + nWithout === 0 ? 0 : nWith * nWithout / (nWith + nWithout);