add some tex to docstrings

millipede/normal.py

@@ -12,11 +12,49 @@
 
 
 class NormalLikelihoodSampler(MCMCSampler):
-    """
+    r"""
     MCMC sampler for Bayesian variable selection for a linear model with a Normal likelihood.
     The likelihood variance is controlled by a Inverse Gamma prior.
     This class supports continuous-valued responses.
 
+    The covariates :math:`X` and responses :math:`Y` are defined as follows:
+
+    .. math::
+
+        X \in \mathbb{R}^{N \\times P} \qquad \qquad Y \in \mathbb{R}^{N}
+
+    The inclusion of each covariate is governed by a Bernoulli random variable :math:`\gamma_p`.
+    In particular :math:`\gamma_p = 0` corresponds to exclusion and :math:`\gamma_p = 1` corresponds to inclusion.
+    The prior probability of inclusion is governed by :math:`h` or alternatively :math:`S`:
+
+    .. math::
+
+        h \in [0, 1] \qquad \\rm{with} \qquad S \equiv hP
+
+    Putting this together, the model specification for an isotopric prior (with an intercept
+    :math:`\\beta_0` included) is as follows:
+
+    .. math::
+
+        &\gamma_p \sim \\rm{Bernoulli}(h) \\qquad \\rm{for} \\qquad p=1,2,...,P
+
+        &\\sigma^2 \sim \\rm{InverseGamma}(\\nu_0 / 2, \\nu_0 \\lambda_0 / 2)
+
+        &\\beta_0 \sim \\rm{Normal}(0, \\sigma^2\\tau_\\rm{intercept}^{-1})
+
+        &\\beta_\gamma \sim \\rm{Normal}(0, \\sigma^2 \\tau^{-1} \\mathbb{1}_\\gamma)
+
+        &Y_n \sim \\rm{Normal}(X_{n, \\gamma} \cdot \\beta_\gamma, \\sigma^2)
+
+    Note that the dimension of :math:`\\beta_\gamma` depends on the number of covariates
+    included in a particular model (i.e. on the number of non-zero entries in :math:`\gamma`).
+
+    For a gprior the prior over the coefficients is instead specified as follows:
+
+    .. math::
+
+        \\beta_{\gamma} \sim \\rm{Normal}(0, c \\sigma^2 (X_\\gamma^{\\rm{T}} X_\\gamma)^{-1})
+
     Usage of this class is only recommended for advanced users. For most users it should
     suffice to use :class:`NormalLikelihoodVariableSelector`.
 

millipede/selection.py

@@ -21,9 +21,9 @@ def populate_weight_stats(stats, weights, quantiles=[5.0, 10.0, 20.0, 50.0, 90.0
 
 
 class NormalLikelihoodVariableSelector(object):
-    """
+    r"""
     Bayesian variable selection for a linear model with a Normal likelihood.
-    The likelihood variance is controlled by a Inverse Gamma prior.
+    The likelihood variance is controlled by an Inverse Gamma prior.
     This class is appropriate for continuous-valued responses.
 
     Usage::
@@ -32,6 +32,50 @@ class NormalLikelihoodVariableSelector(object):
         selector.run(T=2000, T_burnin=1000)
         print(selector.summary)
 
+    The details of the model used in `NormalLikelihoodVariableSelector` are as follows.
+    The covariates :math:`X` and responses :math:`Y` are defined as follows:
+
+    .. math::
+
+        X \in \mathbb{R}^{N \\times P} \qquad \qquad Y \in \mathbb{R}^{N}
+
+    The inclusion of each covariate is governed by a Bernoulli random variable :math:`\gamma_p`.
+    In particular :math:`\gamma_p = 0` corresponds to exclusion and :math:`\gamma_p = 1` corresponds to inclusion.
+    The prior probability of inclusion is governed by :math:`h` or alternatively :math:`S`:
+
+    .. math::
+
+        h \in [0, 1] \qquad \\rm{with} \qquad S \equiv hP
+
+    Putting this together, the model specification for an isotopric prior (with an intercept
+    :math:`\\beta_0` included) is as follows:
+
+    .. math::
+
+        &\gamma_p \sim \\rm{Bernoulli}(h) \\qquad \\rm{for} \\qquad p=1,2,...,P
+
+        &\\sigma^2 \sim \\rm{InverseGamma}(\\nu_0 / 2, \\nu_0 \\lambda_0 / 2)
+
+        &\\beta_0 \sim \\rm{Normal}(0, \\sigma^2\\tau_\\rm{intercept}^{-1})
+
+        &\\beta_\gamma \sim \\rm{Normal}(0, \\sigma^2 \\tau^{-1} \\mathbb{1}_\\gamma)
+
+        &Y_n \sim \\rm{Normal}(X_{n, \\gamma} \cdot \\beta_\gamma, \\sigma^2)
+
+    Note that the dimension of :math:`\\beta_\gamma` depends on the number of covariates
+    included in a particular model (i.e. on the number of non-zero entries in :math:`\gamma`).
+    The hyperparameters :math:`\\nu_0` and :math:`\\lambda_0` govern the prior over
+    :math:`\\sigma^2`. The default choice :math:`\\nu_0=\\lambda_0=0` corresponds to an
+    improper prior :math:`p(\sigma^2) \propto 1/\\sigma^2`.
+
+    For a gprior the prior over the coefficients is instead specified as follows:
+
+    .. math::
+
+        \\beta_{\gamma} \sim \\rm{Normal}(0, c \\sigma^2 (X_\\gamma^{\\rm{T}} X_\\gamma)^{-1})
+
+    where :math:`c > 0` is a user-specified hyperparameter.
+
     :param DataFrame dataframe: A `pandas.DataFrame` that contains covariates and responses. Each row
         encodes a single data point. All columns apart from the response column are assumed to be covariates.
     :param str response_column: The name of the column in `dataframe` that contains the continuous-valued responses.