add to the docs (#144)

docs/examples/binomial.md

@@ -3,18 +3,28 @@ comments: true
 ---
 # Binomial Model 
 
+The [Binomial
+distribution](https://en.wikipedia.org/wiki/Binomial_distribution) models the
+number of successes in a fixed number of independent Bernoulli trials. The
+probability of success, $p$, is thought to be unknown and is estimated from the
+data.
+
+This example demonstrates how to fit a Binomial model with a Beta prior and
+compares the prior and posterior distributions as well as the predictive
+distributions with the true distribution of 
+
 ## Import modules
 
 Import the required distributions: 
 
-- `Binomial`: The assumed model likelihood
+- `Binomial`: The assumed model likelihood in order to generate synthetic data
 - `Beta`: Prior for `Binomial` distribution
-- `BetaBinomial`: The posterior predictive distribution
+- `BetaBinomial`: The predictive distribution for the `Binomial` model
 
 and the functions: 
 
-- `binomial_beta`: get the posterior distribution from data and prior
-- `binomial_beta_predictive`: get the posterior predictive
+- `binomial_beta`: get the posterior distribution from prior and data
+- `binomial_beta_predictive`: get the predictive distribution
 
 ```python 
 from conjugate.distributions import Beta, Binomial, BetaBinomial
@@ -37,14 +47,22 @@ X = true_dist.dist.rvs(size=1, random_state=42)
 
 ## Bayesian Inference
 
-Get the posterior and posterior predictive distributions
+### Posterior Distribution
+
+Get the posterior with `binomial_beta` using the sufficient statistics `n` and
+`x` and the prior distribution:
 
 ```python
-# Conjugate prior
 prior = Beta(alpha=1, beta=1)
 posterior: Beta = binomial_beta(n=N, x=X, prior=prior)
+```
 
-# Comparison
+### Predictive Distribution
+
+Get the predictive distribution for `n` new trials with
+`binomial_beta_predictive` function:
+
+```python
 prior_predictive: BetaBinomial = binomial_beta_predictive(
     n=N, 
     distribution=prior, 
@@ -57,13 +75,15 @@ posterior_predictive: BetaBinomial = binomial_beta_predictive(
 
 ## Additional Analysis
 
-Perform any analysis on the distributions
+Perform any analysis on the distributions to compare the prior and posterior as
+well as the predictive distributions with the true distribution.
 
 ```python
 
 # Figure 
 fig, axes = plt.subplots(ncols=2, nrows=1, figsize=(8, 4))
 
+# Prior and Posterior
 ax: plt.Axes = axes[0]
 posterior.plot_pdf(ax=ax, label="posterior")
 prior.plot_pdf(ax=ax, label="prior")
@@ -72,15 +92,14 @@ ax.axvline(x=true_dist.p, color="black", ymax=0.05, linestyle="--", label="True"
 ax.set_title("Success Rate")
 ax.legend()
 
+# Predictive Distributions & True Distribution
 ax: plt.Axes = axes[1]
 true_dist.plot_pmf(ax=ax, label="true distribution", color="C2")
 posterior_predictive.plot_pmf(ax=ax, label="posterior predictive")
 prior_predictive.plot_pmf(ax=ax, label="prior predictive")
 ax.axvline(x=X, color="black", ymax=0.05, label="Sample")
 ax.set_title("Number of Successes")
 ax.legend()
-
-plt.show()
 ```
 
 ![Binomial Model](../images/binomial-example.png)

docs/examples/generalized-inputs.md

@@ -5,9 +5,22 @@ comments: true
 
 Conjugate models work with anything that works like numbers. 
 
+Here are examples of the Binomial and Beta distributions with different
+packages data as input. For more details on this model, see the [Binomial Model
+example](./binomial.md).
+
+## Setup
+
+Import the `binomial_beta` model and the `Beta` distribution:
+
+```python
+from conjugate.distributions import Beta
+from conjugate.models import binomial_beta
+```
+
 ## Polars
 
-For instance, Bayesian models with the Polars package: 
+Bayesian models with the [Polars](https://docs.pola.rs/) package: 
 
 ```python
 import polars as pl
@@ -30,7 +43,8 @@ ax.legend(title="sample size")
 
 ## Models with SQL
 
-For instance, Bayesian models in SQL using the SQL Builder, [PyPika](https://github.com/kayak/pypika)
+Bayesian models in SQL using the SQL Builder,
+[PyPika](https://github.com/kayak/pypika):
 
 ```python
 from pypika import Field 
@@ -47,8 +61,11 @@ print("Posterior alpha:", posterior.alpha)
 print("Posterior beta:", posterior.beta)
 # Posterior alpha: 1+"successes"
 # Posterior beta: 1+"total"-"successes"
+```
 
-# Priors can be fields too
+Even the priors can be fields too:
+
+```python
 alpha = Field("previous_successes") - 1
 beta = Field("previous_failures") - 1
 
@@ -63,7 +80,8 @@ print("Posterior beta:", posterior.beta)
 
 ## PyMC
 
-Using PyMC distributions for sampling with additional uncertainty
+Use [PyMC](https://www.pymc.io/) distributions for sampling with additional
+uncertainty:
 
 ```python 
 import pymc as pm 

mkdocs.yml

@@ -78,3 +78,10 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences
+  - pymdownx.arithmatex: 
+      generic: true
+
+extra_javascript: 
+  - javascripts/mathjax.js
+  - https://polyfill.io/v3/polyfill.min.js?features=es6
+  - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js