From 989e7d830a9698e8a47f8292c1320cb12528370e Mon Sep 17 00:00:00 2001
From: Myrl <myrl@marmarel.is>
Date: Fri, 7 Jan 2022 15:09:21 -0800
Subject: [PATCH] more documentation

---
 Project.toml  |  2 +-
 README.md     | 27 +++++++++++++++++++++++++--
 src/parser.jl |  4 ++--
 3 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/Project.toml b/Project.toml
index f86c235..4bf3377 100644
--- a/Project.toml
+++ b/Project.toml
@@ -1,7 +1,7 @@
 name = "RankedChoices"
 uuid = "562810e1-8c0d-4830-9cc1-9c323639d9b1"
 authors = ["Myrl <myrl@marmarel.is>"]
-version = "0.1.0"
+version = "0.1.1"
 
 [compat]
 julia = "^1.5"
diff --git a/README.md b/README.md
index 1fd5683..2630b0f 100644
--- a/README.md
+++ b/README.md
@@ -16,7 +16,7 @@ Idealistically, our elections should run on this kind of algorithm. See this [bl
 ## Interface
 Here I detail how to parse rankings, handle the Gibbs sampler, and interpret the results. For instance,
 ```julia
-# (n_participants x ranking_size)
+# (n_respondents x ranking_size)
 rankings = [
   "B" "C" "D";
   "A" "D" "C";
@@ -65,4 +65,27 @@ Two simulation tactics are exposed: `RejectionSim` and `HamiltonianSim`. The ori
 The snazzy `HamiltonianSim(n_trajectories::Int, collision_limit::Int)` is much more complex, but converges quickly even on large rankings. You can set parameter `n_trajectories := 1` if you don't mind consecutive samples being correlated. Additionally, `collision_limit` can be set to a relatively high number like `128`. It determines how many times a ball can bounce between the walls of a linearly constrained Gaussian before we give up early.
 
 
-More details on the core methods coming (very) soon.
+### Conjugate Priors
+My sampler is Bayesian, and takes advantage of a number of conjugate priors. We typically seek to treat all cohorts and respondents equally a priori. Hence, I expose a method
+```julia
+prior = make_impartial_prior(n_total_candidates, n_cohorts;
+  precision_scale, precision_dof, mean_scale, dirichlet_weight)
+```
+where...
+* `precision_scale`, usually around or above unit, scales the diagonal matrix that parametrizes a Wishart prior for the precision matrix.
+* `precision_dof` sets the strength of the Wishart prior for influencing precision matrices.
+* `mean_scale`, which can stay unit, constrains the spread of the multivariate cohort means. In particular, it determines how much less the mean is spread out compared to the spread of the actual utilities.
+* `dirichlet_weight`, typically greater than unit, determines how strongly to favor cohorts of equal proportion
+
+
+### Sampler
+
+```julia
+result = simulate(prior, simulation, votes, n_trials;
+  n_burnin, seed, indifference=false, verbose=false)
+```
+
+The boolean flag `indifference` tells the sampler whether to treat incomplete rankings as implying that all unlisted candidates are lower than those listed (`indifference := false`) or not (`indifference := true`).
+
+
+More details on the core methods coming soon.
diff --git a/src/parser.jl b/src/parser.jl
index 220f91e..62fdd48 100644
--- a/src/parser.jl
+++ b/src/parser.jl
@@ -47,7 +47,7 @@ function read_prm_file(filename, N, R)
     padded_candidates = vcat(candidates, zeros(Int, R-n_choices))
     push!(rankings, RankedChoice{R}(padded_candidates))
   end
-  rankings
+  IssueVote(rankings, N)
 end
 
 using CSV, DataFrames
@@ -83,7 +83,7 @@ function parse_matrix(matrix::AbstractMatrix{String}, candidates::AbstractVector
   filtered_votes = filter(votes) do vote
     vote[1] != 0 # first entry can't be zero!! todo: ensure all other entries are zero too? if not, we could shift forward...
   end
-  filtered_votes, waste
+  IssueVote(filtered_votes, N), waste
 end
 
 function quantize(items::AbstractVector{S}, keys::AbstractVector{S}) where S