From 1cf5f573c4287c65b86c707cba22634e6cb2eb24 Mon Sep 17 00:00:00 2001
From: Mario beraha <berahamario@gmail.com>
Date: Fri, 19 Apr 2024 17:28:29 +0200
Subject: [PATCH] adding docs

---
 src/hierarchies/betagg_hierarchy.h             | 15 +++++++++++++++
 src/hierarchies/likelihoods/beta_likelihood.cc |  8 --------
 src/hierarchies/likelihoods/beta_likelihood.h  |  2 --
 src/hierarchies/priors/gamma_gamma_prior.h     |  5 +++++
 src/proto/distribution.proto                   |  6 +++++-
 src/proto/hierarchy_prior.proto                |  2 +-
 src/proto/ls_state.proto                       |  5 ++++-
 7 files changed, 30 insertions(+), 13 deletions(-)

diff --git a/src/hierarchies/betagg_hierarchy.h b/src/hierarchies/betagg_hierarchy.h
index eca263a7f..c2e487679 100644
--- a/src/hierarchies/betagg_hierarchy.h
+++ b/src/hierarchies/betagg_hierarchy.h
@@ -8,7 +8,22 @@
 #include "updaters/random_walk_updater.h"
 
 /**
+ * Beta Gamma-Gamma hierarchy for univaraite data in [0, 1]
  *
+ * This class represents a hierarchical model where data are distributed
+ * according to a Beta likelihood (see the `BetaLikelihood` class for
+ * details). The shape and rate parameters of the likelihood have
+ * independent gamma priors. That is
+ *
+ * \f[
+ *    f(x_i \mid \alpha, \beta) &= Beta(\alpha, \beta) \\
+ *    \alpha &\sim Gamma(\alpha_a, \alpha_b) \\
+ *    \beta &\sim Gamma(\beta_a, \beta_b)
+ * \f]
+ *
+ * The state is composed of shape and rate. Note that this hierarchy
+ * is NOT conjugate, meaning that the marginal distribution is not available
+ * in closed form.
  */
 
 class BetaGGHierarchy
diff --git a/src/hierarchies/likelihoods/beta_likelihood.cc b/src/hierarchies/likelihoods/beta_likelihood.cc
index ff998cfe3..ddd08df13 100644
--- a/src/hierarchies/likelihoods/beta_likelihood.cc
+++ b/src/hierarchies/likelihoods/beta_likelihood.cc
@@ -4,14 +4,6 @@ double BetaLikelihood::compute_lpdf(const Eigen::RowVectorXd &datum) const {
   return stan::math::beta_lpdf(datum(0), state.shape, state.rate);
 }
 
-// Eigen::VectorXd BetaLikelihood::sample() const {
-//   Eigen::VectorXd out(1);
-//   auto &rng = bayesmix::Rng::Instance().get();
-//   out(0) = stan::math::beta_rng(state.shape, state.rate, rng);
-//   out = out.cwiseMin(1.0 - 1e-8).cwiseMax(1e-8);
-//   return out;
-// }
-
 void BetaLikelihood::update_sum_stats(const Eigen::RowVectorXd &datum,
                                       bool add) {
   double x = datum(0);
diff --git a/src/hierarchies/likelihoods/beta_likelihood.h b/src/hierarchies/likelihoods/beta_likelihood.h
index 8feba0452..d99a2aa84 100644
--- a/src/hierarchies/likelihoods/beta_likelihood.h
+++ b/src/hierarchies/likelihoods/beta_likelihood.h
@@ -30,8 +30,6 @@ class BetaLikelihood
   bool is_dependent() const override { return false; };
   void clear_summary_statistics() override;
 
-  // Eigen::VectorXd sample() const override;
-
   template <typename T>
   T cluster_lpdf_from_unconstrained(
       const Eigen::Matrix<T, Eigen::Dynamic, 1> &unconstrained_params) const {
diff --git a/src/hierarchies/priors/gamma_gamma_prior.h b/src/hierarchies/priors/gamma_gamma_prior.h
index 375cf61b1..9ce995771 100644
--- a/src/hierarchies/priors/gamma_gamma_prior.h
+++ b/src/hierarchies/priors/gamma_gamma_prior.h
@@ -10,6 +10,11 @@
 #include "hyperparams.h"
 #include "src/utils/rng.h"
 
+/*
+ * Prior model for `ShapeRate` states.
+ * This class assumes that the shape and rate are independent and given
+ * Gamma-distributed priors
+ */
 class GGPriorModel
     : public BasePriorModel<GGPriorModel, State::ShapeRate, Hyperparams::GG,
                             bayesmix::GGPrior> {
diff --git a/src/proto/distribution.proto b/src/proto/distribution.proto
index 81db3ffc8..785e2f3ae 100644
--- a/src/proto/distribution.proto
+++ b/src/proto/distribution.proto
@@ -96,9 +96,13 @@ message MultiNormalIGDistribution {
   double scale = 4;
 }
 
+/*
+ * Parameters for the product of two independent Gamma distributions with different
+ * rates and shapes
+ */
 message GamGamDistribution {
   double a_shape = 1;
   double a_rate = 2;
   double b_shape = 3;
   double b_rate = 4;
-}
\ No newline at end of file
+}
diff --git a/src/proto/hierarchy_prior.proto b/src/proto/hierarchy_prior.proto
index 19062a639..7722e29c3 100644
--- a/src/proto/hierarchy_prior.proto
+++ b/src/proto/hierarchy_prior.proto
@@ -131,4 +131,4 @@ message GGPrior {
   oneof prior {
     GamGamDistribution fixed_values = 1;
   }
-}
\ No newline at end of file
+}
diff --git a/src/proto/ls_state.proto b/src/proto/ls_state.proto
index ed09522a1..6794185c5 100644
--- a/src/proto/ls_state.proto
+++ b/src/proto/ls_state.proto
@@ -38,7 +38,10 @@ message FAState {
   Matrix lambda = 4;
 }
 
+/*
+ * Parameters of a shape-rate state, used, e.g., by the BetaLikelihood
+ */
 message SRState {
   double shape = 1;
   double rate = 2;
-}
\ No newline at end of file
+}