docs

book/src/pcc/pred.md

@@ -18,10 +18,49 @@ Determining how certain the model is in its ability to capture a prediction is d
 
 Mathematically, uncertainty is formalized as the Jensen-Shannon divergence (JSD) between the state-level predictive distributions. Uncertainty goes from 0 to 1, 0 meaning that there is only one way to model a prediction, and 1 meaning that there are many ways to model a prediction and they all completely disagree.
 
-![Prediction uncertainty in unimodal data](prediction-uncertainty.png)
+<div class=tabbed-blocks>
 
-**Above.** Prediction uncertainty when predicting *Period_minutes* of a satellite in the satellites data set. Note that the uncertainty value here is driven mostly by the difference variances of the state-level predictive distributions.
+```python
+from lace import examples, plot
 
-Certain ignorance is when the model has zero data by which to make a prediction and instead falls back to the prior distribution. This is rare, but when it happens it will be apparent. To be as general as possible, the priors for a column's component distributions are generally much more broad than the predictive distribution, so if you see a predictive distribution that is senselessly wide and does not looks like the marginal distribution of that variable (which should follow the histogram of the data), you have a certain ignorance. The fix is to fill in the data for items similar to the one you are predicting.
+satellites = examples.Satellites()
+
+plot.prediction_uncertainty(
+  satellites,
+  "Period_minutes",
+  given={ "Class_of_Orbit": "GEO"}
+)
+```
+</div>
+
+{{#include html/sats-low-unc.html}}
+
+**Above.** Prediction uncertainty when predicting *Period_minutes* of a geosynchronous satellite in the satellites dataset. Uncertainty is low. Though the stat distributions differ slightly in their variance, they're relatively close, with similar means.
+
+To visualize a higher uncertainty prediction, well use `given` conditions from a record with a know data entry error.
+
+<div class=tabbed-blocks>
 
+```python
+given = sats["Intelsat 902", :].to_dicts()[0]
 
+# remove all missing data
+given = { k: v for k, v in given.items() if not pd.isnull(v) }
+
+# remove the index and the target value
+_ = row.pop("index")
+_ = row.pop("Period_minutes")
+
+plot.prediction_uncertainty(
+  satellites,
+  "Period_minutes",
+  given=given
+)
+```
+</div>
+
+{{#include html/sats-high-unc.html}}
+
+**Above.** Prediction uncertainty when predicting *Period_minutes* of Intelsat 902. Though the mean predictive distribution (black line) has a relatively low variance, there is a lot of disagreement between some of the samples, leading to high epistemic uncertainty.
+
+Certain ignorance is when the model has zero data by which to make a prediction and instead falls back to the prior distribution. This is rare, but when it happens it will be apparent. To be as general as possible, the priors for a column's component distributions are generally much more broad than the predictive distribution, so if you see a predictive distribution that is senselessly wide and does not looks like the marginal distribution of that variable (which should follow the histogram of the data), you have a certain ignorance. The fix is to fill in the data for items similar to the one you are predicting.

pylace/lace/__init__.py

@@ -35,3 +35,5 @@
     "CountPrior",
     "ValueMap",
 ]
+
+__version__ = "0.5.1"