fix #6

R/hb_s_tau.R

@@ -1,7 +1,8 @@
-#' @title Suggest s_tau
+#' @title Superseded suggest s_tau given a uniform prior on tau.
 #' @export
-#' @family data
-#' @description Suggest a value of the `s_tau` hyperparameter
+#' @keywords internal
+#' @description For the uniform prior on tau,
+#'   suggest a value of the `s_tau` hyperparameter
 #'   to achieve a given amount of borrowing in the hierarchical model.
 #'   Only use if a diffuse prior on `tau` is not feasible.
 #' @details See the hierarchical model section of the

_pkgdown.yml

@@ -11,7 +11,6 @@ reference:
 - title: Data
   contents:
   - '`hb_data`'
-  - '`hb_s_tau`'
 - title: Simulate
   contents:
   - '`hb_sim_hierarchical`'

inst/WORDLIST

@@ -11,6 +11,7 @@ DQRDC
 et
 frac
 https
+commensurability
 ij
 ORCID
 lilly

vignettes/methods.Rmd

@@ -193,29 +193,7 @@ $$
 
 # Borrowing metrics
 
-## Mean shift ratio
-
-Let $\theta_m$ be the posterior mean control group response estimated by model $m$. The mean shift ratio is:
-
-$$
-\begin{aligned}
-\frac{\theta_{m*} - \theta_{\text{independent}}}{\theta_{\text{pool}} - \theta_{\text{independent}}}
-\end{aligned}
-$$
-
-where $m*$ is a historical borrowing model like the mixture model or hierarchical model.
-
-## Variance shift ratio
-
-Let $V_m$ be the estimated posterior variance of $\alpha_I$ (current study control group response mean) estimated by model $m$. The variance shift ratio is:
-
-$$
-\begin{aligned}
-\frac{V_{m*} - V_{\text{independent}}}{V_{\text{pool}} - V_{\text{independent}}}
-\end{aligned}
-$$
-
-where $m*$ is a historical borrowing model like the mixture model or hierarchical model.
+The package supports the following metrics to quantify borrowing.
 
 ## Precision ratio (hierarchical model only)
 
@@ -229,32 +207,31 @@ $$
 
 The precision ratio comes from the conditional distribution of $\alpha_k$ in the hierarchical model given the other parameters and the data. More precisely, in this conditional distribution, the mean is a weighted average between the prior mean and data mean, and the precision ratio is the weight on the prior mean. This can be seen in a simpler case with a Bayesian model with a normal data model, a normal prior on the mean, and known constant variance. For details, see Chapter 2 of [Bayesian Data Analysis](http://www.stat.columbia.edu/~gelman/book/) 3rd Ed. by Gelman et al.
 
-## Adjusting hierarchical borrowing strength using the prior
+## Variance shift ratio
 
-It is almost always best to set a diffuse prior on $\tau$ so that hierarchical borrowing is fully dynamic. However, in extreme cases (e.g. few historical studies, combined with other issues), there may not be enough information to precisely estimate a variance among placebo means in the hierarchical model, the function `hb_s_tau()` suggests a value of $s_\tau$ that assigns a desired prior precision ratio. if $P$ is the desired prior precision ratio, then:
+Let $V_m$ be the estimated posterior variance of $\alpha_I$ (current study control group response mean) estimated by model $m$. The variance shift ratio is:
 
 $$
 \begin{aligned}
-P = \frac{\frac{1}{\tau^2}}{\frac{1}{\tau^2} + \frac{n}{\sigma^2}}
+\frac{V_{m*} - V_{\text{independent}}}{V_{\text{pool}} - V_{\text{independent}}}
 \end{aligned}
 $$
 
-Solving for $\tau$:
+where $m*$ is a historical borrowing model like the mixture model or hierarchical model.
 
-$$
-\begin{aligned}
-\tau = \sigma \sqrt{\frac{1}{n} \left (\frac{1}{P} - 1 \right )}
-\end{aligned}
-$$
+## Mean shift ratio
+
+The mean shift ratio is not recommended to measure the strength of borrowing. Rather, it is an informal ad hoc measure of the lack of commensurability between the current and historical data sources.
 
-If we expect the mean of $\tau$ to be as above, then our uniform upper bound is double:
+To define the mean shift ratio, let $\theta_m$ be the posterior mean control group response estimated by model $m$. The mean shift ratio is:
 
 $$
 \begin{aligned}
-s_\tau = 2 \sigma \sqrt{\frac{1}{n} \left (\frac{1}{P} - 1 \right )}
+\frac{\theta_{m*} - \theta_{\text{independent}}}{\theta_{\text{pool}} - \theta_{\text{independent}}}
 \end{aligned}
 $$
 
+where $m*$ is a historical borrowing model like the mixture model or hierarchical model.
 
 ## Posterior mixture proportions (mixture model only)