Bayesian - More verbose breaking text with worked examples (#24470)

Co-authored-by: Franck Nijhof <frenck@frenck.nl>

source/_posts/2022-10-05-release-202210.markdown

@@ -412,15 +412,69 @@ for that specific item.
 
 {% details "Bayesian" %}
 
-The `prob_given_false` configuration variable is now a required parameter as there
-was no mathematical rationale for the previous default value.
+`prob_given_false` is now a required configuration variable. Previously it had a default value of `1 - prob_given_true`; this didn't really have any mathematical basis and so has been removed. You can use this documentation to calculate what it should be, or to restore your previous functionality, set it to `1 - prob_given_true`.
 
-`numeric_state`, `template`, and `state` entries with only one `to_state`
-configured will update the prior probability accordingly if the
-observation is false. Those who have used duplicate, mirrored `state`
-configurations as a workaround will have their functionality preserved.
-However, for `numeric_state` and `template` entries, this will cause
-duplication of the Bayesian updating.
+The logic of Bayesian sensors has been significantly corrected. Previously the configs given in the examples above would not have worked as expected. For example, if the device `device_tracker.paulus` was `home`, this would not have updated the probability that `Paulus Home` was on. This is because Bayesian ignored observations that were false, even though that *should* update our probabilities. 
+
+Because of this, many users will have had to use either of two workarounds:
+
+1. Providing additional observations that evaluate to `True` when the other evaluates to `False`, effectively mirroring it. This forced Bayesian to take into account a negative observation.
+2. Tweaking `prior`, `threshold`, and even sometimes `prob_given_true` and `prob_given_false` to get the desired functionality, often with the help of a community-provided spreadsheet for iterative testing.
+
+To solve (1), all you need do is delete the mirrored entry as shown below:
+
+```yaml
+# Example of a mirrored entry used a workaround
+binary_sensor:
+  - name: "Heat On"
+    platform: bayesian
+    prior: 0.2
+    probability_threshold: 0.9
+    observations:
+      - platform: numeric_state
+        entity_id: sensor.outside_air_temperature_fahrenheit
+        prob_given_true: 0.95
+        prob_given_false: 0.05
+        below: 50
+      - platform: numeric_state # line no longer needed - delete
+        entity_id: sensor.outside_air_temperature_fahrenheit # line no longer needed - delete
+        prob_given_true: 0.05 # line no longer needed - delete
+        prob_given_false: 0.95 # line no longer needed - delete
+        above: 50 # no longer needed - delete
+      - platform: state
+        entity_id: binary_sensor.house_occupied
+        prob_given_true: 0.3
+        prob_given_false: 0.05
+        to_state: "on"
+      - platform: state # line no longer needed - delete
+        entity_id: binary_sensor.house_occupied # line no longer needed - delete
+        prob_given_true: 0.7 # line no longer needed - delete
+        prob_given_false: 0.95 # line no longer needed - delete
+        to_state: "off" # line no longer needed - delete
+```
+
+To solve (2), you need to re-estimate your probabilities using this documentation - this will likely result in better performance in the long term.
+
+A hacky and *not recommended* workaround to restore your previous functionality would be to put in a mirrored entry for each observation where `prob_given_false` is equal to `prob_given_true`. This will induce the same behavior as before - the negative, counterfactual observation is essentially ignored. Be warned - this may break or cause errors in future versions and will not work for `template` or `numeric_state` observations. For templates, instead, make them return `None` where they would have returned `False` to induce Bayesian to ignore them.
+
+```yaml
+binary_sensor:
+  - name: "Heat On"
+    platform: bayesian
+    prior: 0.2
+    probability_threshold: 0.9
+    observations:
+      - platform: state
+        entity_id: binary_sensor.house_occupied
+        prob_given_true: 0.3
+        prob_given_false: 0.05
+        to_state: "on"
+      - platform: state # not 
+        entity_id: binary_sensor.house_occupied # not recommended
+        prob_given_true: 0.5 # not recommended
+        prob_given_false: 0.5 # not recommended
+        to_state: "off" # not recommended
+```
 
 ([@HarvsG] - [#67631]) ([documentation](/integrations/bayesian))