From 360aceb94d1fc23cbdca8209d99a29de27337b97 Mon Sep 17 00:00:00 2001
From: Romeo Valentin <romeov@stanford.edu>
Date: Wed, 22 May 2024 17:09:32 -0700
Subject: [PATCH] Add Readme v1.

---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 47 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..e5ff13a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,47 @@
+# ProbabilisticParameterEstimators.jl
+
+Implementation of different parameter estimators that take in measures under uncertainty and produce a probability distribution over the parameters.
+
+## High Level Example
+
+``` julia
+# observation function with multivariate observations
+f(x, p) = [(x + 1)^2 - sum(p);
+           (x + 1)^3 + diff(p)[1]]
+
+# true parameter (to be estimated) and a prior belief
+θtrue = [1.0, 2.0]
+prior = MvNormal(zeros(2), 4.0 * I)
+
+# observation noise
+obsnoises = [rand()/10 * I(2) * MvNormal(zeros(2), I) for _ in eachindex(xs)]
+noisemodel = UncorrGaussianNoiseModel(obsnoises)
+
+# noisy observations x and y
+xs = rand(5)
+ysmeas = f.(xs, [θtrue]) .+ rand.(noises)
+
+# find a probabilistic description of θ either as samples or as a distribution
+# currently we provide three methods
+for est in [MCMCEstimator(prior, f),
+            LinearApproxEstimator(prior, f),
+            LSQEstimator(prior, f)]
+    # either
+    samples =  predictsamples(est, xs, ysmeas, noisemodel, 100)
+    # or
+    dist    =  predictdist(est, xs, ysmeas, noisemodel; nsamples=100)
+end
+```
+
+## Problem Setup
+We assume parameters $\theta$ in $\mathbb{R}^m$, inputs $x$ in $\mathbb{R}^n$, and measurements $y$ in $\mathbb{R}^l$, linked by a observation function $$y = f(x, \theta) + \varepsilon$$ where $\varepsilon$ is sampled from a known noise distribution $p_{\bar{\varepsilon}}$.
+Further assumptions of the noise models are discussed below.
+Notice also that $x$, $y$, and $theta$ may all be multidimensional, with different dimensions.
+
+Given that we have uncertainty in the observations, we are interested in constructing a probabilistic description $p_{\bar{\theta}}(\theta \mid y)$ of the parameters $\theta$, either as a distribution, or as a set of samples.
+We implement three estimators for this task, which map to either samples or a distribution via `predictsamples(est, xs, ys, noisemodel, nsamples)` and `predictdist(est, xs, ys, noisemodel)`, respectively.
+The conversion between samples and a distribution can be done automatically via sampling or fitting a multivariate normal distribution.
+
+[<img src="figs/distribution_graph/distribution_graph.png">](Estimator Overview)
+
+###